Skip to content

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.json
index 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.md
index 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 as
composable, 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`
## Documents
diff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.md
index 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 LLM
providers 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.md
index 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.py
and 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.md
index 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-examples
diff --git a/.claude/.codebase-info/patterns.md b/.claude/.codebase-info/patterns.md
index 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*
## Atomicity
Build 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 (see
the `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,