agentbyte 0.4.3__tar.gz → 0.4.7__tar.gz

{agentbyte-0.4.3 → agentbyte-0.4.7}/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.4.7] - 2026-04-06
+
+### Added
+- Reorganised `agentbyte.llm` into provider packages: `agentbyte.llm.openai` (chat, embedding, settings) and `agentbyte.llm.azure` (chat, embedding, settings, auth). Base classes, shared types, and pricing remain at the `llm/` root. Thin compatibility shims preserve all existing flat `agentbyte.llm.*` import paths so downstream code is unaffected.
+- Added `agentbyte.llm._retry_observability` shared helper (`build_retry_record`, `build_retry_summary`). All four provider clients import from this single module so the retry record shape is defined once and consistent across providers.
+- Provider-owned retry observability in chat clients: `ChatCompletionResult.metadata["retry_observability"]` is now populated by `OpenAIChatCompletionClient` and `AzureOpenAIChatCompletionClient` when at least one retry occurred; key is absent on zero retries.
+- Provider-owned retry observability in embedding clients: `EmbeddingResult.metadata["retry_observability"]` is now populated by `OpenAIEmbeddingClient` and `AzureOpenAIEmbeddingClient` when at least one retry occurred; key is absent on zero retries.
+
+### Changed
+- Updated concept notebooks to reflect the new provider package layout and dual observability ownership model.
+- Updated retry design doc and middleware study doc to reflect Phase 2 streaming-tool retry path and the provider vs. middleware observability split.
+
+### Testing
+- Added 11 tests in `tests/llm/test_retry_observability.py` covering absent-on-zero-retries, correct structure on one retry, and accumulation across multiple retries for all four provider client combinations (OpenAI/Azure × chat/embedding).
+
+## [0.4.6] - 2026-04-06
+
+### Added
+- Added `RetryMiddleware` to `agentbyte.middleware` with MAF-style constructor config (`max_retries`, `initial_interval`, `backoff_factor`, `max_interval`, `jitter`, `retry_on`, `operation_types`).
+- Default `operation_types` covers `tool_call` and `memory_access`; `model_call` and `embedding_call` are excluded by default to avoid nested retry with existing provider-level retry in chat and embedding clients.
+- Streaming tools now retry via the shared middleware chain when a failure occurs before any user-visible output is emitted; retries are suppressed once output has started to prevent duplicate or corrupted stream output.
+- Added retry observability: each retry attempt is appended to `AgentContext.metadata["retry_observability"]["history"]` with attempt number, computed delay, exception type, and outcome; a `"latest"` summary key is also updated after each operation.
+
+### Fixed
+- Fixed a pre-existing gap in `MiddlewareChain.execute_stream()` where a `None` return from `process_error()` was incorrectly treated as a recovery value, suppressing the original exception. The inline error handler now applies the same `is not None` guard already present in `_execute_error_handlers()`.
+
+### Testing
+- Added 24 unit tests in `tests/middleware/test_retry_middleware.py` covering delays, jitter, operation filtering, stream retry, hook invocation counts, and retry observability.
+- Added 5 agent integration tests in `tests/agents/test_agent_retry_middleware.py` covering non-streaming tool retry, exhaustion surfacing, streaming tool pre-output retry, post-output no-retry, and approval-pause preservation.
+
+## [0.4.5] - 2026-03-27
+
+### Added
+- Added a new `agentbyte.presets` package with provider-aware `build_chat_client()` plus default `get_*` builders for query rewriter, researcher, writer, reviewer, orchestrators, and the default workflow.
+- Added a default presets example under `examples/presets/basic_presets.py`.
+- Added the `notebooks/usecases/08.1-default-presets.ipynb` use-case notebook to demonstrate preset agents, orchestrators, workflows, and streaming execution.
+
+### Changed
+- Moved the role-specific `researcher -> writer -> reviewer` workflow assembly into the presets layer so `agentbyte.workflow.defaults` remains focused on generic workflow templates.
+- Tightened the plan-based preset so reviewer feedback triggers writer revision and reviewer re-check loops until explicit approval is given.
+- Updated the plan-based preset final result behavior to prefer the latest approved writer draft instead of the reviewer approval message.
+
+### Testing
+- Added focused preset coverage for provider resolution, preset builders, reviewer approval gating, revision-loop insertion, and final-result selection.
+
+## [0.4.4] - 2026-03-26
+
+### Fixed
+- Corrected the release after `v0.4.3` published `0.4.2` package artifacts instead of `0.4.3`.
+
+### Changed
+- Added a mandatory release guardrail in repository instructions: clean `dist/`, rebuild with `uv build`, and verify artifact filenames/version metadata before creating or pushing a release tag.
+
 ## [0.4.3] - 2026-03-26
 
 ### Added

