Generic OpenTelemetry tracing: api-only instrumentor, GenAI attributes, LLM attempt spans

.claude/.codebase-info/.map-state.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "tool": "codebase-mapper",
   "version": "2.15.10",
-  "mappedAt": "2026-10-20",
-  "gitCommit": "609bacb464177649bb73b5d4eea56e631c3c91f0",
+  "mappedAt": "2026-10-21",
+  "gitCommit": "d1c1bc8a910d3a80a98d08d3a35e49d748611cea",
   "documents": [
     "architecture.md",
     "coding-style.md",
@@ -17,16 +17,16 @@
     "tech-landscape.md"
   ],
   "hashes": {
-    "INDEX.md": "fa005d57802311a643c11e92ea8788e62f8d7eb5eb0001952d26e0e91deb9a49",
-    "architecture.md": "59d1265c89d3b42671b7c47165408625018537c016a72df421113cae3f80bb70",
+    "INDEX.md": "8fec73a52b4a1a7b5c9f2ab7de1e02f273aa49aeb73dc5e29a4d5e7049b2c3ec",
+    "architecture.md": "0ff15b04928495b48cdcf40845b5bf9e3bb548c602b734321c4b10f630d83150",
     "coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",
-    "communication.md": "4c49f01a99b25a2f56b2b3ab77464f05c7d70d057aa8e998deffe845afc3e7e6",
-    "dependencies.md": "22b8d208df66c973659a34cea10011a7ac315ddaa65b243c8aaa3adc4eed1a9e",
-    "directory-structure.md": "4efb931cdefecf2c733f0ffb905ad519aff3a81e245a978c0b62b2c5cf0ad49a",
-    "entry-points.md": "e03c248c63823276c21dbbe894b98488643ee401c2db136ad2467a00ba57bc9a",
-    "modules.md": "cd4f81f8ce74dfc4a7bab15ba91dc569245bc342ddf494845d658b51a0a1dc51",
+    "communication.md": "0a61b6090f5e67341ad605517111270bdd04caede037e70ec6565de8dcdf5f28",
+    "dependencies.md": "abadb58027b4092afaaa0efcaec92893eac7bb598318f7f54a542fd77d607dc1",
+    "directory-structure.md": "c8d654506843622fd394e0a998fddba769e4ec534449ccd6755d312192184bfd",
+    "entry-points.md": "65ebc321a35f1ae36f587adce8b7b04b71cc4006ec7d518f4c092836c2984705",
+    "modules.md": "e1185cdddfbcc7a05a69b80661a6c720aa2a1fc10bc445e319983fffb875524e",
     "onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",
     "patterns.md": "09d04b9b8d079ac4ce9e1f5ddafabb6f3faf53b5ef48dca1c2d62d0875e149b0",
-    "tech-landscape.md": "919d254fae6fa5212a18072ee0d26a1165ce2aeef861faace6c34b8804c025b1"
+    "tech-landscape.md": "8a4459f7309dd13fa9e2425507fec35d21b8b3f691bc6a39b6626fffb8d1744d"
   }
 }

.claude/.codebase-info/INDEX.md

@@ -1,12 +1,12 @@
 # Codebase Map — Atomic Agents
 
