agentbyte 0.2.4__tar.gz → 0.3.0__tar.gz

{agentbyte-0.2.4 → agentbyte-0.3.0}/.github/copilot-instructions.md

@@ -503,6 +503,72 @@ src/agentbyte/
 ## Conding Tips and Tricks
 - When picking certain topics from certain sections of the book, first only focus on that section and not the whole chapter if not relevant to the current implementation phase
 
+## Local Jaeger Trace Inspection
+
+Agentbyte ships a trace inspector script at `examples/otel/inspect_trace.py` that fetches a trace from local Jaeger and pretty-prints every span with its full AI messages (input, tool calls, tool results, output).
+
+### Setup
+
+1. **Start Jaeger** (clears all old traces):
+   ```bash
+   docker compose -f docker/jaeger-compose.yml down && docker compose -f docker/jaeger-compose.yml up -d
+   ```
+
+2. **Run an OTel example** to generate traces (service names: `agentbyte-example`, `agentbyte-stream`, `agentbyte-debug`):
+   ```bash
+   uv run python examples/otel/agent_with_stream_telemetry.py
+   ```
+
+3. **List all traces** for a service and see their span structure:
+   ```bash
+   curl -s "http://localhost:16686/api/traces?service=agentbyte-stream&limit=10&lookback=1h" | python3 -c "
+   import json, sys
+   data = json.load(sys.stdin)
+   for t in data.get('data', []):
+       print(t['traceID'], 'spans=', len(t['spans']))
+       for s in sorted(t['spans'], key=lambda x: x['startTime']):
+           print('   ', s['operationName'], f'({s[\"duration\"]//1000}ms)')
+   "
+   ```
+
+4. **Inspect a specific trace** (full messages per span):
+   ```bash
+   uv run python examples/otel/inspect_trace.py <trace_id>
+   ```
+
+### What the inspector shows per span
+- **`agent <name>`** — root span, total duration
+- **`chat <model>`** — `INPUT MESSAGES` (full context sent to LLM), `OUTPUT MESSAGES` (model reply), tokens/cost/finish_reason
+- **`tool <name>`** — `TOOL PARAMETERS` (args), `TOOL RESULT` (return value), success flag
+
+### OTel environment variables
+| Variable | Default | Purpose |
+|---|---|---|
+| `AGENTBYTE_ENABLE_OTEL` | `false` | Enable OTel instrumentation |
+| `AGENTBYTE_OTEL_CAPTURE_CONTENT` | `false` | Capture full message content in spans (needed for inspector to show messages) |
+| `OTEL_SERVICE_NAME` | — | Service label shown in Jaeger |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP endpoint (e.g. `http://localhost:4318`) |
+
+### Trace structure
+```
+agent city_assistant          ← root span (one per run_stream/run call)
+  └─ chat gpt-4.1-mini        ← LLM call: tokens, cost, finish_reason, messages
+  └─ tool get_weather          ← tool execution: params, result
+  └─ tool get_population       ← tool execution: params, result
+  └─ chat gpt-4.1-mini        ← final LLM call with all tool results
+```
+
+### Jaeger UI
+View at **http://localhost:16686** — use service dropdown to select `agentbyte-stream`, `agentbyte-example`, or `agentbyte-debug`.
+
+### Message format note
+Agentbyte serializes messages with a `parts` array (not OpenAI-style `content` string). The inspector handles both formats automatically.
+
+---
+
+## Script Execution Rule
+- Assume Python scripts are run from the repository root. Use `.envs/local.env` with a root-relative path (e.g., `Path(".envs") / "local.env"`) instead of traversing parents.
+
 ## Coding Rules:
 - Try to create minimal tests with pytest and pytest async for testing any code. **AVOID heredoc blocks** (`uv run python3 << 'EOF'`) as they tend to hang/freeze in terminal output:
   - ✅ Good: `uv run python3 -c "from agentbyte.llm import X; print(X)"`
@@ -523,6 +589,7 @@ src/agentbyte/
   - Run full checks: `uv run ruff check <file_or_dir>`
   - Auto-fix fixable issues: `uv run ruff check <file_or_dir> --fix`
   - This catches unused imports, style issues, and other code quality concerns early
