Environment Variables and API Keys

Complete reference for all environment variables used by congress-approp. No API keys are needed to query pre-extracted example data — keys are only required for downloading new bills, extracting provisions, or using semantic search.

API Keys

Setting API Keys

Set keys in your shell before running commands:

export CONGRESS_API_KEY="your-congress-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENAI_API_KEY="your-openai-key"

To persist across sessions, add the export lines to your shell profile (~/.bashrc, ~/.zshrc, or equivalent).

Testing API Keys

Verify that your Congress.gov and Anthropic keys are working:

congress-approp api test

There is no built-in test for the OpenAI key — the embed command will fail with a clear error message if the key is missing or invalid.

Configuration Variables

Setting the Model Override

# Use a different model for all extractions in this session
export APPROP_MODEL="claude-sonnet-4-20250514"
congress-approp extract --dir data/118/hr/9468

# Or override per-command with the flag (takes precedence over env var)
congress-approp extract --dir data/118/hr/9468 --model claude-sonnet-4-20250514

Quality note: The system prompt and expected output format are specifically tuned for Claude Opus. Other models may produce lower-quality extractions. Always check audit output after extracting with a non-default model.

Which Keys Do I Need?

Querying pre-extracted data (no keys needed)

These commands work with the included data/ data and any previously extracted bills — no API keys required:

congress-approp summary --dir data
congress-approp search --dir data --type appropriation
congress-approp search --dir data --keyword "Veterans"
congress-approp audit --dir data
congress-approp compare --base data/118-hr4366 --current data/118-hr9468
congress-approp upgrade --dir data --dry-run

Semantic search (OPENAI_API_KEY only)

Semantic search requires one API call to embed your query text (~100ms, costs fractions of a cent):

export OPENAI_API_KEY="your-key"
congress-approp search --dir data --semantic "school lunch programs" --top 5

The --similar flag does not require an API key — it uses pre-computed vectors stored locally:

# No API key needed for --similar
congress-approp search --dir data --similar 118-hr9468:0 --top 5

Downloading bills (CONGRESS_API_KEY only)

export CONGRESS_API_KEY="your-key"
congress-approp download --congress 118 --type hr --number 9468 --output-dir data
congress-approp api bill list --congress 118 --enacted-only

Extracting provisions (ANTHROPIC_API_KEY only)

export ANTHROPIC_API_KEY="your-key"
congress-approp extract --dir data/118/hr/9468

Generating embeddings (OPENAI_API_KEY only)

export OPENAI_API_KEY="your-key"
congress-approp embed --dir data/118/hr/9468

Full pipeline (all three keys)

export CONGRESS_API_KEY="your-congress-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENAI_API_KEY="your-openai-key"

congress-approp download --congress 118 --enacted-only --output-dir data
congress-approp extract --dir data --parallel 6
congress-approp embed --dir data
congress-approp summary --dir data

Error Messages

Security Best Practices

• Never hardcode API keys in scripts, configuration files checked into version control, or command-line arguments (which may be logged in shell history).

• Use environment variables as shown above, or source them from a file that is not checked into version control:

  # Create a file (add to .gitignore!)
  echo 'export CONGRESS_API_KEY="your-key"' > ~/.congress-approp-keys
  echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.congress-approp-keys
  echo 'export OPENAI_API_KEY="your-key"' >> ~/.congress-approp-keys
  
  # Source before use
  source ~/.congress-approp-keys
  congress-approp extract --dir data
  

• Rotate keys periodically, especially if they may have been exposed.

• Use separate keys for development and production if your organization supports it.

Cost Estimates

The tool tracks token usage but never displays dollar costs. Here are approximate costs for reference:

Extraction (Anthropic)

Token usage is recorded in tokens.json after extraction. Use extract --dry-run to preview token counts before committing.

Embeddings (OpenAI)

Semantic Search (OpenAI)

Each --semantic query makes one API call to embed the query text: approximately $0.0001 per search.

The --similar flag uses stored vectors and makes no API calls — completely free after initial embedding.

Summary

Next Steps

• Installation — getting started with the tool
• Extract Your Own Bill — the full pipeline tutorial
• CLI Command Reference — complete reference for all commands and flags