-*Last Updated: 2026-10-20*
+*Last Updated: 2026-10-21*
 
 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
 `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 · optional OpenInference tracing (Phoenix)
+**Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling · Pyright · `VideoURL` multimodal content · optional OpenTelemetry tracing (GenAI attributes; Phoenix/OpenInference optional)
 **Shape:** Monorepo — `atomic-agents/` (core lib) · `atomic-assembler/` (CLI) · `atomic-forge/` (tools) · `atomic-examples/` (examples)
 **Package:** `atomic-agents` v2.14.0 · core import package is `atomic_agents`
 

.claude/.codebase-info/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-*Last Updated: 2026-10-15*
+*Last Updated: 2026-10-21*
 
 ## Summary
 
@@ -50,7 +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 |
+| Observability (opt-in) | `atomic-agents/atomic_agents/observability/` | OpenTelemetry AGENT / TOOL / LLM-attempt spans with GenAI attributes for any backend (OpenInference attributes optional via the `phoenix` extra); `observability` extra = `opentelemetry-api`; `openinference_instrumentor` + `opentelemetry_instrumentor` entry points |
 | Assembler (CLI) | `atomic-assembler/atomic_assembler/` | Textual TUI to fetch/install forge tools |
 | Forge (tools) | `atomic-forge/tools/` | 13 standalone tools, each `BaseTool`-based |
 

.claude/.codebase-info/communication.md

@@ -1,6 +1,6 @@
 # Communication & Integrations
 
-*Last Updated: 2026-10-19*
+*Last Updated: 2026-10-21*
 
 The framework exposes no HTTP API of its own; "communication" here means how it talks to LLM
 providers and external tools.
@@ -37,15 +37,18 @@ 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 `openinference_instrumentor`, by the standard `opentelemetry-instrument` launcher through
-  `opentelemetry_instrumentor`, or by `AtomicAgentsInstrumentor().instrument(tracer_provider=...)`
-  for an explicitly configured backend. Both discovery paths share the first installation's provider/config.
-  Missing optional tracing dependencies are DEBUG-skipped when the launcher passes `skip_dep_check=True`;
-  manual setup retains its import error and install hint. Choose one configuration path or share the
-  provider explicitly. LLM spans come from one provider-level OpenInference instrumentor and nest under
-  the agent span. See `docs/guides/observability.md` and the `phoenix-tracing` example.
+- OpenTelemetry tracing (`atomic_agents.observability`, `observability` extra = `opentelemetry-api` only): an AGENT
+  span 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; OpenInference
+  attributes are added only when its package is importable (`phoenix` extra). Activated by
+  `phoenix.otel.register(auto_instrument=True)` through `openinference_instrumentor`, by the `opentelemetry-instrument`
+  launcher through `opentelemetry_instrumentor`, or by `AtomicAgentsInstrumentor().instrument(tracer_provider=...,
+  config=TracingConfig(...))`. A later install with different explicit values replaces the provider/config in place
+  with a WARNING; `None` keeps the installed value. Missing `opentelemetry-api` is DEBUG-skipped when the launcher
+  passes `skip_dep_check=True`; manual setup raises `ModuleNotFoundError` with the install hint. Application hooks on
+  the same client keep running; `AtomicAgent.clear_hooks()` removes only its own. Set `llm_spans=False` (or
+  `ATOMIC_AGENTS_TRACE_LLM_SPANS=false`) when a provider instrumentor also emits LLM spans. 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.

.claude/.codebase-info/dependencies.md

@@ -1,6 +1,6 @@
 # Dependencies
 
-*Last Updated: 2026-10-19*
+*Last Updated: 2026-10-21*
 
 Declared in `pyproject.toml` (Hatchling build, `uv` workspace; versions locked in `uv.lock`).
 
@@ -12,15 +12,15 @@ 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 |
+## Optional extras — `observability` and `phoenix`
+| Extra | Package | Purpose |
+|-------|---------|---------|
+| `observability` | opentelemetry-api (≥1.30,<2) | Tracer / context API; the only runtime dependency of `atomic_agents.observability` |
+| `phoenix` | opentelemetry-api, openinference-instrumentation (≥0.1.38,<0.2), openinference-semantic-conventions (≥0.1.20,<0.2) | Adds the OpenInference attribute family and `using_session` / `using_user` / `using_metadata`; needed for Arize Phoenix views |
 
-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.
+Users bring their own SDK and exporter (`opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http`, ...). The dev
+group carries the OpenInference packages plus `opentelemetry-sdk` so the tests run; `arize-phoenix-otel` already
+brings the OpenInference packages, so the Phoenix auto path works without the `phoenix` extra.
 
 ## Runtime — CLI / tooling
 | Package | Purpose |

.claude/.codebase-info/directory-structure.md

@@ -1,6 +1,6 @@
 # Directory Structure
 
-*Last Updated: 2026-10-15*
+*Last Updated: 2026-10-21*
 
 ## Root Layout
 
@@ -13,7 +13,7 @@ atomic-agents/                  # repo root (uv workspace)
 │       ├── context/            #     SystemPromptGenerator, BaseChatHistory/ChatHistory, context providers
 │       ├── connectors/mcp/     #     Model Context Protocol integration
 │       ├── utils/              #     token counter, tool-message formatting
-│       └── observability/      #     opt-in OpenInference instrumentor (Phoenix / OpenTelemetry)
+│       └── observability/      #     opt-in OpenTelemetry instrumentor (GenAI attributes; OpenInference optional)
 │   └── 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

.claude/.codebase-info/entry-points.md

@@ -1,6 +1,6 @@
 # Entry Points
 
-*Last Updated: 2026-10-19*
+*Last Updated: 2026-10-21*
 
 ## 1. Library API (the primary entry point)
 
@@ -49,7 +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)` |
+| `phoenix-tracing` | Arize Phoenix traces: planner agent -> calculator tool -> answer agent under one CHAIN span, via `register(auto_instrument=True)`; depends on `atomic-agents[phoenix]` and sets `ATOMIC_AGENTS_TRACE_LLM_SPANS=false` because the OpenAI instrumentor owns LLM spans there |
 | `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 |
@@ -60,9 +60,10 @@ MCP server tools/resources/prompts become agent components via `atomic_agents.co
 `atomic_agents.observability:AtomicAgentsInstrumentor` is registered as `atomic_agents` in both
 `openinference_instrumentor` (Phoenix) and `opentelemetry_instrumentor` (the standard
 `opentelemetry-instrument` launcher). Both use the same installation state. The launcher needs
