Skip to content

Building AI agents, atomically

Release v2.12.1 (#317)

Kenny Vaneetveldef401da1acafe
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json
index 1d18388..6823e12 100644
--- a/.claude/.codebase-info/.map-state.json
+++ b/.claude/.codebase-info/.map-state.json
@@ -2,8 +2,8 @@
"schemaVersion": 1,
"tool": "codebase-mapper",
"version": "2.15.10",
- "mappedAt": "2026-10-15",
- "gitCommit": "9e56b85a0173acae6c957a519957b86b5a4c0dad",
+ "mappedAt": "2026-10-19",
+ "gitCommit": "eb257d2d13cda893f8f9a8cb3df20628e2ddb569",
"documents": [
"architecture.md",
"coding-style.md",
@@ -21,12 +21,12 @@
"architecture.md": "59d1265c89d3b42671b7c47165408625018537c016a72df421113cae3f80bb70",
"coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",
"communication.md": "70fbeedf239b130cfd3d7a92f27d56e96b207d85117b2f83cc9eef8ec6d6c6b3",
- "dependencies.md": "837fe41809eb2753be100ae244fec53423846867b16d91471ec3b5ae03f74e90",
+ "dependencies.md": "e39579db4e32a05b34467df9af4ac7c64bc47df935704e1e95c3a4a79bfc304b",
"directory-structure.md": "4efb931cdefecf2c733f0ffb905ad519aff3a81e245a978c0b62b2c5cf0ad49a",
"entry-points.md": "3c94fd8a821fc76789794b6d3f4d89cc88a7903055755d97437f9f3ca6193cb6",
"modules.md": "cd4f81f8ce74dfc4a7bab15ba91dc569245bc342ddf494845d658b51a0a1dc51",
"onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",
- "patterns.md": "30652236ca7524c3b0c2680054e595903652d8c4ece81f4236238e870c09eb42",
- "tech-landscape.md": "700b3ba7bb5e47ec14086e2b94ad65ad956c0bfbe1c463f96c39493143e0c912"
+ "patterns.md": "dbd5ff107b7567c6424af31910ca88148836d16f31002bfed226f28b6725147f",
+ "tech-landscape.md": "31f74730fcc6e75fc4127315a5c707af261d5ad3add7161bfdeb9719b8195af0"
}
}
diff --git a/.claude/.codebase-info/dependencies.md b/.claude/.codebase-info/dependencies.md
index e3c4ccf..f1460ff 100644
--- a/.claude/.codebase-info/dependencies.md
+++ b/.claude/.codebase-info/dependencies.md
@@ -1,6 +1,6 @@
# Dependencies
-*Last Updated: 2026-10-15*
+*Last Updated: 2026-10-19*
Declared in `pyproject.toml` (Hatchling build, `uv` workspace; versions locked in `uv.lock`).
@@ -26,7 +26,7 @@ already brings the two OpenInference packages, so the Phoenix auto path works wi
| Package | Purpose |
|---------|---------|
| textual (≥5.3,<6) | TUI framework for the `atomic` assembler |
-| mcp[cli] (≥1.6) | Model Context Protocol client + CLI |
+| mcp[cli] (≥1.6,<2) | Model Context Protocol client + CLI |
| requests (≥2.32,<3) | HTTP |
| gitpython (≥3.1.43,<4) | Clone the repo to fetch forge tools |
| pyyaml (≥6,<7) | Read tool `config.yaml` metadata |
diff --git a/.claude/.codebase-info/patterns.md b/.claude/.codebase-info/patterns.md
index 281f114..70ea2ce 100644
--- a/.claude/.codebase-info/patterns.md
+++ b/.claude/.codebase-info/patterns.md
@@ -1,6 +1,6 @@
# Patterns & Conventions
-*Last Updated: 2026-10-13*
+*Last Updated: 2026-10-19*
## Atomicity
Build with small, single-purpose, composable parts ("LEGO blocks"): each agent, tool, and context
@@ -12,6 +12,10 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.
as the LLM-facing description). Naming: `<Thing>InputSchema` / `<Thing>OutputSchema`.
- Agents are parameterized by schemas via PEP 695 generics: `AtomicAgent[InputSchema, OutputSchema]`.
- Structured output is enforced by Instructor through `response_model=OutputSchema`.
+- Streaming completion accepts field names when reconstructing output schemas with aliases.
+- Tool messages use Pydantic JSON-mode serialization, including JSON-only field serializers.
+- MCP dictionary schemas preserve mapping values and validate typed `additionalProperties`,
+ including mappings reached through `$defs` or `definitions` references.
## Dynamic system prompts (context providers)
- `SystemPromptGenerator(background=[...], steps=[...], output_instructions=[...], context_providers={...})`.
@@ -50,6 +54,8 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.
- MCP tests use real SDK result models with mocked transport/session boundaries. Synthetic execution against production filenames is not used to increase coverage.
## Configuration
+- Omitted `BaseTool`, `BaseResource`, and `BasePrompt` configurations are created per instance.
+ Explicitly supplied configuration objects retain their identity.
- Runtime config is explicit via `AgentConfig` (client, model, history, roles, mode,
`model_api_parameters`, `max_context_tokens`) — no global state. Secrets (API keys) come from the
environment / `.env`.
diff --git a/.claude/.codebase-info/tech-landscape.md b/.claude/.codebase-info/tech-landscape.md
index f6cb634..994bf9e 100644
--- a/.claude/.codebase-info/tech-landscape.md
+++ b/.claude/.codebase-info/tech-landscape.md
@@ -1,6 +1,6 @@
# Technology Landscape
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-19*
## Source-of-Truth Files
@@ -25,7 +25,7 @@
| Structured LLM I/O | Instructor 1.14.5 (pinned) | provider-agnostic structured outputs |
| Data modeling | Pydantic v2 (≥2.11) | all schemas are Pydantic models |
| Provider / token utils | LiteLLM (≥1.50) | token counting, model metadata |
-| Tool protocol | MCP — `mcp[cli]` (≥1.6) | Model Context Protocol connectors |
+| Tool protocol | MCP, `mcp[cli]` (≥1.6,<2) | Model Context Protocol connectors |
| TUI | Textual (≥5.3,<6) | the `atomic` assembler UI |
| Console output | Rich, pyfiglet | |
| HTTP / Git | requests, GitPython | assembler fetches forge from GitHub |
@@ -38,8 +38,9 @@
- **CI (GitHub Actions):**
- `code-quality.yml` — on push/PR to `main`/`v2.0`: `uv sync`, `black --check`, `flake8`, then
- `pytest --cov=atomic_agents` across `atomic-agents`, `atomic-assembler`, `atomic-examples`,
- `atomic-forge`.
+ `pytest --cov=atomic_agents` for the core. Formatting and lint cover all four project directories.
+ A separate `fresh-install` job builds the wheel, installs it without the lockfile, and imports
+ every `atomic_agents` subpackage.
- `docs.yml` — on push to `main`: build Sphinx docs, run
`scripts/generate_llms_files.py` (spec-compliant `llms.txt` index + `llms-*.txt`
bundles, copied to the site root), deploy to GitHub Pages. The docs version needs
diff --git a/.release/2.12.1.md b/.release/2.12.1.md
index 99754f0..1f7e206 100644
--- a/.release/2.12.1.md
+++ b/.release/2.12.1.md
@@ -1,15 +1,28 @@
# Atomic Agents 2.12.1
-Patch release. No framework behavior changes.
+## Fixes
-## Fix
+- Cap `mcp` below 2.0 so fresh installs can import the MCP connector. The lockfile had hidden the incompatible upstream import change. (#308)
+- Give tools, resources, and prompts independent default configurations. Explicitly shared configurations still work. (#307)
+- Serialize tool arguments with Pydantic's JSON representations, including dates, UUIDs, decimals, paths, enums, and JSON-only field serializers. (#312)
+- Complete sync and async streaming for output schemas with field aliases without a validation error. (#314)
+- Preserve dictionary arguments and structured results in MCP tools, and validate typed dictionary values. (#313)
+- Make the README context-provider example runnable without an undefined typing import. (#311)
+- Correct the manual OpenTelemetry setup and document the masking boundary. (#309)
-- Pin `mcp` below 2.0. A fresh `pip install atomic-agents` since late July resolved mcp 2.x, and `import atomic_agents.connectors.mcp` then failed with `ImportError: cannot import name 'streamablehttp_client'`. The repo lockfile kept resolving mcp 1.22, which is why the test suite never saw it. The mcp 2.x migration is scheduled for 2.13.0.
+## Forge tools
-## CI
+These downloadable tools live in the repository and are not bundled in the PyPI package.
-- New job builds the wheel, installs it into a clean environment without the lockfile, and imports every module under `atomic_agents`. This is the check that would have caught the break before release.
+- Count elapsed time across daylight-saving transitions in DateTimeTool. (#315)
+- Apply the requested arXiv category to the full search expression. (#316)
+
+## Installation checks
+
+A new CI job builds the wheel, installs it without the lockfile, and imports every core subpackage.
## Compatibility
-Python 3.12 or newer. Projects already pinning `mcp<2` or resolving 1.x see no change. Projects that need mcp 2.x should wait for 2.13.0.
+Python 3.12 or newer. Instructor remains pinned to 1.14.5 in this patch. The separately tested Instructor range update follows in 2.13.0. MCP 2.x support is still pending.
+
+Full changelog: https://github.com/Eigenwise/atomic-agents/compare/v2.12.0...v2.12.1
diff --git a/pyproject.toml b/pyproject.toml
index d5f1666..18cdda6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "atomic-agents"
-version = "2.12.0"
+version = "2.12.1"
description = "A versatile framework for creating and managing intelligent agents."
readme = "README.md"
license = "MIT"
diff --git a/uv.lock b/uv.lock
index 3aa0da6..8c06370 100644
--- a/uv.lock
+++ b/uv.lock
@@ -258,7 +258,7 @@ wheels = [
[[package]]
name = "atomic-agents"
-version = "2.12.0"
+version = "2.12.1"
source = { editable = "." }
dependencies = [
{ name = "gitpython" },