timbal: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Development and Testing

• Install dependencies: uv sync --dev (from repo root — pyproject.toml is at root)
• Run all tests: uv run pytest (from repo root)
• Run single test: uv run pytest python/tests/core/test_agent.py::TestClass::test_method
• Linting: uv run ruff check
• Format: uv run ruff format
• Fix lint: uv run ruff check --fix
• Line length: 120 chars (configured in pyproject.toml)

Benchmarks

• LangGraph benchmarks: uv pip install -r benchmarks/langchain/requirements.txt, then uv run --no-sync python benchmarks/langchain/bench_agent.py (or the other standalone bench_*.py scripts). JavaScript dependencies: npm ci --prefix benchmarks/langgraph_js.
• Quick mode: pass --quick; full mode is the default. bench_revision.py emits repeated-comparison samples as JSON.
• Current agent API: bench_agent.py --agent-api current benchmarks langchain.agents.create_agent; the default retains legacy create_react_agent for historical comparisons. Keep the same environment/harness and switch only PYTHONPATH when comparing Timbal revisions.

Repository Layout

timbal/
├── python/
│   ├── timbal/               # Main package
│   │   ├── __init__.py       # Top-level exports: Agent, Workflow
│   │   ├── core/
│   │   │   ├── runnable.py   # Base class for all executable components
│   │   │   ├── agent.py      # Agent execution engine
│   │   │   ├── workflow.py   # DAG workflow engine
│   │   │   ├── tool.py       # Tool wrapper
│   │   │   ├── tool_set.py   # ToolSet ABC for runtime tool resolution
│   │   │   ├── mcp.py        # MCPServer — MCP servers as tool sources
│   │   │   ├── llm/          # Multi-provider LLM dispatch (router, registry, clients, retry + one module per API)
│   │   │   ├── models.py     # Model strings + context window lookup
│   │   │   └── test_model.py # Offline TestModel for testing
│   │   ├── state/
│   │   │   ├── __init__.py   # get_run_context, get_call_id, etc.
│   │   │   ├── context.py    # RunContext definition
│   │   │   ├── background.py # Session-scoped background-task store
│   │   │   └── tracing/
│   │   │       ├── providers/
│   │   │       │   ├── base.py       # TracingProvider ABC + Exporter ABC
│   │   │       │   ├── in_memory.py  # Default in-memory provider
│   │   │       │   ├── jsonl.py      # JSONL file provider
│   │   │       │   └── platform.py   # Timbal platform provider
│   │   │       └── exporters/
│   │   │           └── otel.py       # OTelExporter (fire-and-forget OTLP/HTTP)
│   │   ├── types/
│   │   │   ├── message.py    # Message with role + content list
│   │   │   ├── file.py       # File type with auto content detection
│   │   │   ├── content/      # TextContent, ToolUseContent, FileContent, etc.
│   │   │   └── events/       # StartEvent, DeltaEvent, OutputEvent
│   │   ├── collectors/       # Output processing; TimbalCollector is default
│   │   └── tools/            # Built-in tool library (Bash, Slack, Gmail, etc.)
│   └── tests/
│       └── core/             # Test files mirroring package structure
├── benchmarks/
│   ├── README.md             # General benchmark guide
│   └── langchain/            # Timbal vs LangChain/LangGraph benchmarks
├── planning/                 # In-progress feature plans (gitignored)
└── pyproject.toml            # Root package config + dev deps