+- **Release/tag rule (mandatory):** whenever preparing a new version tag/release, always update both `README.md` and `CHANGELOG.md` in the same change set before commit/tag/push.
 ## Success Criteria
 
 ✓ **Deep Understanding:** Can explain the "why" behind each pattern and design decision

agentbyte-0.3.0/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to Agentbyte are documented in this file.
+
+The format follows Keep a Changelog principles and semantic versioning.
+
+## [0.3.0] - 2026-03-06
+
+### Breaking Changes
+- `BaseAgent` no longer stores a context instance. `self.context`, `reset_context()`, `clear_messages()`, `window_messages()`, and `reset()` are removed. `Agent.__init__` no longer accepts a `context=` keyword argument.
+- Multi-turn sessions must now be managed by the caller: pass `context=` to each `run()`/`run_stream()` call and capture the returned context from `AgentResponse.context`.
+
+### Changed
+- `Agent.run(task=None, context=None, ...)` and `Agent.run_stream(task=None, context=None, ...)` accept a per-call `AgentContext`. When `None`, a fresh context is created automatically.
+- `AgentResponse.context` returns the fully-populated working context to the caller after every run.
+- `AgentAsTool.execute(parameters, context=None)` and `execute_stream(parameters, context=None, ...)` thread the caller-supplied context through to the underlying agent.
+- `AgentToolCompatible` protocol updated to include `context=None` on both `execute` and `execute_stream`.
+
+### Documentation
+- `topic_agents.md`: Parts 2.5 (lock-free context threading) and 2.6 (agent-as-tool context) added.
+- `topic_approval.md`: Tool approval resume pattern updated to `agent.run(context=first_response.context)`.
+- `topic_otel_spans.md`: Dummy trace ID notes added; `args: {}` vs `TOOL PARAMETERS` discrepancy explained; known limitation section for parsed args not captured in chat span attributes.
+- Notebooks `04-agent-with-context`, `07-agent-as-tool-coordinator`, `04.2-metadata-extraction-large-doc` updated to caller-owned context pattern.
+
+## [0.2.7] - 2026-03-03
+
+### Added
+- `run_stream()` is now fully instrumented with an OTel root span via the native `_root_span()` context manager — every streaming task gets a correctly nested `agent <name>` root span identical to `run()`.
+- New OTel example `examples/otel/agent_with_stream_telemetry.py` — streaming agent with 3 queries of increasing tool complexity (service: `agentbyte-stream`).
+- New `examples/otel/inspect_traces.py` — CLI utility to inspect Jaeger traces without opening the UI; requires a traceID positional argument.
+
+### Changed
+- `auto_instrument()` now patches **only** `Agent.__init__` (OTelMiddleware injection); root span creation is handled natively in `Agent.run_stream()` — no monkey-patching of `run` or `run_stream`.
+- `Agent.run_stream` execution logic renamed internally to `_run_stream_impl`; public `run_stream` is a thin span-wrapping delegate.
+- `_annotate_root_span()` is a module-level function in `otel.py` — all OTel instrumentation logic is now centralized in one file.
+
+## [0.2.6] - 2026-03-03
+
+### Added
+- OpenTelemetry model-call usage enrichment:
+	- `gen_ai.usage.total_tokens`
+	- `gen_ai.usage.cost_estimate_usd`
+	- `gen_ai.response.finish_reason`
+- Root agent span usage enrichment (opt-in via `AGENTBYTE_OTEL_CAPTURE_USAGE=true`):
+	- `gen_ai.agent.finish_reason`
+	- `gen_ai.agent.llm_calls`
+	- `gen_ai.usage.duration_ms`
+	- `gen_ai.usage.input_tokens`
+	- `gen_ai.usage.output_tokens`
+	- `gen_ai.usage.total_tokens`
+	- `gen_ai.usage.cost_estimate_usd`
+
+### Changed
+- OTel examples now set `AGENTBYTE_OTEL_CAPTURE_USAGE=true` to demonstrate final task-level usage aggregation on root spans.
+- OTel middleware now uses `Usage.total_tokens` directly for span attribute emission.
+
+### Documentation
+- Updated README to position Agentbyte as an observability-first agentic AI framework.
+- Added no-UI Jaeger debugging workflow (API-based trace inspection with `curl`).
+
+## [0.2.5] - 2026-03-02
+
+### Changed
+- Synced release documentation with code version and updated release-facing project docs.
+- Updated release process guidance in repository instructions to require `README.md` and `CHANGELOG.md` updates for every tag.
+
+### Documentation
+- Updated README release section to reflect the new version and current highlights.
+
+## [0.2.4] - 2026-03-02
+
+### Added
+- New use-case notebook: `04.2-metadata-extraction-large-doc.ipynb` for progressive chunked metadata extraction with memory and aggregation.
+- New concept sample-data JSON files for ASMD/ESMD synthetic contract metadata.
+- Project logo asset at `logo/agent-byte-avatar-low.png`.
+
+### Changed
+- Reorganized notebooks into `notebooks/concepts/agent/` and `notebooks/usecases/` with updated naming.
+- Refreshed multiple concept notebooks for agent, middleware, memory, OTel, and agent-as-tool flows.
+
+## [0.2.3] - 2026-03-02
+
+### Changed
+- Unified `Conversation` and `Workspace` into a single `Session` model. Both were structurally identical; domain semantics now live in `Session.metadata` (e.g. `{"name": "Blog Post"}`).
+- `session.py` now contains `Session(Entity)`, `BaseSession(ABC)`, and `InMemorySession` — flat pattern mirroring `memory/base.py`.
+- `AgentContext.conversation_id` field removed. `session_id: Optional[str]` (already present) is the sole context-level session link.
+
+### Removed
+- `src/agentbyte/conversation/` module and all exports (`Conversation`, `BaseConversation`, `InMemoryConversation`).
+- `src/agentbyte/workspace/` module and all exports (`Workspace`, `BaseWorkspace`, `InMemoryWorkspace`).
+- `tests/test_conversation.py`, `tests/test_workspace.py`, `tests/agents/test_agent_conversation_integration.py`.
+
+### Added
+- `tests/test_session.py` — 19 tests covering `Session` identity/equality, `to_context()`/`from_context()`, `InMemorySession` CRUD, copy-safety, and ABC contract.
+
+### Reorganized
+- Notebooks moved from flat layout into `notebooks/agent/`, `notebooks/auth/`, and `notebooks/usecase/` subdirectories.
+
+## [0.2.1] - 2026-02-27
+
+### Changed
+- Updated package metadata for project URLs (Homepage, Repository, Issues, Changelog).
+- Updated README installation guidance for `pip`/`uv add` extras usage.
+
+### Added
+- Added root `LICENSE` file (MIT) for distribution compliance and clarity.
+
+## [0.2.0] - 2026-02-27
+
+### Added
+- Memory serialization parity (`ListMemoryConfig`, `FileMemoryConfig`, `_to_config`, `_from_config`).
+- Agent-managed memory tooling via `MemoryTool` and `MemoryBackend`.
+- Middleware-driven memory access routing (`operation="memory_access"`).
+- `ApprovalMiddleware` for centralized tool-approval policy.
+- OpenTelemetry middleware and auto-instrumentation support.
+- Notebook examples for middleware patterns and real-client logging middleware.
+- New/expanded tests for middleware, memory, package API, and OTel integration.
+
+### Changed
+- Middleware execution and event pipeline now support richer parity behavior with request/response/error fan-out semantics.
+- Agent run paths now integrate improved middleware handling and instrumentation.
+- Package API now exposes `Agent` at package root and supports opt-in auto-instrumentation via environment variable.
+
+### Fixed
+- Token usage mapping alignment in telemetry paths (`tokens_input`, `tokens_output`).
+- Auto-instrumentation idempotency for repeated setup calls.
+
+## [0.1.2] - 2026-02-25
+
+### Added
+- Initial middleware and memory completion pass (streaming middleware baseline, approval pause integration, memory tooling foundations).