-its own SDK/exporter setup and the optional OpenInference dependencies; it does not install them
-through `opentelemetry-bootstrap`. Set `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=atomic_agents` to
-disable launcher discovery. See `docs/guides/observability.md`.
+its own SDK/exporter setup; only `opentelemetry-api` is required for the instrumentor, and
+`opentelemetry-bootstrap` does not install Atomic Agents. Set `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=atomic_agents`
+to disable launcher discovery; `ATOMIC_AGENTS_TRACE_*` environment variables configure hiding, size cap and
+LLM attempt spans on both automatic paths. See `docs/guides/observability.md`.
 
 ## Representative Flow
 

.claude/.codebase-info/modules.md

@@ -1,6 +1,6 @@
 # Key Modules
 
-*Last Updated: 2026-10-15*
+*Last Updated: 2026-10-21*
 
 ## Core framework — `atomic-agents/atomic_agents/`
 
@@ -46,19 +46,37 @@
 
 ### 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).
+- **Purpose:** plain OpenTelemetry tracing for any backend (OTLP collector, Grafana Tempo, Sentry, Datadog,
+  Honeycomb, PostHog, Arize Phoenix, Langfuse). Only `opentelemetry-api` is required; the OpenTelemetry GenAI
+  semantic-convention attributes are primary and the OpenInference family is an optional layer, auto-on when the
+  `openinference-instrumentation` package is importable (`phoenix` extra).
+- **Modules:** `__init__.py` (loader, `AtomicAgentsInstrumentor`, stdlib-only imports), `tracing.py` (thin facade),
+  `tracing_config.py` (`TracingConfig`, `PayloadVisibility`, env parsing), `span_payloads.py` (serialize, hide before
+  serialize, truncate with `<key>.original_length`, bounded/redacted error text), `span_attributes.py` (key constants,
+  Instructor-to-semconv provider map, None filtering, best-effort attribute collection, OpenInference context seam,
+  `using_conversation`), `agent_spans.py` (four `AtomicAgent.run*` wrappers, stream cursors, run state),
+  `tool_spans.py` (`BaseTool` wrappers via `__subclasses__` walk + wrapped `__init_subclass__`, re-entrancy guard),
+  `installation.py` (install / uninstall / replace-in-place), `llm_attempt_spans.py` (Instructor hook handlers).
+- **Contract:** `instrument(tracer_provider=, config=TracingConfig | PayloadVisibility | None, **options)` /
+  `uninstrument()` / `is_instrumented_by_opentelemetry`. Same arguments: no-op; different provider or config:
+  replaced in place with a WARNING, `None` keeps the installed value; in-flight spans finish on their original
+  provider. Hooks are registered once per Instructor client under a lock and removed on uninstall;
+  `suppress_instrumentation` is honored; hooks never raise into user code.
+- **Spans:** `invoke_agent {AgentConfig.name or class}` (`gen_ai.operation.name=invoke_agent`, `gen_ai.agent.name`,
+  `gen_ai.request.model`, `gen_ai.provider.name`, `gen_ai.conversation.id`, `atomic_agents.agent.class`, `.input`,
+  `.output`, model/mode/schema/history/provider/prompt-hash keys, usage totals and `atomic_agents.llm.attempts` at end);
+  `execute_tool {tool.tool_name}` (`gen_ai.tool.*`, `atomic_agents.tool.class`); one `chat {model}` CLIENT span per
+  Instructor attempt from `completion:kwargs`/`completion:response`/`completion:error` with per-attempt usage
+  (cached/reasoning tokens for both chat-completion and Responses shapes), `parse:error` as a `validation_error`
+  event; `error.type` on failures; cancellation = `atomic_agents.cancelled`, never ERROR. Spans always attach to the
+  current context. `llm_spans=False` keeps totals and drops chat spans.
+- **Config:** `TracingConfig(hide_inputs, hide_outputs, max_attribute_length=4096, openinference_attributes=None,
+  llm_spans=True)`; env `ATOMIC_AGENTS_TRACE_HIDE_INPUTS/_OUTPUTS` (fallback `OPENINFERENCE_HIDE_*`),
+  `ATOMIC_AGENTS_TRACE_MAX_ATTRIBUTE_LENGTH` (tolerant, 4096 fallback), `ATOMIC_AGENTS_TRACE_LLM_SPANS`. Under
+  `hide_outputs` every exception becomes `<Type>: <N> attempts (__REDACTED__)`. Nothing in `atomic_agents/__init__.py`
+  imports the package.
+- **Tests:** `atomic-agents/tests/observability/` (in-memory exporter; `instructor_transport.py` builds real Instructor
+  clients over `httpx.MockTransport`; `test_instructor_modes.py` covers TOOLS/JSON/JSON_SCHEMA/RESPONSES_TOOLS).
 
 ## Subprojects
 

