agentbyte 0.30.1__tar.gz → 0.32.0__tar.gz

{agentbyte-0.30.1 → agentbyte-0.32.0}/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [Unreleased]
+
+## [0.32.0] - 2026-09-30
+
+Upgrade notes (breaking):
+
+- Optional extras are grouped by database driver. `dataset`, `workflow-sqlite` and `eval-history` are removed; install `agentbyte[sqlite]` instead. pip only warns about an unknown extra, so update install lines before upgrading.
+- New `postgres` extra (`sqlalchemy[asyncio]`, `sqlmodel`, `asyncpg`) for `SqlUsageBackend` and `SqlEvalRunStore`; `sql` is now `sqlite` + `postgres` and installs the same packages as before, plus `greenlet` via `sqlalchemy[asyncio]`.
+
+### Added
+
+- Evaluation history (spec 0051): new `agentbyte.eval.history` with `EvalRunRecorder` (bounded, index-ordered scheduling; each outcome committed before it is yielded; cancellation and stream close account for every planned item), `EvalRunStore`, `MemoryEvalRunStore` and native-async `SQLiteEvalRunStore` (new `sqlite` extra). Summary capture by default (no transcripts, reasoning or error text); opt-in full capture with a redaction hook and data-only reload of structured output (`StructuredPayload`). Transactional item/counter/revision commits, idempotent replays, explicit `recover_interrupted()`, exclusive single-writer ownership, versioned schema and evidence, atomic owner-scoped admission. Errors: `EvalPersistenceError`, `EvalSerializationError`, `EvalSchemaVersionError`, `EvalStoreOwnershipError`, `EvalQueueFullError`, `EvalHistoryConflictError`.
+- Swappable evaluation history backends: `SqlEvalRunStore` for PostgreSQL through a caller-owned SQLAlchemy session factory (`postgres` extra; row locks, advisory-lock single writer, optional schema, `history_metadata()` for Alembic), public `agentbyte.eval.history.transitions`, and the reusable `agentbyte.eval.history.conformance` suite for custom stores.
+- `EvalRunner.evaluate_task()`: public single-task scoring used by the recorder (previously private `_evaluate_single_task`).
+
+## [0.31.0] - 2026-09-30
+
+Upgrade notes (breaking):
+
+- `ContextCompactionMiddleware(max_tokens=..., keep_last=...)` → `ContextCompactionMiddleware(max_input_tokens=...)`; read counts from `metadata["compaction"]`.
+- Middleware that rewrites a `model_call` payload must keep its keys: `context.data = {**context.data, "messages": new}`.
+- Multi-call approval batches return every approval request at once; loop over `response.approval_requests`.
+- Workflow steps must write back changed state explicitly (`context.set(...)`); in-place mutation of a value read from `WorkflowContext` no longer persists.
+
+### Added
+
+- Workflow reliability (spec 0058): optional native-async `SQLiteCheckpointStore` (new `workflow-sqlite` extra, lazily imported driver) with immutable checkpoint IDs and per-run retention; checkpoint schema v2 with staged continuation and accepted responses (v1 checkpoints still load); `CheckpointStore.load_latest(..., execution_id=...)`; multiple nested input requests per step with batch validation and partial resume (`BaseStep.resume_from_requests`, `validate_resume_responses`); `WorkflowStateIsolationError`, `WorkflowCheckpointError`, `CheckpointConflictError`.
+- Context compaction (spec 0049): new `agentbyte.compaction` package with `HeadTailCompaction`, `SlidingWindowCompaction`, `CharacterTokenCounter`, optional `TiktokenCounter` and `CompactionResult`. Tool-call batches and their results are kept or removed whole; system messages and the current turn are always kept; the budget covers messages, tools and output schema. Mandatory content that cannot fit raises `ContextBudgetExceeded` before any provider call.
+- `BaseMiddleware.finalize_request` and `validate_request` hooks: after every `process_request`, the chain runs all `finalize_request` hooks (may change the payload), then all read-only `validate_request` hooks, immediately before the operation. A validator that changes the payload raises `MiddlewareContractError`.
+- Tool message metadata (spec 0056): `ToolMessage.metadata` keeps an independent copy of the final `ToolResult.metadata` (e.g. `AgentAsTool` child usage) across run, streaming, approval resume and failed results. Sessions and checkpoints preserve it; model-provider requests never include it. Records without the field load as `{}`.
+
+### Changed
+
+- **Breaking:** the agent no longer falls back to its own messages, tools or output format when middleware removes those keys from a `model_call` payload; a missing key raises. Set a key to `None` to omit it.
+- Passing a new task while the conversation ends with an unresolved tool-call batch now ends the run with `finish_reason="error"` instead of sending an invalid history; resume with `task=None` first.
+- **Breaking:** `ContextCompactionMiddleware` now takes keyword-only `max_input_tokens` (required), `strategy` and `counter`; `max_tokens` and `keep_last` were removed without aliases, and the fabricated summary placeholder is gone. Malformed, orphan or unresolved tool exchanges now raise `ToolExchangeError`/`PendingToolExchangeError` instead of being sent. Metadata moved to `metadata["compaction"]`, with per-pass counts in `passes`.
+- **Breaking:** `ToolResult.metadata` and `ToolMessage.metadata` accept JSON values only (string-keyed objects, lists, strings, finite numbers, booleans, null). Tuples, enums, non-string keys, `Path`, `datetime`, models, NaN/inf raise `ToolMetadataError` (a `TypeError`); a custom tool producing such metadata now fails its call instead of succeeding.
+- Tool metadata is now present on every `ToolMessage` sent by the WebUI server and stored in sessions, not only in verbose tool-response events.
+- `CalculatorTool` no longer duplicates the computed value in metadata, so non-finite and complex results still succeed.
+- **Breaking:** workflow staged state is isolated: `WorkflowContext` reads return detached copies, so steps must write changes back explicitly; values that cannot be isolated raise `WorkflowStateIsolationError`. Checkpoints are taken at quiescent recovery boundaries, and persistence failures stop the run with `WorkflowCheckpointError` instead of continuing unsaved.
+- `FileCheckpointStore` is deprecated (legacy blocking backend); use `SQLiteCheckpointStore` or an application durable store. Migration guidance is in the workflow skill and checkpoint study topic. FastAPI still persists through its session store.
+
+### Documentation
+
+- Context compaction notebook (`notebooks/concepts/agent/10-context-compaction.ipynb`) and FastAPI example (`examples/compaction/`) showing budgets, 413/409 mapping, turn rollback, SSE and a context meter.
+- Proposed spec 0059 (summarizing compaction).
+
+### Fixed
+
+- Multi-call tool batches stay complete across approval pauses: calls after the first approval-gated call are no longer skipped (previously the model received tool calls without results after resume). All gated calls in a batch request approval in one round; resume runs the rest in original order; missing decisions keep `approval_needed` without a model call.
+- Cancelling mid-batch records a failed `ToolMessage` (`error="Cancelled"`) for each call that did not run, so the session stays valid for the next task.
+
 ## [0.30.1] - 2026-09-30
 
 ### Fixed

