agentbyte 0.1.2__tar.gz → 0.2.0__tar.gz

{agentbyte-0.1.2 → agentbyte-0.2.0}/.github/copilot-instructions.md

@@ -14,6 +14,21 @@ The development approach is iterative and intentional: understand a pattern from
 
 We will work **chapter-by-chapter** starting from **Chapter 4** in [docs/chapters](../docs/chapters/), studying each chapter, then **implementing the concepts ourselves** in Agentbyte. Chapters may be **skipped when not relevant** to the current implementation phase. Each chapter follows a **learn → implement → validate** loop, with examples used only as references (no direct copying). We will skip certain chapters and comeback to them later when relevant to the current implementation phase. The focus is on **deep understanding** and **intentional design**, not just code replication.
 
+**Important: Book Chapters vs. Picoagents Codebase**
+- **Book chapters** [docs/chapters](../docs/chapters/) provide **sequential building concepts** and high-level architecture explanations, but do NOT contain complete implementation code
+- **Picoagents codebase** [external_lib/designing-multiagent-systems/picoagents/src/picoagents/](../external_lib/designing-multiagent-systems/picoagents/src/picoagents/) contains the **complete, production-ready implementation** of all concepts
+- **Our workflow**: 
+  1. Study the **concept** from book chapter (understand the "why" and architecture)
+  2. When ready to implement, **review the actual code** in picoagents codebase (understand the "how")
+  3. Implement in Agentbyte with our own design decisions and enhancements
+  4. Validate with tests and examples
+
+### Chapter Lookup Rule (Mandatory)
+
+- When the user mentions the book, a chapter number, or a section title, always read from `docs/chapters/chapter_<n>.md` first.
+- If the user specifies a particular section/range (for example, "4.9.4" or line ranges), focus only on that specific subsection before broader chapter reading.
+- Treat chapter files under `docs/chapters/` as the primary source for conceptual guidance; use picoagents source code afterward for implementation parity details.
+
 - Study plan should be created for chapters in [study](../docs/study/)
 - When implementing tools (Chapter 4.6.4), follow the step-by-step guide in [docs/study/topic_tools.md](../docs/study/topic_tools.md). Use its file creation steps, class responsibilities, and parity checklist as the execution plan.
 
@@ -381,6 +396,16 @@ src/agentbyte/
 - Hides dependency issues that should be architectural problems
 - Requires runtime model rebuilding as workaround
 
+❌ **Don't**: Create mutual concrete imports between collaborating modules
+- Example risk: `agents/base.py` importing `agents/agent_as_tool.py` while `agent_as_tool.py` imports `BaseAgent`
+- This creates fragile import-order coupling and can regress as modules grow
+
+✅ **Do**: Break cycles with protocol/contract boundaries
+- Prefer structural interfaces (`Protocol`) for collaborator typing instead of importing concrete classes
+- Keep adapters/wrappers (like Agent-as-Tool) dependent on minimal runtime contracts (`name`, `description`, `run`, `run_stream`)
+- Use local/lazy imports only as a secondary tactic, not as the primary architecture
+- If a cycle appears, refactor shared abstractions into a neutral module or protocol contract first
+
 ❌ **Don't**: Create `tools/types.py` for single `ToolResult`
 - Too granular; root `types.py` is appropriate for framework fundamentals
 - `ToolResult` is as fundamental as Message types
@@ -487,6 +512,12 @@ src/agentbyte/
 - Use settings classes for all configuration management, never hard-code values
 - Our code is uv to have a packaged applciation which means we do not need to import from src but from agentbyte directly. For example, in our notebooks we should import from agentbyte like `from agentbyte.tools import FunctionTool` instead of `from src.agentbyte.tools import FunctionTool`
 - Notebook already has a async main thread so do not use `asyncio.run()` in the notebooks, just call the async function directly like `await test_example1()`
+- **Pydantic v2 config standard (mandatory):**
+  - ✅ Use `model_config = ConfigDict(...)` for model configuration
+  - ❌ Do NOT use inner `class Config` in `BaseModel` subclasses (deprecated in Pydantic v2, removed in v3)
+  - Example:
+    - ✅ `from pydantic import BaseModel, ConfigDict`
+    - ✅ `class MyModel(BaseModel): model_config = ConfigDict(frozen=True)`
 - **Run ruff check after creating any code** to ensure code quality:
   - Check for unused imports: `uv run ruff check <file_or_dir> --select F401`
   - Run full checks: `uv run ruff check <file_or_dir>`

