Building AI agents, atomically
Refresh the map for the prepared release tree
Eigenwiseecba212ebe75
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.jsonindex 52efcd4..ce10a17 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-13",+ "gitCommit": "8f915c9dd4d8268571f42ee1c32e730b80a49be6","documents": ["architecture.md","coding-style.md",@@ -17,16 +17,16 @@"tech-landscape.md"],"hashes": {- "INDEX.md": "50e7beb7784d3d01f8ce0e85b842889f5c033ca98cbb30981fd0b532c1495c8f",+ "INDEX.md": "dd70bf99170b2677ba146497792392e899cc1b7b37d93ea8f03b390944cb6c73","architecture.md": "8e6be8d2795231ea5919d7cdc23a201595f9fed9724b635e6cc686b2bf24581f","coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",- "communication.md": "6c73cad50151b73a6be63c8f0745d3f7a6653a861d37afce660c512ac30b8819",+ "communication.md": "62f68e393ae8ff624e46ca9380ee7e91341ca46233efcd729aa3708e16fda66c","dependencies.md": "b445a920c121e27006fec824add6865d01cf71212a517e5ff8b2058d3999037a",- "directory-structure.md": "ca200817789c4d1fdc41d1683c37740c9837bf323b18881cb2351ef8a56c4926",+ "directory-structure.md": "5bd6d10635f7103c9a13c546e76d0b39febc746bb926acf3d90ebe5e369b4807","entry-points.md": "62fd8ff478fc27c3658776626059bdd4101cab12a74a48cdd8787f9ca7b83f97",- "modules.md": "7a8772e5f31be0070003c9a7ce78eca5df95dfb6a1c9dd471a6be97df81084aa",+ "modules.md": "e60e67bb603eb2dddbbb8b76e6c29b1a7817b6e8e2be9601f31333eadfdae341","onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",- "patterns.md": "f3a339a7bc711c4586062139d135e1d79129653cf82fc430cd256028d25e2dcc",+ "patterns.md": "30652236ca7524c3b0c2680054e595903652d8c4ece81f4236238e870c09eb42","tech-landscape.md": "700b3ba7bb5e47ec14086e2b94ad65ad956c0bfbe1c463f96c39493143e0c912"}}diff --git a/.claude/.codebase-info/INDEX.md b/.claude/.codebase-info/INDEX.mdindex cbf4927..a3e1695 100644--- a/.claude/.codebase-info/INDEX.md+++ b/.claude/.codebase-info/INDEX.md@@ -1,6 +1,6 @@# Codebase Map — Atomic Agents-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-13*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@@ -8,7 +8,7 @@ composable, schema-driven building blocks (built on Instructor + Pydantic). This**Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling · Pyright · `VideoURL` multimodal content**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`+**Package:** `atomic-agents` · prepared source version 2.11.0, not published · core import package is `atomic_agents`## Documentsdiff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.mdindex 86aa7b8..d846b8c 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-13*The framework exposes no HTTP API of its own; "communication" here means how it talks to LLMproviders and external tools.@@ -28,6 +28,9 @@ providers and external tools.tools/resources/prompts: `MCPFactory`, `MCPDefinitionService`, `SchemaTransformer`, and`fetch_mcp_tools` / `fetch_mcp_resources` / `fetch_mcp_prompts` (sync + async). See the`mcp-agent` and `progressive-disclosure` examples.+- Discovery follows tool, resource, template and prompt cursors. Template continuation errors propagate.+- Schema references decode escaped definition names and support non-object definitions.+- Typed SDK tool results use structured content only when it is non-None, then use the existing validated JSON-text fallback. Present empty structured data retains precedence. Mapping adapters keep their separate validation contract.## Hooks / observability- Built on Instructor's hook system: `register_hook(event, handler)`, `unregister_hook`,diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.mdindex d9473c7..d8fa7e6 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-13*## Root Layout@@ -48,7 +48,7 @@ A Textual terminal UI launched by the `atomic` command (`main.py:main`). `app.pyand copies a selected tool into the user's project.### `atomic-forge/tools/`-14 self-contained tools (`arxiv_search`, `calculator`, `serply_search`, `tavily_search`, `weather`,+Self-contained tools (`arxiv_search`, `calculator`, `firecrawl_search`, `fxmacrodata`, `serply_search`, `tavily_search`, `weather`,`webpage_scraper`, `wikipedia_search`, …). Each tool folder contains `tool/<name>.py` (Input/Output`BaseIOSchema` + a `BaseToolConfig` + a `BaseTool` subclass), `tests/`, and its own`pyproject.toml`/`requirements.txt`. Tools are copied into user projects, not pip-installed.diff --git a/.claude/.codebase-info/modules.md b/.claude/.codebase-info/modules.mdindex 40d733e..5db6f3f 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-13*## Core framework — `atomic-agents/atomic_agents/`@@ -56,9 +56,11 @@### atomic-forge (tools)- **Location:** `atomic-forge/tools/`-- **Purpose:** 13 standalone tools, each an independent mini-project following the `BaseTool` pattern,+- **Purpose:** Standalone tools, each an independent mini-project following the `BaseTool` pattern,copied into user projects by the assembler (build files such as `pyproject.toml` / `requirements.txt`/ `uv.lock` are skipped on copy).+- **Recent additions:** `firecrawl_search` provides web/news search; `fxmacrodata` provides economic releases, FX and COT data. Both keep their own dependencies and setup.+- **YouTube compatibility:** `youtube_transcript_scraper` uses the instance-based transcript API and converts SDK transcript objects to raw entries.- **Authoring guide:** `atomic-forge/guides/tool_structure.md`.### atomic-examplesdiff --git a/.claude/.codebase-info/patterns.md b/.claude/.codebase-info/patterns.mdindex a587923..281f114 100644--- a/.claude/.codebase-info/patterns.md+++ b/.claude/.codebase-info/patterns.md@@ -1,6 +1,6 @@# Patterns & Conventions-*Last Updated: 2026-08-11*+*Last Updated: 2026-10-13*## AtomicityBuild with small, single-purpose, composable parts ("LEGO blocks"): each agent, tool, and context@@ -34,6 +34,7 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.and supports `dump()`/`load()`. `VideoURL` is converted to an OpenAI-compatible `video_url`content part for provider messages. `AtomicAgent` trims the oldest whole turns to honor`max_context_tokens`, using a text placeholder when LiteLLM cannot count video parts.+- Invalid serialized history is validated before replacing existing state. Context trimming includes the incoming message in the token budget.- Custom backend pattern: subclass `ChatHistory` and override `add_message`/`load` to persist (seethe `persistent-memory` example and the "Writing a Custom Memory Backend" guide section).@@ -46,6 +47,7 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.clients. Core tests in `atomic-agents/tests/` mirror the package layout (`agents/`, `base/`,`context/`, `connectors/mcp/`, `utils/`), including `tests/base/test_multimodal.py` for `VideoURL`.Discovery (`pytest.ini`): files `test_*.py`, classes `Test*`, functions `test_*`.+- MCP tests use real SDK result models with mocked transport/session boundaries. Synthetic execution against production filenames is not used to increase coverage.## Configuration- Runtime config is explicit via `AgentConfig` (client, model, history, roles, mode,