{agentbyte-0.30.1 → agentbyte-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.30.1
+Version: 0.32.0
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -25,7 +25,7 @@ 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'
-Requires-Dist: sqlalchemy>=2.0.43; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.43; extra == 'all'
 Requires-Dist: sqlmodel>=0.0.38; extra == 'all'
 Requires-Dist: uvicorn>=0.42.0; extra == 'all'
 Requires-Dist: youtube-transcript-api>=0.6; extra == 'all'
@@ -35,8 +35,6 @@ Provides-Extra: azureopenai
 Requires-Dist: azure-identity>=1.25.1; extra == 'azureopenai'
 Requires-Dist: openai>=1.107.1; extra == 'azureopenai'
 Provides-Extra: coding
-Provides-Extra: dataset
-Requires-Dist: aiosqlite>=0.22.1; extra == 'dataset'
 Provides-Extra: dev
 Requires-Dist: ipykernel>=7.1.0; extra == 'dev'
 Requires-Dist: nbclient>=0.10.4; extra == 'dev'
@@ -53,6 +51,10 @@ 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'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.31.0; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.43; extra == 'postgres'
+Requires-Dist: sqlmodel>=0.0.38; extra == 'postgres'
 Provides-Extra: research
 Requires-Dist: arxiv>=2.1; extra == 'research'
 Requires-Dist: beautifulsoup4>=4.12; extra == 'research'
@@ -61,8 +63,10 @@ Requires-Dist: youtube-transcript-api>=0.6; extra == 'research'
 Provides-Extra: sql
 Requires-Dist: aiosqlite>=0.22.1; extra == 'sql'
 Requires-Dist: asyncpg>=0.31.0; extra == 'sql'
-Requires-Dist: sqlalchemy>=2.0.43; extra == 'sql'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.43; extra == 'sql'
 Requires-Dist: sqlmodel>=0.0.38; extra == 'sql'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.22.1; extra == 'sqlite'
 Provides-Extra: test
 Requires-Dist: aiosqlite>=0.22.1; extra == 'test'
 Requires-Dist: arxiv>=2.1; extra == 'test'
@@ -86,7 +90,7 @@ Description-Content-Type: text/markdown
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.30.1**
+Current release: **0.32.0**
 
 ## Building an Agent
 
@@ -305,10 +309,17 @@ uv sync --all-groups
 Optional extras:
 
 ```bash
-uv sync --extra openai
-uv sync --extra azureopenai
-uv sync --extra otel
-uv sync --extra webui
+uv sync --extra openai        # OpenAI client
+uv sync --extra azureopenai   # Azure OpenAI client + azure-identity
+uv sync --extra aws           # S3 datasets (aioboto3)
+uv sync --extra otel          # OpenTelemetry export
+uv sync --extra webui         # WebUI playground (FastAPI)
+uv sync --extra sqlite        # SQLite stores: datasets, workflow checkpoints, eval history
+uv sync --extra postgres      # PostgreSQL stores: usage logging, eval history
+uv sync --extra sql           # sqlite + postgres
+uv sync --extra optim         # prompt optimization (GEPA)
+uv sync --extra viz           # workflow diagrams (graphviz)
+uv sync --extra research      # research tools
 ```
 
 ### Install in another project (pip / uv add)

{agentbyte-0.30.1 → agentbyte-0.32.0}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.30.1**
+Current release: **0.32.0**
 
 ## Building an Agent
 
@@ -221,10 +221,17 @@ uv sync --all-groups
 Optional extras:
 
 ```bash
-uv sync --extra openai
-uv sync --extra azureopenai
-uv sync --extra otel
-uv sync --extra webui
+uv sync --extra openai        # OpenAI client
+uv sync --extra azureopenai   # Azure OpenAI client + azure-identity
+uv sync --extra aws           # S3 datasets (aioboto3)
+uv sync --extra otel          # OpenTelemetry export
+uv sync --extra webui         # WebUI playground (FastAPI)
+uv sync --extra sqlite        # SQLite stores: datasets, workflow checkpoints, eval history
+uv sync --extra postgres      # PostgreSQL stores: usage logging, eval history
+uv sync --extra sql           # sqlite + postgres
+uv sync --extra optim         # prompt optimization (GEPA)
+uv sync --extra viz           # workflow diagrams (graphviz)
+uv sync --extra research      # research tools
 ```
 
 ### Install in another project (pip / uv add)

{agentbyte-0.30.1 → agentbyte-0.32.0}/pyproject.toml

@@ -38,14 +38,16 @@ webui = [
     "fastapi>=0.135.2",
     "uvicorn[standard]>=0.44.0",
 ]
-dataset = [
+sqlite = [
     "aiosqlite>=0.22.1",
 ]
-sql = [
-    "sqlalchemy>=2.0.43",
+postgres = [
+    "sqlalchemy[asyncio]>=2.0.43",
     "sqlmodel>=0.0.38",
     "asyncpg>=0.31.0",
-    "aiosqlite>=0.22.1",
+]
+sql = [
+    "agentbyte[sqlite,postgres]",
 ]
 optim = [
     "gepa>=0.1",
@@ -86,7 +88,7 @@ all = [
     "openai>=1.107.1",
     "azure-identity>=1.25.1",
     "aioboto3>=15.5.0",
-    "sqlalchemy>=2.0.43",
+    "sqlalchemy[asyncio]>=2.0.43",
     "sqlmodel>=0.0.38",
     "asyncpg>=0.31.0",
     "aiosqlite>=0.22.1",
@@ -194,7 +196,7 @@ all = [
     "openai>=1.107.1",
     "azure-identity>=1.25.1",
     "aioboto3>=15.5.0",
-    "sqlalchemy>=2.0.43",
+    "sqlalchemy[asyncio]>=2.0.43",
     "sqlmodel>=0.0.38",
     "asyncpg>=0.31.0",
     "aiosqlite>=0.22.1",

agentbyte-0.32.0/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.32.0"
+VERSION = __version__

{agentbyte-0.30.1 → agentbyte-0.32.0}/src/agentbyte/agents/agent.py

@@ -234,6 +234,7 @@ class Agent(BaseAgent):
                     tool_name=tool_call.tool_name,
                     success=streamed_result.success,
                     error=streamed_result.error,
+                    metadata=streamed_result.metadata,
                 )
                 working_context.add_message(tool_message)
                 yield tool_message
@@ -317,6 +318,7 @@ class Agent(BaseAgent):
                 tool_name=tool_call.tool_name,
                 success=result.success,
                 error=result.error,
+                metadata=result.metadata,
             )
         except Exception as exc:
             message = ToolMessage(
@@ -339,6 +341,102 @@ class Agent(BaseAgent):
 
         yield message
 
+    @staticmethod
+    def _unresolved_tail_calls(working_context: AgentContext) -> List[ToolCallRequest]:
+        """Calls of the newest tool-call batch that have no result yet, in order.
+
+        Only a batch followed exclusively by tool results counts; results are
+        matched to that batch occurrence, not to earlier reuses of a call ID.
+        """
+        resolved: set[str] = set()
+        for message in reversed(working_context.messages):
+            if isinstance(message, ToolMessage):
+                resolved.add(message.tool_call_id)
+                continue
+            if isinstance(message, AssistantMessage) and message.tool_calls:
+                return [c for c in message.tool_calls if c.call_id not in resolved]
+            return []
+        return []
+
+    def _awaits_approval(
+        self,
+        tool_call: ToolCallRequest,
+        working_context: AgentContext,
+        extra_tools: Optional[List[BaseTool]],
+    ) -> bool:
+        """Whether *tool_call* needs an approval decision that does not exist yet."""
+        tool = self._find_tool(tool_call.tool_name, extra_tools=extra_tools)
+        return (
+            tool is not None
+            and tool.approval_mode == ApprovalMode.ALWAYS
+            and working_context.get_approval_response(tool_call.call_id) is None
+        )
+
+    async def _resolve_tool_batch(
+        self,
+        working_context: AgentContext,
+        cancellation_token: Optional[CancellationToken],
+        verbose: bool,
+        extra_tools: Optional[List[BaseTool]],
+        outcome: dict[str, int | bool],
+    ) -> AsyncGenerator[Union[Message, AgentEvent], None]:
+        """Execute the newest batch's unresolved calls in their original order.
+
+        Execution stops before the first call still awaiting approval; approval
+        requests for every such call in the batch are registered together, so a
+        single decision round resolves the batch. Calls left unexecuted because
+        of cancellation receive an explicit failed result, keeping the batch
+        complete. ``outcome`` reports ``executed`` and ``paused``.
+        """
+        pending = self._unresolved_tail_calls(working_context)
+        awaiting = [
+            c for c in pending if self._awaits_approval(c, working_context, extra_tools)
+        ]
+        stop_at = awaiting[0].call_id if awaiting else None
+
+        for tool_call in pending:
+            if tool_call.call_id == stop_at:
+                break
+            outcome["executed"] = int(outcome["executed"]) + 1
+            try:
+                async for item in self._execute_tool_call(
+                    tool_call,
+                    working_context,
+                    cancellation_token,
+                    verbose,
+                    extra_tools=extra_tools,
+                ):
+                    yield item
+                    if isinstance(item, ToolApprovalEvent):
+                        outcome["paused"] = True
+                        return
+            except asyncio.CancelledError:
+                for skipped in self._unresolved_tail_calls(working_context):
+                    working_context.add_message(
+                        ToolMessage(
+                            content="Tool execution cancelled before it ran",
+                            source=self.name,
+                            tool_call_id=skipped.call_id,
+                            tool_name=skipped.tool_name,
+                            success=False,
+                            error="Cancelled",
+                        )
+                    )
+                raise
+
+        if not awaiting:
+            return
+
+        outcome["paused"] = True
+        for tool_call in awaiting:
+            if tool_call.call_id in working_context.pending_tool_calls:
+                continue  # already requested in an earlier run
+            request = working_context.add_approval_request(
+                tool_call=tool_call,
+                tool_name=tool_call.tool_name,
+            )
+            yield ToolApprovalEvent(source=self.name, approval_request=request)
+
     @trace_stream("agent")
     async def run_stream(
         self,
@@ -428,6 +526,11 @@ class Agent(BaseAgent):
 
         try:
             task_messages = self._convert_task_to_messages(task) if task else []
+            if task_messages and self._unresolved_tail_calls(working_context):
+                raise AgentExecutionError(
+                    "The conversation ends with unresolved tool calls; resolve pending "
+                    "approvals by resuming with task=None before sending a new task."
+                )
             for message in task_messages:
                 working_context.add_message(message)
 
@@ -453,32 +556,22 @@ class Agent(BaseAgent):
                 if cancellation_token and cancellation_token.is_cancelled():
                     raise asyncio.CancelledError()
 
-                approved_calls = working_context.get_approved_tool_calls()
-                rejected_calls = working_context.get_rejected_tool_calls()
-
-                for approved_call in approved_calls:
-                    tool_calls += 1
-                    async for item in self._execute_tool_call(
-                        approved_call,
+                # Resume: finish the newest tool-call batch (approved, denied and
+                # not-yet-run siblings, in order) before asking the model again.
+                if self._unresolved_tail_calls(working_context):
+                    outcome: dict[str, int | bool] = {"executed": 0, "paused": False}
+                    async for item in self._resolve_tool_batch(
                         working_context,
                         cancellation_token,
                         verbose,
-                        skip_approval_check=True,
-                        extra_tools=provider_tools,
+                        provider_tools,
+                        outcome,
                     ):
                         yield item
-
-                for rejected_call_id, rejected_call in rejected_calls:
-                    denial_message = ToolMessage(
-                        content="Tool execution denied: User declined approval",
-                        source=self.name,
-                        tool_call_id=rejected_call_id,
-                        tool_name=rejected_call.tool_name,
-                        success=False,
-                        error="Approval denied",
-                    )
-                    working_context.add_message(denial_message)
-                    yield denial_message
+                    tool_calls += int(outcome["executed"])
+                    if outcome["paused"]:
+                        finish_reason = "approval_needed"
+                        break
 
                 llm_messages = await self._prepare_llm_messages([], working_context, extra_instructions=extra_instructions)
                 if self.memory is not None:
@@ -560,11 +653,25 @@ class Agent(BaseAgent):
                     break
 
                 async def _execute_model_call(payload: dict[str, object]):
-                    payload_messages = payload.get("messages", llm_messages)
+                    # Send exactly the final middleware payload: falling back to
+                    # the agent's own values would bypass request validation
+                    # (e.g. compaction budgets) done on that payload.
+                    missing = [
+                        key
+                        for key in ("messages", "tools", "output_format")
+                        if key not in payload
+                    ]
+                    if missing:
+                        raise ValueError(
+                            f"model_call payload is missing {missing}; middleware "
+                            "must preserve payload keys (set a key to None to omit it)"
+                        )
+
+                    payload_messages = payload["messages"]
                     if not isinstance(payload_messages, list):
                         raise ValueError("model_call payload messages must be a list")
 
-                    payload_tools = payload.get("tools", tools)
+                    payload_tools = payload["tools"]
                     if payload_tools is not None and not isinstance(
                         payload_tools, list
                     ):
@@ -572,9 +679,7 @@ class Agent(BaseAgent):
                             "model_call payload tools must be a list or None"
                         )
 
-                    payload_output_format = payload.get(
-                        "output_format", self.output_format
-                    )
+                    payload_output_format = payload["output_format"]
                     if payload_output_format is not None and not isinstance(
                         payload_output_format, type
                     ):
@@ -667,27 +772,18 @@ class Agent(BaseAgent):
                         finish_reason = "max_iterations_finalized"
                     break
 
-                approval_pause = False
-                for tool_call in assistant_message.tool_calls:
-                    tool_calls += 1
-                    async for item in self._execute_tool_call(
-                        tool_call,
-                        working_context,
-                        cancellation_token,
-                        verbose,
-                        extra_tools=provider_tools,
-                    ):
-                        yield item
-
-                        if isinstance(item, ToolApprovalEvent):
-                            finish_reason = "approval_needed"
-                            approval_pause = True
-                            break
-
-                    if approval_pause:
-                        break
-
-                if approval_pause:
+                outcome = {"executed": 0, "paused": False}
+                async for item in self._resolve_tool_batch(
+                    working_context,
+                    cancellation_token,
+                    verbose,
+                    provider_tools,
+                    outcome,
+                ):
+                    yield item
+                tool_calls += int(outcome["executed"])
+                if outcome["paused"]:
+                    finish_reason = "approval_needed"
                     break
 
                 if not self.summarize_tool_result:

agentbyte-0.32.0/src/agentbyte/compaction/__init__.py

@@ -0,0 +1,41 @@
+"""Context compaction that keeps outbound conversations provider-valid.
+
+Strategies select whole message groups (a tool request and all its results are
+one group) so that a complete model-call request fits an input-token budget,
+or raise :class:`ContextBudgetExceeded` before any provider I/O.
+"""
+
+from agentbyte.compaction.counters import (
+    CharacterTokenCounter,
+    TiktokenCounter,
+    TokenCounter,
+)
+from agentbyte.compaction.errors import (
+    CompactionError,
+    ContextBudgetExceeded,
+    PendingToolExchangeError,
+    ToolExchangeError,
+)
+from agentbyte.compaction.grouping import MessageGroup, group_messages
+from agentbyte.compaction.strategies import (
+    CompactionResult,
+    CompactionStrategy,
+    HeadTailCompaction,
+    SlidingWindowCompaction,
+)
+
+__all__ = [
+    "CharacterTokenCounter",
+    "CompactionError",
+    "CompactionResult",
+    "CompactionStrategy",
+    "ContextBudgetExceeded",
+    "HeadTailCompaction",
+    "MessageGroup",
+    "PendingToolExchangeError",
+    "SlidingWindowCompaction",
+    "TiktokenCounter",
+    "TokenCounter",
+    "ToolExchangeError",
+    "group_messages",
+]