# CLAUDE.md — pureagents

## Philosophy

**Powerful, but simple. Many features ≠ complicated.**

Most agent frameworks are over-engineered. Thousands of lines, dozens of abstractions, patterns on patterns. You end up fighting the framework instead of building your product.

pureagents is different:

- **Powerful** — All the features you need: tools, streaming, memory, structured outputs, hooks, batch, retry, cost tracking
- **Simple** — ~800 lines. Read the entire codebase in 30 minutes
- **Elegant** — Clean API. One decorator, one class. No magic
- **Buildable** — Fork it, modify it, build on top. Not a black box

### Core principles

1. **Read** — Understand the entire codebase in 30 minutes
2. **Copy** — Fork and modify, don't depend on upstream updates
3. **Build** — Base for your own implementation, not a black box

### Design rules

- Every feature is **optional** and **modular**
- One parameter = one feature (e.g., `retries=3`)
- No magic. If something happens, you can see why
- No abstractions for abstraction's sake
- No hidden behaviour

## Project structure

```
pureagents/
├── src/pure_agents/      # Main package (~800 lines total)
│   ├── __init__.py       # Public exports
│   ├── agent.py          # Agent class with run/stream/batch
│   ├── clients.py        # LLM providers (Mistral, OpenAI, Anthropic)
│   ├── memory.py         # Memory abstraction + JSONMemory
│   ├── message.py        # Message dataclass
│   └── tool.py           # @tool decorator
├── examples/             # Working examples
├── docs/                 # Docusaurus documentation
└── pyproject.toml
```

## Features

| Feature | Parameter/Usage |
|---------|-----------------|
| Tools | `@tool` decorator |
| Providers | `provider="openai"` |
| Streaming | `agent.stream()` |
| Memory | `session="my-chat"` |
| Structured outputs | `output=MyDataclass` |
| Hooks | `on_tool_call=fn` |
| Templates | `template="coder"` |
| Batch | `agent.batch([...])` |
| Retry | `retries=3` |
| Timeout | `timeout=30.0` |
| Context limit | `max_messages=20` |
| Usage tracking | `agent.usage` |

## Documentation

Docs are built with Docusaurus and live in `docs/`.

### Running locally

```bash
cd docs
npm install
npm run dev
```

### Updating docs when adding features

1. **Update API reference** in `docs/docs/api/`
2. **Add guide** in `docs/docs/guides/` if the feature needs explanation
3. **Update quickstart** if it's a core feature
4. **Update homepage** if it's a major feature
5. **Add example** in `examples/`
6. **Keep examples minimal** — show simplest usage

### Style guidelines

- British English, sentence case
- Code examples should be copy-pasteable
- Keep explanations concise
- No corporate jargon

## Code style

- Python 3.10+, type hints everywhere
- Minimal dependencies (httpx only)
- async/await by default
- ruff for formatting
- ~88 char line limit
