agent/README.md

# Agent App

## Run the UI

```bash
cd /Users/binx/Desktop/Goon/agent
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app/app.py
```

Set your Anthropic key in `agent/.env`:

```bash
ANTHROPIC_API_KEY=your_key_here
```

Or paste it into the sidebar after the app starts.

## Local Python API

This repo does not expose an HTTP API server. The supported programmatic interface is the local Python function in `analysis.agent`.

### Basic usage

```python
from analysis.agent import run_agent

result = run_agent("How many posts per subreddit?")
print(result["answer"])
print(result["tool_calls"])
```

### With prior context

```python
from analysis.agent import run_agent

turns = [
    {
        "question": "How many posts per subreddit?",
        "answer": "Previous answer text",
        "tool_calls": [],
        "artifacts": [],
        "plotly_json": "",
        "route": "describe",
    }
]

result = run_agent(
    "Which subreddits changed most over time?",
    turns=turns,
)
print(result["route"])
print(result["answer"])
```

## Return shape

`run_agent(...)` returns a dictionary with:

- `answer`: final assistant response
- `tool_calls`: executed tool calls plus arguments and results
- `plotly_json`: chart payload when a plot was generated
- `route`: detected route for the question
- `allowed_tools`: tools exposed for that route

## Notes

- Use `python3`, not `python`, in this environment.
- The app stores structured turn state in the Streamlit session so follow-up questions can reuse prior analytical context.
- Generated CSV and PNG artifacts are written to `agent/outputs/`.