{agentbyte-0.4.3 → agentbyte-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.4.3
+Version: 0.4.7
 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
@@ -36,17 +36,35 @@ Requires-Dist: uvicorn>=0.42.0; extra == 'webui'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.3/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.7/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
 </p>
 
 # Agentbyte
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.4.3**
+Current release: **0.4.7**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.4.7
+
+- Reorganised `agentbyte.llm` into provider packages: `agentbyte.llm.openai` and `agentbyte.llm.azure`. All existing flat `agentbyte.llm.*` imports continue to work via compatibility shims.
+- Added shared `_retry_observability` helper — single retry record shape used by all provider clients.
+- Provider-owned retry observability: `ChatCompletionResult.metadata["retry_observability"]` and `EmbeddingResult.metadata["retry_observability"]` populated on retries; absent when no retries occurred. Covers OpenAI and Azure chat and embedding clients.
+- Updated concept notebooks and study docs to reflect the new layout and dual observability ownership model.
+
+## What's New in 0.4.5
+
+- Added a new `agentbyte.presets` package with provider-aware `build_chat_client()` plus default `get_*` builders for agents, orchestrators, and workflows.
+- Added a review-gated plan-based preset flow so reviewer feedback now triggers writer revision loops until explicit `APPROVED`.
+- Added the `notebooks/usecases/08.1-default-presets.ipynb` use-case notebook to demonstrate preset agents, orchestrators, workflows, and streaming.
+
+## What's New in 0.4.4
+
+- Corrected the release after `v0.4.3` published `0.4.2` artifacts in CI.
+- Added a mandatory release guardrail to clean `dist/`, rebuild, and verify artifact filenames before tagging.
+
 ## What's New in 0.4.3
 
 - Added a new `agentbyte-plan-based-orchestration` Copilot skill for Chapter 7.5 plan-based orchestration.

{agentbyte-0.4.3 → agentbyte-0.4.7}/README.md

@@ -1,15 +1,33 @@
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.3/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.7/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
 </p>
 
 # Agentbyte
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.4.3**
+Current release: **0.4.7**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.4.7
+
+- Reorganised `agentbyte.llm` into provider packages: `agentbyte.llm.openai` and `agentbyte.llm.azure`. All existing flat `agentbyte.llm.*` imports continue to work via compatibility shims.
+- Added shared `_retry_observability` helper — single retry record shape used by all provider clients.
+- Provider-owned retry observability: `ChatCompletionResult.metadata["retry_observability"]` and `EmbeddingResult.metadata["retry_observability"]` populated on retries; absent when no retries occurred. Covers OpenAI and Azure chat and embedding clients.
+- Updated concept notebooks and study docs to reflect the new layout and dual observability ownership model.
+
+## What's New in 0.4.5
+
+- Added a new `agentbyte.presets` package with provider-aware `build_chat_client()` plus default `get_*` builders for agents, orchestrators, and workflows.
+- Added a review-gated plan-based preset flow so reviewer feedback now triggers writer revision loops until explicit `APPROVED`.
+- Added the `notebooks/usecases/08.1-default-presets.ipynb` use-case notebook to demonstrate preset agents, orchestrators, workflows, and streaming.
+
+## What's New in 0.4.4
+
+- Corrected the release after `v0.4.3` published `0.4.2` artifacts in CI.
+- Added a mandatory release guardrail to clean `dist/`, rebuild, and verify artifact filenames before tagging.
+
 ## What's New in 0.4.3
 
 - Added a new `agentbyte-plan-based-orchestration` Copilot skill for Chapter 7.5 plan-based orchestration.

{agentbyte-0.4.3 → agentbyte-0.4.7}/pyproject.toml

@@ -72,11 +72,14 @@ include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md", "/.githu
 [dependency-groups]
 dev = [
     "ipykernel>=7.1.0",
-    "picoagents>=0.4.0",
     "pydantic-settings>=2.13.0",
     "pymupdf-layout>=1.26.6",
     "pymupdf4llm>=0.2.9",
 ]
+extlib = [
+    "agent-framework-core>=1.0.0",
+    "agent-framework-openai>=1.0.0",
+]
 otel = [
     "opentelemetry-api>=1.39.1",
     "opentelemetry-exporter-otlp-proto-http>=1.39.1",

{agentbyte-0.4.3 → agentbyte-0.4.7}/src/agentbyte/__about__.py

@@ -1,2 +1,2 @@
-__version__ = "0.4.3"
+__version__ = "0.4.7"
 VERSION = __version__

{agentbyte-0.4.3 → agentbyte-0.4.7}/src/agentbyte/__init__.py

@@ -34,6 +34,18 @@ from agentbyte.orchestration import (
     RoundRobinOrchestrator,
     StepProgressEvaluation,
 )
+from agentbyte.presets import (
+    build_chat_client,
+    get_ai_orchestrator,
+    get_orchestrator,
+    get_plan_based_orchestrator,
+    get_query_rewriter,
+    get_researcher,
+    get_reviewer,
+    get_round_robin_orchestrator,
+    get_workflow,
+    get_writer,
+)
 from agentbyte.session import BaseSession, InMemorySession, Session
 from agentbyte.termination import (
     BaseTermination,
@@ -80,6 +92,17 @@ __all__ = [
     "PlanStep",
     "RoundRobinOrchestrator",
     "StepProgressEvaluation",
+    # Presets
+    "build_chat_client",
+    "get_query_rewriter",
+    "get_researcher",
+    "get_writer",
+    "get_reviewer",
+    "get_orchestrator",
+    "get_round_robin_orchestrator",
+    "get_ai_orchestrator",
+    "get_plan_based_orchestrator",
+    "get_workflow",
     # Termination
     "BaseTermination",
     "MaxMessageTermination",

{agentbyte-0.4.3 → agentbyte-0.4.7}/src/agentbyte/agents/agent.py

@@ -21,7 +21,7 @@ from agentbyte.messages import (
     UserMessage,
 )
 from agentbyte.types import ToolResult
-from agentbyte.middleware.base import MiddlewareContext, OperationType
+from agentbyte.middleware.base import OperationType
 from agentbyte.tools import ApprovalMode
 
 from .base import AgentConfigurationError, AgentExecutionError, BaseAgent
@@ -162,81 +162,87 @@ class Agent(BaseAgent):
                 return
 
         if tool.supports_streaming():
-            streamed_result: Optional[ToolResult] = None
-            middleware_context = MiddlewareContext(
-                operation=OperationType.TOOL_CALL,
-                agent_name=self.name,
-                agent_context=working_context,
-                data={
-                    "tool_name": tool_call.tool_name,
-                    "parameters": tool_call.parameters,
-                    "call_id": tool_call.call_id,
-                },
-                metadata={},
-            )
-
             try:
-                for middleware in self.middleware_chain.middlewares:
-                    final_context: MiddlewareContext | None = None
-                    async for item in self.middleware_chain._iter_hook_items(  # type: ignore[attr-defined]
-                        middleware.process_request(middleware_context)
-                    ):
-                        if isinstance(item, MiddlewareContext):
-                            final_context = item
-                        elif isinstance(item, BaseEvent):
-                            if verbose or isinstance(item, ToolApprovalEvent):
-                                yield item
 
-                            if isinstance(item, ToolApprovalEvent):
-                                return
+                async def _execute_streaming_tool(
+                    payload: dict[str, object],
+                ) -> AsyncGenerator[object, None]:
+                    tool_parameters = payload.get("parameters", {})
+                    if not isinstance(tool_parameters, dict):
+                        raise ValueError(
+                            "tool_call payload parameters must be a dictionary"
+                        )
 
-                    if final_context is not None:
-                        middleware_context = final_context
+                    async for item in tool.execute_stream(
+                        tool_parameters,
+                        cancellation_token,
+                    ):
+                        yield item
 
-                async for item in tool.execute_stream(
-                    middleware_context.data.get("parameters", tool_call.parameters),
-                    cancellation_token,
+                streamed_result: object | None = None
+                async for item in self.middleware_chain.execute_tool_stream(
+                    operation=OperationType.TOOL_CALL,
+                    agent_name=self.name,
+                    agent_context=working_context,
+                    data={
+                        "tool_name": tool_call.tool_name,
+                        "parameters": tool_call.parameters,
+                        "call_id": tool_call.call_id,
+                    },
+                    func=_execute_streaming_tool,
                 ):
+                    if isinstance(item, BaseEvent):
+                        if verbose or isinstance(item, ToolApprovalEvent):
+                            yield item
+
+                        if isinstance(item, ToolApprovalEvent):
+                            return
+
+                        continue
+
                     if isinstance(item, ToolResult):
                         streamed_result = item
                     else:
                         yield item
 
-            except Exception as exc:
-                recovered, recovery = await self.middleware_chain._execute_error_handlers(  # type: ignore[attr-defined]
-                    middleware_context, exc
+                if streamed_result is None:
+                    raise AgentExecutionError(
+                        "Streaming tool middleware execution did not yield a final result"
+                    )
+
+                tool_message = ToolMessage(
+                    content=str(streamed_result.result)
+                    if streamed_result.success
+                    else (streamed_result.error or ""),
+                    source=self.name,
+                    tool_call_id=tool_call.call_id,
+                    tool_name=tool_call.tool_name,
+                    success=streamed_result.success,
+                    error=streamed_result.error,
                 )
-                if recovered and isinstance(recovery, ToolResult):
-                    streamed_result = recovery
-                else:
-                    message = ToolMessage(
-                        content=f"Tool execution failed: {exc}",
+                working_context.add_message(tool_message)
+                yield tool_message
+
+                if verbose:
+                    yield ToolCallResponseEvent(
                         source=self.name,
-                        tool_call_id=tool_call.call_id,
-                        tool_name=tool_call.tool_name,
-                        success=False,
-                        error=str(exc),
+                        call_id=tool_call.call_id,
+                        result=streamed_result,
                     )
-                    working_context.add_message(message)
 
-                    if verbose:
-                        yield ToolCallResponseEvent(
-                            source=self.name,
-                            call_id=tool_call.call_id,
-                            result=None,
-                        )
-
-                    yield message
-                    return
+                return
+            except Exception as exc:
+                error_message = str(exc)
+                if error_message == "Streaming tool returned no final result":
+                    error_message = "Streaming tool middleware execution did not yield a final result"
 
-            if streamed_result is None:
                 message = ToolMessage(
-                    content="Tool execution failed: streaming tool returned no final result",
+                    content=f"Tool execution failed: {error_message}",
                     source=self.name,
                     tool_call_id=tool_call.call_id,
                     tool_name=tool_call.tool_name,
                     success=False,
-                    error="Streaming tool returned no final result",
+                    error=error_message,
                 )
                 working_context.add_message(message)
 
@@ -250,51 +256,6 @@ class Agent(BaseAgent):
                 yield message
                 return
 
-            final_result = streamed_result
-            try:
-                for middleware in reversed(self.middleware_chain.middlewares):
-                    transformed_result = final_result
-                    async for item in self.middleware_chain._iter_hook_items(  # type: ignore[attr-defined]
-                        middleware.process_response(middleware_context, final_result)
-                    ):
-                        if isinstance(item, BaseEvent):
-                            if verbose or isinstance(item, ToolApprovalEvent):
-                                yield item
-                            continue
-                        transformed_result = item
-                    if isinstance(transformed_result, ToolResult):
-                        final_result = transformed_result
-            except Exception as exc:
-                recovered, recovery = await self.middleware_chain._execute_error_handlers(  # type: ignore[attr-defined]
-                    middleware_context, exc
-                )
-                if recovered and isinstance(recovery, ToolResult):
-                    final_result = recovery
-                else:
-                    raise
-
-            tool_message = ToolMessage(
-                content=str(final_result.result)
-                if final_result.success
-                else (final_result.error or ""),
-                source=self.name,
-                tool_call_id=tool_call.call_id,
-                tool_name=tool_call.tool_name,
-                success=final_result.success,
-                error=final_result.error,
-            )
-            working_context.add_message(tool_message)
-            yield tool_message
-
-            if verbose:
-                yield ToolCallResponseEvent(
-                    source=self.name,
-                    call_id=tool_call.call_id,
-                    result=final_result,
-                )
-
-            return
-
         try:
 
             async def _execute_tool(payload: dict[str, object]) -> object:

{agentbyte-0.4.3 → agentbyte-0.4.7}/src/agentbyte/llm/__init__.py

@@ -33,21 +33,22 @@ from .base import (
 )
 from .embeddings_base import BaseEmbeddingClient, BaseEmbeddingClientConfig
 from .openai import OpenAIChatCompletionClient, OpenAIChatCompletionClientConfig
-from .openai_embedding import OpenAIEmbeddingClient, OpenAIEmbeddingClientConfig
-from .azure_openai import (
+from .openai import OpenAIEmbeddingClient, OpenAIEmbeddingClientConfig
+from .openai import OpenAISettings
+from .azure import (
     AzureOpenAIChatCompletionClient,
     AzureOpenAIChatCompletionClientConfig,
 )
-from .azure_openai_embedding import (
+from .azure import (
     AzureOpenAIEmbeddingClient,
     AzureOpenAIEmbeddingClientConfig,
 )
-from .auth import (
+from .azure import (
     get_default_token_provider,
     get_certificate_token_provider,
     create_token_provider_from_string,
 )
-from .settings import OpenAISettings, AzureOpenAISettings, AzureServicePrincipalSettings
+from .azure import AzureOpenAISettings, AzureServicePrincipalSettings
 # Import message types and usage from root module (picoagents-aligned)
 from agentbyte.messages import (
     BaseMessage,

agentbyte-0.4.7/src/agentbyte/llm/_retry_observability.py

@@ -0,0 +1,40 @@
+"""
+Shared retry observability utilities for LLM provider clients.
+
+All provider clients (OpenAI, Azure, Bedrock, Ollama, etc.) import from here
+so the retry record shape is defined once and consistent across providers.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Type
+
+
+def build_retry_record(
+    attempt: int,
+    delay: float,
+    exc_type: Type[BaseException],
+    outcome: str,
+) -> Dict[str, Any]:
+    """Build a single retry attempt record."""
+    return {
+        "attempt": attempt,
+        "delay_s": round(delay, 3),
+        "exception_type": exc_type.__name__,
+        "outcome": outcome,
+    }
+
+
+def build_retry_summary(history: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Build a summary dict from a completed retry history list."""
+    if not history:
+        return {}
+    last = history[-1]
+    return {
+        "total_attempts": len(history) + 1,
+        "retries": len(history),
+        "latest_exception_type": last["exception_type"],
+        "latest_outcome": last["outcome"],
+    }
+
+
+__all__ = ["build_retry_record", "build_retry_summary"]

agentbyte-0.4.7/src/agentbyte/llm/auth.py

@@ -0,0 +1,16 @@
+"""Compatibility shim for the legacy flat auth module path.
+
+Canonical imports now live under ``agentbyte.llm.azure.auth``.
+"""
+
+from .azure.auth import (
+    create_token_provider_from_string,
+    get_certificate_token_provider,
+    get_default_token_provider,
+)
+
+__all__ = [
+    "get_default_token_provider",
+    "get_certificate_token_provider",
+    "create_token_provider_from_string",
+]

agentbyte-0.4.7/src/agentbyte/llm/azure/__init__.py

@@ -0,0 +1,22 @@
+"""Azure provider package."""
+
+from .auth import (
+    get_default_token_provider,
+    get_certificate_token_provider,
+    create_token_provider_from_string,
+)
+from .chat import AzureOpenAIChatCompletionClient, AzureOpenAIChatCompletionClientConfig
+from .embedding import AzureOpenAIEmbeddingClient, AzureOpenAIEmbeddingClientConfig
+from .settings import AzureOpenAISettings, AzureServicePrincipalSettings
+
+__all__ = [
+    "get_default_token_provider",
+    "get_certificate_token_provider",
+    "create_token_provider_from_string",
+    "AzureOpenAIChatCompletionClient",
+    "AzureOpenAIChatCompletionClientConfig",
+    "AzureOpenAIEmbeddingClient",
+    "AzureOpenAIEmbeddingClientConfig",
+    "AzureOpenAISettings",
+    "AzureServicePrincipalSettings",
+]

agentbyte-0.4.7/src/agentbyte/llm/azure/auth.py

@@ -0,0 +1,68 @@
+"""
+Authentication utility functions for creating token providers.
+
+Supports DefaultAzureCredential, certificate-based, and pre-fetched token auth.
+"""
+
+from typing import Callable
+
+
+def get_default_token_provider() -> Callable[[], str]:
+    """Create a token provider using DefaultAzureCredential."""
+    try:
+        from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+    except ImportError:
+        raise ImportError(
+            "azure-identity is required for DefaultAzureCredential. "
+            "Install with: pip install azure-identity"
+        )
+
+    credentials = DefaultAzureCredential()
+    token_provider = get_bearer_token_provider(
+        credentials, "https://cognitiveservices.azure.com/.default"
+    )
+    return token_provider
+
+
+def get_certificate_token_provider(
+    tenant_id: str,
+    client_id: str,
+    certificate_data: bytes,
+    scope: str = "https://cognitiveservices.azure.com/.default",
+) -> Callable[[], str]:
+    """Create a token provider using X.509 certificate authentication."""
+    try:
+        from azure.identity import CertificateCredential
+    except ImportError:
+        raise ImportError(
+            "azure-identity is required for CertificateCredential. "
+            "Install with: pip install azure-identity"
+        )
+
+    credential = CertificateCredential(
+        tenant_id=tenant_id,
+        client_id=client_id,
+        certificate_data=certificate_data,
+    )
+
+    def token_provider() -> str:
+        token = credential.get_token(scope)
+        return token.token
+
+    return token_provider
+
+
+def create_token_provider_from_string(token: str) -> Callable[[], str]:
+    """Create a simple token provider from a pre-authenticated token."""
+
+    def token_provider() -> str:
+        return token
+
+    return token_provider
+
+
+__all__ = [
+    "get_default_token_provider",
+    "get_certificate_token_provider",
+    "create_token_provider_from_string",
+]