agentbyte-0.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to Agentbyte are documented in this file.
+
+The format follows Keep a Changelog principles and semantic versioning.
+
+## [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.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: agentbyte
+Version: 0.2.0
+Summary: A toolkit for designing multiagent systems
+Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: all
+Requires-Dist: azure-identity>=1.25.1; extra == 'all'
+Requires-Dist: openai>=1.107.1; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.39.1; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'all'
+Provides-Extra: azureopenai
+Requires-Dist: azure-identity>=1.25.1; extra == 'azureopenai'
+Requires-Dist: openai>=1.107.1; extra == 'azureopenai'
+Provides-Extra: openai
+Requires-Dist: openai>=1.107.1; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.39.1; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# Agentbyte
+
+Agentbyte is a Python toolkit for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
+
+Current release: **0.2.0**
+
+## What’s New in 0.2.0
+
+- Memory parity upgrades (`ListMemory`/`FileMemory` serialization config support).
+- Agent-managed memory tooling (`MemoryTool`, sandboxed `MemoryBackend`).
+- Middleware parity improvements (`ApprovalMiddleware`, `memory_access` routing).
+- OpenTelemetry middleware + opt-in auto-instrumentation support.
+- New notebook coverage for real-client middleware workflows.
+
+See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
+
+## Current Capabilities
+
+- Agent execution loop with `run()` and `run_stream()` APIs.
+- Tooling system (function tools + core tools + memory tool).
+- Middleware chain for request/response/error handling.
+- Built-in middleware: logging, security, rate limiting, approval, telemetry.
+- Memory abstractions: list memory, file memory, context injection.
+- OpenAI and Azure OpenAI model client support.
+
+## Installation
+
+```bash
+uv sync --all-groups
+```
+
+Optional extras:
+
+```bash
+uv sync --extra openai
+uv sync --extra azureopenai
+uv sync --extra otel
+```
+
+### Install in another project (pip / uv add)
+
+Use extras to enable provider + telemetry support:
+
+```bash
+pip install "agentbyte[azureopenai,otel]"
+```
+
+```bash
+uv add "agentbyte[azureopenai,otel]"
+```
+
+Install all optional features:
+
+```bash
+pip install "agentbyte[all]"
+# or
+uv add "agentbyte[all]"
+```
+
+Note: the Azure extra is `azureopenai`.
+
+## Quick Start
+
+```python
+from agentbyte.agents import Agent
+from agentbyte.middleware import LoggingMiddleware
+
+# model_client = OpenAIChatCompletionClient(...) or AzureOpenAIChatCompletionClient(...)
+
+def quick_faq_lookup(topic: str) -> str:
+    faq = {
+        "middleware": "Middleware handles cross-cutting runtime concerns.",
+        "memory": "Memory helps agents keep useful context across interactions.",
+    }
+    return faq.get(topic.lower(), "No FAQ found.")
+
+agent = Agent(
+    name="helpful-assistant",
+    description="Helpful assistant with middleware",
+    instructions="Answer clearly and use tools when needed.",
+    model_client=model_client,
+    tools=[quick_faq_lookup],
+    middlewares=[LoggingMiddleware()],
+)
+```
+
+## Project Layout
+
+```
+src/agentbyte/
+  agents/
+  llm/
+  memory/
+  middleware/
+  tools/
+  messages.py
+  context.py
+  types.py
+```
+
+## Development
+
+```bash
+uv run ruff check src tests
+uv run pytest tests -v
+```
+
+## References
+
+- [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.0/README.md

@@ -0,0 +1,113 @@
+# Agentbyte
+
+Agentbyte is a Python toolkit for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
+
+Current release: **0.2.0**
+
+## What’s New in 0.2.0
+
+- Memory parity upgrades (`ListMemory`/`FileMemory` serialization config support).
+- Agent-managed memory tooling (`MemoryTool`, sandboxed `MemoryBackend`).
+- Middleware parity improvements (`ApprovalMiddleware`, `memory_access` routing).
+- OpenTelemetry middleware + opt-in auto-instrumentation support.
+- New notebook coverage for real-client middleware workflows.
+
+See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
+
+## Current Capabilities
+
+- Agent execution loop with `run()` and `run_stream()` APIs.
+- Tooling system (function tools + core tools + memory tool).
+- Middleware chain for request/response/error handling.
+- Built-in middleware: logging, security, rate limiting, approval, telemetry.
+- Memory abstractions: list memory, file memory, context injection.
+- OpenAI and Azure OpenAI model client support.
+
+## Installation
+
+```bash
+uv sync --all-groups
+```
+
+Optional extras:
+
+```bash
+uv sync --extra openai
+uv sync --extra azureopenai
+uv sync --extra otel
+```
+
+### Install in another project (pip / uv add)
+
+Use extras to enable provider + telemetry support:
+
+```bash
+pip install "agentbyte[azureopenai,otel]"
+```
+
+```bash
+uv add "agentbyte[azureopenai,otel]"
+```
+
+Install all optional features:
+
+```bash
+pip install "agentbyte[all]"
+# or
+uv add "agentbyte[all]"
+```
+
+Note: the Azure extra is `azureopenai`.
+
+## Quick Start
+
+```python
+from agentbyte.agents import Agent
+from agentbyte.middleware import LoggingMiddleware
+
+# model_client = OpenAIChatCompletionClient(...) or AzureOpenAIChatCompletionClient(...)
+
+def quick_faq_lookup(topic: str) -> str:
+    faq = {
+        "middleware": "Middleware handles cross-cutting runtime concerns.",
+        "memory": "Memory helps agents keep useful context across interactions.",
+    }
+    return faq.get(topic.lower(), "No FAQ found.")
+
+agent = Agent(
+    name="helpful-assistant",
+    description="Helpful assistant with middleware",
+    instructions="Answer clearly and use tools when needed.",
+    model_client=model_client,
+    tools=[quick_faq_lookup],
+    middlewares=[LoggingMiddleware()],
+)
+```
+
+## Project Layout
+
+```
+src/agentbyte/
+  agents/
+  llm/
+  memory/
+  middleware/
+  tools/
+  messages.py
+  context.py
+  types.py
+```
+
+## Development
+
+```bash
+uv run ruff check src tests
+uv run pytest tests -v
+```
+
+## References
+
+- [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.0/docker/jaeger-compose.yml

@@ -0,0 +1,11 @@
+version: "3.9"
+
+services:
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: agentbyte-jaeger
+    ports:
+      - "16686:16686"  # Jaeger UI
+      - "4318:4318"    # OTLP HTTP receiver
+    environment:
+      - COLLECTOR_OTLP_ENABLED=true