.claude/.codebase-info/tech-landscape.md

@@ -1,6 +1,6 @@
 # Technology Landscape
 
-*Last Updated: 2026-10-20*
+*Last Updated: 2026-10-21*
 
 ## Source-of-Truth Files
 
@@ -40,10 +40,12 @@
   - `code-quality.yml` — on push/PR to `main`/`v2.0`, three jobs: `quality` (`uv sync`,
     `black --check` and `flake8` across all four project directories, a focused Pyright 1.1.414 constructor check, then
     `pytest --cov=atomic_agents` for the core); `fresh-install` (build the wheel, install
-    it with the observability extra into a clean venv without the lockfile, import every module under
-    `atomic_agents`, which is what a new user's `pip install` sees); `lowest-versions` (resolve runtime
-    dependencies with `uv pip compile --resolution lowest-direct`, install current pytest tooling plus
-    `opentelemetry-instrumentation==0.51b0` compatible with the OpenTelemetry API floor, then run the
+    it with the `observability` extra plus `opentelemetry-sdk` into a clean venv without the lockfile, prove
+    `openinference` is not importable, run a real `instructor.from_openai` client over `httpx.MockTransport`
+    through a tool and an agent and assert the GenAI span names, usage keys and the absence of every OpenInference
+    key, then import every module under `atomic_agents`); `lowest-versions` (resolve the runtime dependencies plus
+    the `observability` and `phoenix` extras with `uv pip compile --resolution lowest-direct`, install current pytest
+    tooling plus `opentelemetry-instrumentation==0.51b0` compatible with the OpenTelemetry API floor, then run the
     suite). Observability tests exercise real installed discovery metadata, the auto-loader and enabled/disabled
     launcher subprocesses with local exporters; no live model/backend calls are needed.
   - `docs.yml` — on push to `main`: build Sphinx docs, run