Building AI agents, atomically
Map the observability package, Phoenix example and forge context propagation
Eigenwiseffca7a311919
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.jsonindex 52efcd4..9ef7c2c 100644--- a/.claude/.codebase-info/.map-state.json+++ b/.claude/.codebase-info/.map-state.json@@ -1,9 +1,9 @@{"schemaVersion": 1,"tool": "codebase-mapper",- "version": "2.14.4",- "mappedAt": "2026-08-11",- "gitCommit": "c80c7520a703018d36abc97f2199dcaf3d9c29a3",+ "version": "2.15.10",+ "mappedAt": "2026-10-15",+ "gitCommit": "4801bcfcd92ed3f36ea4d3e8213413de147f6f3a","documents": ["architecture.md","coding-style.md",@@ -17,14 +17,14 @@"tech-landscape.md"],"hashes": {- "INDEX.md": "50e7beb7784d3d01f8ce0e85b842889f5c033ca98cbb30981fd0b532c1495c8f",- "architecture.md": "8e6be8d2795231ea5919d7cdc23a201595f9fed9724b635e6cc686b2bf24581f",+ "INDEX.md": "40401c94518aebe4bf68dfffb3ea6f8d7e4ce873930a2a87e3e3d7533439358e",+ "architecture.md": "59d1265c89d3b42671b7c47165408625018537c016a72df421113cae3f80bb70","coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",- "communication.md": "6c73cad50151b73a6be63c8f0745d3f7a6653a861d37afce660c512ac30b8819",- "dependencies.md": "b445a920c121e27006fec824add6865d01cf71212a517e5ff8b2058d3999037a",- "directory-structure.md": "ca200817789c4d1fdc41d1683c37740c9837bf323b18881cb2351ef8a56c4926",- "entry-points.md": "62fd8ff478fc27c3658776626059bdd4101cab12a74a48cdd8787f9ca7b83f97",- "modules.md": "7a8772e5f31be0070003c9a7ce78eca5df95dfb6a1c9dd471a6be97df81084aa",+ "communication.md": "7cf34aaf643a8bfc6dfeb1f0ec070121c76c76859dbd6377f815bf21e0c29c3b",+ "dependencies.md": "837fe41809eb2753be100ae244fec53423846867b16d91471ec3b5ae03f74e90",+ "directory-structure.md": "31ea7434131d4e3529948b174d7f009838cfe46a71f1f9470703f3b3010c74af",+ "entry-points.md": "3c94fd8a821fc76789794b6d3f4d89cc88a7903055755d97437f9f3ca6193cb6",+ "modules.md": "cfe0b05069039074e488880093844fc1cdcabd01ee4c80de08ca7c86492a8e0b","onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e","patterns.md": "f3a339a7bc711c4586062139d135e1d79129653cf82fc430cd256028d25e2dcc","tech-landscape.md": "700b3ba7bb5e47ec14086e2b94ad65ad956c0bfbe1c463f96c39493143e0c912"diff --git a/.claude/.codebase-info/INDEX.md b/.claude/.codebase-info/INDEX.mdindex cbf4927..03ec62d 100644--- a/.claude/.codebase-info/INDEX.md+++ b/.claude/.codebase-info/INDEX.md@@ -1,12 +1,12 @@# Codebase Map — Atomic Agents-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-15*Atomic Agents is a lightweight, modular Python framework for building agentic AI applications ascomposable, schema-driven building blocks (built on Instructor + Pydantic). This repository is a`uv`-workspace **monorepo**: the core framework, a TUI tool installer, a tool library, and examples.-**Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling · Pyright · `VideoURL` multimodal content+**Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling · Pyright · `VideoURL` multimodal content · optional OpenInference tracing (Phoenix)**Shape:** Monorepo — `atomic-agents/` (core lib) · `atomic-assembler/` (CLI) · `atomic-forge/` (tools) · `atomic-examples/` (examples)**Package:** `atomic-agents` v2.10.3 on PyPI · core import package is `atomic_agents`diff --git a/.claude/.codebase-info/architecture.md b/.claude/.codebase-info/architecture.mdindex 9cc9cbd..4db0b97 100644--- a/.claude/.codebase-info/architecture.md+++ b/.claude/.codebase-info/architecture.md@@ -1,6 +1,6 @@# Architecture-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-15*## Summary@@ -50,6 +50,7 @@ Tool install (atomic-assembler TUI):| Context | `atomic-agents/atomic_agents/context/` | `SystemPromptGenerator`, `BaseDynamicContextProvider`, `BaseChatHistory` (pluggable memory contract) + `ChatHistory` with Instructor media and `VideoURL` || Connectors | `atomic-agents/atomic_agents/connectors/mcp/` | Model Context Protocol tools / resources / prompts || Utils | `atomic-agents/atomic_agents/utils/` | Token counting (LiteLLM), tool-message formatting |+| Observability (opt-in) | `atomic-agents/atomic_agents/observability/` | OpenInference AGENT/TOOL spans for Phoenix / OpenTelemetry; `observability` extra + `openinference_instrumentor` entry point || Assembler (CLI) | `atomic-assembler/atomic_assembler/` | Textual TUI to fetch/install forge tools || Forge (tools) | `atomic-forge/tools/` | 13 standalone tools, each `BaseTool`-based |diff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.mdindex 86aa7b8..8a3b4a8 100644--- a/.claude/.codebase-info/communication.md+++ b/.claude/.codebase-info/communication.md@@ -1,6 +1,6 @@# Communication & Integrations-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-15*The framework exposes no HTTP API of its own; "communication" here means how it talks to LLMproviders and external tools.@@ -33,6 +33,14 @@ providers and external tools.- Built on Instructor's hook system: `register_hook(event, handler)`, `unregister_hook`,`clear_hooks`. Events include `parse:error`, `completion:kwargs`, `completion:response`,`token:counted`. See the `hooks-example` example and `docs/guides/hooks.md`.+- OpenInference tracing (`atomic_agents.observability`, optional `observability` extra): an AGENT span per+ `AtomicAgent` run and a TOOL span per `BaseTool` run, auto-activated by `phoenix.otel.register(auto_instrument=True)`+ through the `openinference_instrumentor` entry point, or by `AtomicAgentsInstrumentor().instrument(tracer_provider=...)`+ for any OTLP backend. LLM spans come from the provider's own OpenInference instrumentor and nest under the agent+ span. See `docs/guides/observability.md` and the `phoenix-tracing` example.+- Forge tools that run their async body through a `ThreadPoolExecutor` submit via+ `contextvars.copy_context().run` so the caller's OpenTelemetry context (and the tracing re-entrancy guard)+ survives in the pool thread.## Assembler ↔ GitHub- `atomic-assembler` clones `https://github.com/eigenwise/atomic-agents.git` (via GitPython), readsdiff --git a/.claude/.codebase-info/dependencies.md b/.claude/.codebase-info/dependencies.mdindex 0eba7a8..e3c4ccf 100644--- a/.claude/.codebase-info/dependencies.md+++ b/.claude/.codebase-info/dependencies.md@@ -1,6 +1,6 @@# Dependencies-*Last Updated: 2026-06-13*+*Last Updated: 2026-10-15*Declared in `pyproject.toml` (Hatchling build, `uv` workspace; versions locked in `uv.lock`).@@ -12,6 +12,16 @@ Declared in `pyproject.toml` (Hatchling build, `uv` workspace; versions locked i| litellm (≥1.50,<2) | Provider-agnostic token counting & model metadata || rich (≥13.7.1,<14) | Console formatting |+## Optional extra — `observability`+| Package | Purpose |+|---------|---------|+| openinference-instrumentation (≥0.1.38,<0.2) | `OITracer` / `TraceConfig` used by `atomic_agents.observability` |+| openinference-semantic-conventions (≥0.1.20,<0.2) | Span attribute names (`agent.name` needs ≥0.1.20) |+| opentelemetry-api (≥1.30,<2) | Tracer / context API |++Also listed in the dev group (plus `opentelemetry-sdk`) so CI runs the observability tests. `arize-phoenix-otel`+already brings the two OpenInference packages, so the Phoenix auto path works without the extra.+## Runtime — CLI / tooling| Package | Purpose ||---------|---------|diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.mdindex d9473c7..8b800ca 100644--- a/.claude/.codebase-info/directory-structure.md+++ b/.claude/.codebase-info/directory-structure.md@@ -1,6 +1,6 @@# Directory Structure-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-15*## Root Layout@@ -12,14 +12,15 @@ atomic-agents/ # repo root (uv workspace)│ ├── base/ # BaseIOSchema, BaseTool, BaseResource, BasePrompt, VideoURL│ ├── context/ # SystemPromptGenerator, BaseChatHistory/ChatHistory, context providers│ ├── connectors/mcp/ # Model Context Protocol integration-│ └── utils/ # token counter, tool-message formatting-│ └── tests/ # pytest suite (agents/, base/, context/, connectors/, utils/; VideoURL tests in base/)+│ ├── utils/ # token counter, tool-message formatting+│ └── observability/ # opt-in OpenInference instrumentor (Phoenix / OpenTelemetry)+│ └── tests/ # pytest suite (agents/, base/, context/, connectors/, observability/, utils/)├── atomic-assembler/ # Textual TUI (`atomic` command) to install forge tools│ └── atomic_assembler/ # main.py, app.py, screens/, widgets/, utils.py, constants.py├── atomic-forge/ # library of standalone tools (NOT a package)│ ├── tools/<tool>/ # one folder per tool: tool/<tool>.py, tests/, pyproject.toml│ └── guides/ # tool authoring guides (e.g. tool_structure.md)-├── atomic-examples/ # 16 runnable example apps (each its own project)+├── atomic-examples/ # 17 runnable example apps (each its own project)├── claude-plugin/atomic-agents/ # AI-assistant plugin: 7 skills + 2 subagents (Claude Code plugin,│ # also installable cross-tool via `npx skills add eigenwise/atomic-agents`)├── .claude-plugin/ # marketplace.json — plugin marketplace manifest (drives npx skills discovery)@@ -54,7 +55,7 @@ and copies a selected tool into the user's project.`pyproject.toml`/`requirements.txt`. Tools are copied into user projects, not pip-installed.### `atomic-examples/`-16 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`,+17 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`, `phoenix-tracing`,`mcp-agent`, `fastapi-memory`, `persistent-memory`, `youtube-summarizer`, …), each with its own`pyproject.toml`. These are excluded from the workspace build.diff --git a/.claude/.codebase-info/entry-points.md b/.claude/.codebase-info/entry-points.mdindex ebccf30..4d15221 100644--- a/.claude/.codebase-info/entry-points.md+++ b/.claude/.codebase-info/entry-points.md@@ -1,6 +1,6 @@# Entry Points-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-15*## 1. Library API (the primary entry point)@@ -49,6 +49,7 @@ MCP server tools/resources/prompts become agent components via `atomic_agents.co| `fastapi-memory` | multi-user / multi-session memory behind a FastAPI service || `persistent-memory` | custom `BaseChatHistory` backend: cross-session recall via stdlib `sqlite3` (no extra deps) || `hooks-example` | monitoring, error handling, retry via hooks |+| `phoenix-tracing` | Arize Phoenix traces: planner agent -> calculator tool -> answer agent under one CHAIN span, via `register(auto_instrument=True)` || `basic-multimodal` / `nested-multimodal` | images / PDFs in (nested) schemas || `basic-pdf-analysis` | PDF analysis with a multimodal model || `youtube-summarizer` / `youtube-to-recipe` | transcript → summary / structured recipe |diff --git a/.claude/.codebase-info/modules.md b/.claude/.codebase-info/modules.mdindex 40d733e..c16558f 100644--- a/.claude/.codebase-info/modules.md+++ b/.claude/.codebase-info/modules.md@@ -1,6 +1,6 @@# Key Modules-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-15*## Core framework — `atomic-agents/atomic_agents/`@@ -44,6 +44,22 @@- **Key files:** `token_counter.py` (`TokenCounter` via LiteLLM; `get_context_token_count`),`format_tool_message.py`.+### observability (opt-in)+- **Location:** `atomic-agents/atomic_agents/observability/`+- **Purpose:** OpenInference tracing for Arize Phoenix and any OpenTelemetry backend. `AtomicAgentsInstrumentor`+ (`__init__.py`, stdlib-only imports) lazily loads `openinference_tracing.py`, which patches the four+ `AtomicAgent.run*` methods into AGENT spans and every `BaseTool` subclass's `run`/`run_async`/`arun` into TOOL+ spans (existing classes via a `__subclasses__` walk, future ones via a wrapped `BaseTool.__init_subclass__`).+- **Contract:** `instrument(tracer_provider=, config=TraceConfig)` / `uninstrument()` /+ `is_instrumented_by_opentelemetry`; idempotent and fully reversible. Needs the `observability` extra+ (`openinference-instrumentation>=0.1.38`); older versions are refused with a warning so Phoenix's+ `register(auto_instrument=True)` (which loads the `openinference_instrumentor` entry point) never fails.+- **Span facts:** `agent.name` = `Class[InputSchema, OutputSchema]`; namespaced `atomic_agents.*` attributes+ (model, mode, schema names, history size, context provider names, SHA-256 of the static prompt sections);+ streams record the final/last partial and `atomic_agents.stream.closed_early`; a `ContextVar` re-entrancy guard+ keeps `run -> arun` / `to_thread` delegation to one TOOL span. Nothing in `atomic_agents/__init__.py` imports it.+- **Tests:** `atomic-agents/tests/observability/` (in-memory span exporter).+## Subprojects### atomic-assembler (CLI)