{agentbyte-0.2.4 → agentbyte-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.2.4
+Version: 0.3.0
 Summary: A toolkit for designing multiagent systems
 Project-URL: Homepage, https://gitlab.com/pyninja/aiengineering/agentbyte
 Project-URL: Repository, https://gitlab.com/pyninja/aiengineering/agentbyte
@@ -30,22 +30,24 @@ Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'otel'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.3.0/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
 </p>
 
 # Agentbyte
 
-Agentbyte is a Python toolkit for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
+Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.2.1**
+Current release: **0.3.0**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
-## What’s New in 0.2.1
+## What's New in 0.3.0
 
-- Added explicit project URLs in package metadata (Homepage, Repository, Issues, Changelog).
-- Added MIT `LICENSE` file at repository root.
-- Expanded README install guidance for extras using `pip install` and `uv add`.
+- **Breaking:** `BaseAgent` no longer stores context. `self.context`, `reset_context()`, `clear_messages()`, `window_messages()`, and `reset()` are removed. `Agent.__init__` no longer accepts a `context=` kwarg.
+- `Agent.run(task=None, context=None, ...)` and `Agent.run_stream(task=None, context=None, ...)` accept a per-call `AgentContext`. A fresh context is created automatically when `None`.
+- `AgentResponse.context` returns the fully-populated working context to the caller — enables clean multi-turn patterns without agent-side state.
+- `AgentAsTool.execute()` and `execute_stream()` thread the caller-supplied context through to the underlying agent.
+- Notebooks, study docs (`topic_agents.md`, `topic_approval.md`), and OTel span guide (`topic_otel_spans.md`) updated to the caller-owned context pattern.
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
 
@@ -57,6 +59,36 @@ See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
 - Built-in middleware: logging, security, rate limiting, approval, telemetry.
 - Memory abstractions: list memory, file memory, context injection.
 - OpenAI and Azure OpenAI model client support.
+- OpenTelemetry-first tracing with model-call and task-level usage telemetry.
+
+## Observability-First Telemetry
+
+Agentbyte exposes two complementary telemetry layers:
+
+- **Per-call middleware spans** (`chat ...`, `tool ...`) for model/tool-level diagnostics.
+- **Task-level root span attributes** (`agent ...`) for final aggregated usage and outcome.
+
+Enable telemetry:
+
+```bash
+export AGENTBYTE_ENABLE_OTEL=true
+```
+
+Per-call span attributes emitted by `OTelMiddleware`:
+
+- `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.total_tokens`
+- `gen_ai.usage.cost_estimate_usd`
+- `gen_ai.response.finish_reason`
+- `gen_ai.request.model`
+- `gen_ai.tool.name`, `gen_ai.tool.success`
+
+## Degugging Traces without UI
+details can be found in the [OTel spans guide](docs/study/topic_otel_spans.md#debugging-traces-without-ui).
+
+Practical interpretation:
+
+- `chat gpt-4.1-mini` spans show **per-call** usage/cost/finish reason.
+- `agent <name>` span shows **final accumulated** usage and final task outcome.
 
 ## Installation
 
@@ -148,5 +180,4 @@ MIT — see [LICENSE](LICENSE).
 
 - [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
 - [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
-- [Pydantic AI](https://ai.pydantic.dev/)
 

{agentbyte-0.2.4 → agentbyte-0.3.0}/README.md

@@ -1,20 +1,22 @@
 <p align="center">
-  <img src="logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.3.0/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
 </p>
 
 # Agentbyte
 
-Agentbyte is a Python toolkit for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
+Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.2.1**
+Current release: **0.3.0**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
-## What’s New in 0.2.1
+## What's New in 0.3.0
 
-- Added explicit project URLs in package metadata (Homepage, Repository, Issues, Changelog).
-- Added MIT `LICENSE` file at repository root.
-- Expanded README install guidance for extras using `pip install` and `uv add`.
+- **Breaking:** `BaseAgent` no longer stores context. `self.context`, `reset_context()`, `clear_messages()`, `window_messages()`, and `reset()` are removed. `Agent.__init__` no longer accepts a `context=` kwarg.
+- `Agent.run(task=None, context=None, ...)` and `Agent.run_stream(task=None, context=None, ...)` accept a per-call `AgentContext`. A fresh context is created automatically when `None`.
+- `AgentResponse.context` returns the fully-populated working context to the caller — enables clean multi-turn patterns without agent-side state.
+- `AgentAsTool.execute()` and `execute_stream()` thread the caller-supplied context through to the underlying agent.
+- Notebooks, study docs (`topic_agents.md`, `topic_approval.md`), and OTel span guide (`topic_otel_spans.md`) updated to the caller-owned context pattern.
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
 
@@ -26,6 +28,36 @@ See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
 - Built-in middleware: logging, security, rate limiting, approval, telemetry.
 - Memory abstractions: list memory, file memory, context injection.
 - OpenAI and Azure OpenAI model client support.
+- OpenTelemetry-first tracing with model-call and task-level usage telemetry.
+
+## Observability-First Telemetry
+
+Agentbyte exposes two complementary telemetry layers:
+
+- **Per-call middleware spans** (`chat ...`, `tool ...`) for model/tool-level diagnostics.
+- **Task-level root span attributes** (`agent ...`) for final aggregated usage and outcome.
+
+Enable telemetry:
+
+```bash
+export AGENTBYTE_ENABLE_OTEL=true
+```
+
+Per-call span attributes emitted by `OTelMiddleware`:
+
+- `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.total_tokens`
+- `gen_ai.usage.cost_estimate_usd`
+- `gen_ai.response.finish_reason`
+- `gen_ai.request.model`
+- `gen_ai.tool.name`, `gen_ai.tool.success`
+
+## Degugging Traces without UI
+details can be found in the [OTel spans guide](docs/study/topic_otel_spans.md#debugging-traces-without-ui).
+
+Practical interpretation:
+
+- `chat gpt-4.1-mini` spans show **per-call** usage/cost/finish reason.
+- `agent <name>` span shows **final accumulated** usage and final task outcome.
 
 ## Installation
 
@@ -117,5 +149,4 @@ MIT — see [LICENSE](LICENSE).
 
 - [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
 - [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
-- [Pydantic AI](https://ai.pydantic.dev/)
 

{agentbyte-0.2.4 → agentbyte-0.3.0}/docker/jaeger-compose.yml

@@ -1,5 +1,3 @@
-version: "3.9"
-
 services:
   jaeger:
     image: jaegertracing/all-in-one:latest

agentbyte-0.3.0/docs/progress.md

@@ -0,0 +1,81 @@
+# Progress Log (Compact)
+
+This file keeps a concise, high-signal history of major milestones only.
+
+## 2026-03-06 — v0.3.0 (Breaking) Lock-Free Context Threading
+
+### Scope
+- Refactored agent execution to caller-owned context.
+- Removed agent-held mutable session state.
+- Updated docs/notebooks to match the new usage pattern.
+
+### Design Decision
+- `AgentContext` is passed per call and returned via `AgentResponse.context`.
+- This removes shared mutable state from agents and enables safe concurrent reuse.
+
+### Breaking Changes
+- Removed agent-owned context API:
+  - `self.context`
+  - `reset_context()`
+  - `clear_messages()`
+  - `window_messages()`
+  - `reset()`
+- `Agent.__init__(context=...)` no longer supported.
+
+### New Usage Pattern
+- `run(task=None, context=None, ...)`
+- `run_stream(task=None, context=None, ...)`
+- Continue multi-turn sessions by reusing `response.context`.
+
+### Related Updates
+- Agent-as-tool context threading updated.
+- Study docs and notebooks aligned with caller-owned context.
+- OTel trace guide clarified `args: {}` vs tool-parameter spans.
+
+### Validation
+- Ruff: passed.
+- Pytest: 256 passed.
+
+---
+
+## 2026-03-05 — OTel Simplification + Trace Inspector
+
+### Scope
+- Simplified OTel architecture and removed unnecessary root-span usage aggregation.
+- Added local Jaeger trace inspection utility.
+
+### Outcomes
+- Per-call `chat` and `tool` spans remain the primary observability surface.
+- Added `examples/otel/inspect_trace.py` for full trace/message inspection.
+- Updated tests and docs; suite remained green.
+
+---
+
+## 2026-03-02 — Session Model Unification
+
+### Scope
+- Unified conversation/workspace into a single session model.
+
+### Outcomes
+- Consolidated to `Session`, `BaseSession`, and `InMemorySession`.
+- Removed redundant conversation/workspace modules.
+- Updated context and package exports accordingly.
+
+---
+
+## 2026-02-26 to 2026-02-27 — Middleware/Memory/OTel Foundation
+
+### Scope
+- Completed Chapter 4.9/4.10-aligned foundations for middleware, memory operations, and telemetry.
+
+### Outcomes
+- Middleware streaming and approval flow integrated.
+- Memory tool and memory middleware routing added.
+- OTel middleware + auto instrumentation introduced and hardened.
+
+---
+
+## Current Status
+- Current release target in repository: **0.3.0**.
+- Primary branch is release-ready with validated tests.
+- Next: create release commit, tag `v0.3.0`, and push branch/tag.