ACS Agent

AI-powered assistant for exploring and downloading data from the U.S. Census American Community Survey (ACS). The package bundles an Anthropic Claude chat agent with a fully async ACS API client and command-line tools.

Features

• Conversational agent that can search tables, explain variables, and download data with tool calls.
• Async ACS client with caching, geography resolution, and rate limiting.
• CLI utilities for direct table/variable downloads without the chat layer.
• Usage tracking with token cost estimates for the chat agent.

Requirements

• Python 3.10+
• Environment variables:
  • ANTHROPIC_API_KEY (required for the chat agent)
  • CENSUS_API_KEY (optional, raises Census API rate limits)
  • ACS_CACHE_PATH (optional, custom cache directory for metadata)

Installation

cd acs_agent
pip install -e .

Usage

Chat agent

Interactively ask for tables, quick stats, or downloads:

acs-agent
# or
acs-agent --query "Download median household income for Michigan"

Direct ACS access CLI

Use the client without the chat layer:

acs-access download-table B01001 --state Michigan --year 2022 --output ./data
acs-access search-tables "median income" --year 2024
acs-access download-variables B01003_001E B19013_001E --state CA --year 2023

Python API

import asyncio

from acs_agent import ACSAgent, ACSDataAgent, ACSClient


async def main():
    # Chat agent
    agent = ACSAgent()
    response = await agent.chat("Find tables about education in Ohio")
    print(response)

    # Simple synchronous wrapper
    data_agent = ACSDataAgent()
    print(data_agent.execute("Download B01003 for California"))

    # Direct client usage
    async with ACSClient() as client:
        result = await client.download_table("B01001", {"state": "Michigan"}, year=2024, output_dir="./data")
        if result.success:
            print("Saved to", result.file_path)


asyncio.run(main())

Development

• Install dev tools: pip install -e .[dev]
• Run formatting/linting: ruff check . and black .
• Run tests (if added): pytest

License

MIT License. See LICENSE for details.

Credits

This code is built off work from @Night-Mode's acs AI query tool. Thanks for the inspiration!

99% of this code was written with the help of Claude Code, Codex, and Cursor.