Building AI agents, atomically
Document generic schema resolution and hook pausing (#329)
Kenny Vaneetvelde14cf8eb65d84
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.jsonindex b020de2..00d0e52 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-21",- "gitCommit": "b8506eb910c0b1c07a5e8dd21e0ce7397154545f",+ "mappedAt": "2026-10-24",+ "gitCommit": "ea7c09aae6ced82dd0b5df6935f2cb0804246c88","documents": ["architecture.md","coding-style.md",@@ -20,13 +20,13 @@"INDEX.md": "91bb80710a6b08c0bb9be27178d9fbf52f1d32a3cdea58b7bdb07ec295e60b68","architecture.md": "0ff15b04928495b48cdcf40845b5bf9e3bb548c602b734321c4b10f630d83150","coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",- "communication.md": "0a61b6090f5e67341ad605517111270bdd04caede037e70ec6565de8dcdf5f28",+ "communication.md": "2de7556dd0cd55fef9fd56d4cbc6c96dd8b89a29a76b1f7a97356b446a2b8093","dependencies.md": "abadb58027b4092afaaa0efcaec92893eac7bb598318f7f54a542fd77d607dc1","directory-structure.md": "c8d654506843622fd394e0a998fddba769e4ec534449ccd6755d312192184bfd","entry-points.md": "65ebc321a35f1ae36f587adce8b7b04b71cc4006ec7d518f4c092836c2984705","modules.md": "e1185cdddfbcc7a05a69b80661a6c720aa2a1fc10bc445e319983fffb875524e","onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",- "patterns.md": "09d04b9b8d079ac4ce9e1f5ddafabb6f3faf53b5ef48dca1c2d62d0875e149b0",+ "patterns.md": "bd2ea1b37b5bddf1eed1e85cdb6916ac12abf18632c9f67400dc3d588d4420fe","tech-landscape.md": "8a4459f7309dd13fa9e2425507fec35d21b8b3f691bc6a39b6626fffb8d1744d"}}diff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.mdindex b4fbce3..ee1c18e 100644--- a/.claude/.codebase-info/communication.md+++ b/.claude/.codebase-info/communication.md@@ -1,6 +1,6 @@# Communication & Integrations-*Last Updated: 2026-10-21*+*Last Updated: 2026-10-24*The framework exposes no HTTP API of its own; "communication" here means how it talks to LLMproviders and external tools.@@ -37,6 +37,8 @@ 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`.+- `disable_hooks()` detaches this agent's registered Instructor callbacks. Registrations made while disabled stay+ paused; `enable_hooks()` restores the remaining callbacks. Direct client callbacks and tracing hooks remain independent.- OpenTelemetry tracing (`atomic_agents.observability`, `observability` extra = `opentelemetry-api` only): an AGENTspan per `AtomicAgent` run, a TOOL span per `BaseTool` run and one CLIENT `chat` span per Instructor attempt(driven by Instructor hooks registered once per client), all with OpenTelemetry GenAI attributes; OpenInferencediff --git a/.claude/.codebase-info/patterns.md b/.claude/.codebase-info/patterns.mdindex 3bbbd01..c8640a6 100644--- a/.claude/.codebase-info/patterns.md+++ b/.claude/.codebase-info/patterns.md@@ -1,6 +1,6 @@# Patterns & Conventions-*Last Updated: 2026-10-20*+*Last Updated: 2026-10-24*## AtomicityBuild with small, single-purpose, composable parts ("LEGO blocks"): each agent, tool, and context@@ -11,6 +11,8 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.- Every input and output is a `BaseIOSchema` (Pydantic) subclass with a **required docstring** (usedas the LLM-facing description). Naming: `<Thing>InputSchema` / `<Thing>OutputSchema`.- Agents are parameterized by schemas via PEP 695 generics: `AtomicAgent[InputSchema, OutputSchema]`.+- Fully specialized generic agent subclasses resolve their concrete schemas through intermediate bases per instance.+ Different specializations keep independent input/output bindings; untyped agents retain the basic chat defaults.- 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.