agentbyte 0.7.0__tar.gz → 0.8.0__tar.gz

{agentbyte-0.7.0 → agentbyte-0.8.0}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.8.0] - 2026-04-13
+
+### Added
+
+- Added SQL-backed usage logging middleware with a typed persistence contract plus SQLModel-backed storage for LLM usage records.
+- Added `examples/webui/in_memory.py` and `examples/webui/presets_webui.py` as concrete launchers for the packaged AgentByte WebUI.
+- Added plan-based orchestration to the preset-backed WebUI catalog so round-robin, AI-driven, and plan-based teams are all selectable from the same real-entities launcher.
+
+### Changed
+
+- Completed the `agentbyte.webui` session contract: WebUI sessions now support `user_id`, stricter session/entity binding, and injected durable session stores for persisted `AgentContext` reload across restarts.
+- Rebased and adapted the packaged WebUI frontend to AgentByte's backend contracts, including fixed session query handling, stable post-stream message refresh, richer workflow result rendering, cleaner orchestration event classification, and improved debug-panel payload inspection.
+- Extended agent and orchestrator WebUI usage surfaces to show both token counts and cost estimates when providers supply pricing data.
+- Removed the unused bundled examples-gallery flow and other stale picoagents-only frontend assumptions from the packaged WebUI.
+
+### Fixed
+
+- Fixed agent stream completion handling in the WebUI so final agent state events no longer fall through to `unknown`, immediate UI finalization works again, and post-stream session refresh reliably recalculates session totals.
+- Fixed round-robin and other orchestrator debug events so lifecycle payloads render as labeled orchestration events instead of opaque `unknown` entries.
+- Fixed workflow completion rendering so the WebUI shows terminal workflow outputs directly instead of dumping the raw completion envelope.
+
 ## [0.7.0] - 2026-04-09
 
 ### Added

{agentbyte-0.7.0 → agentbyte-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.7.0
+Version: 0.8.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
@@ -42,6 +42,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: sql
+Requires-Dist: aiosqlite>=0.22.1; extra == 'sql'
+Requires-Dist: asyncpg>=0.31.0; extra == 'sql'
+Requires-Dist: sqlmodel>=0.0.38; extra == 'sql'
 Provides-Extra: test
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
@@ -55,17 +59,26 @@ Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'webui'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.7.0/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.8.0/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.7.0**
+Current release: **0.8.0**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.8.0
+
+**WebUI maturity + preset expansion + SQL usage logging**
+
+- Completed the server-side WebUI session contract with user-scoped sessions, stricter `session_id` binding to `entity_id`, and injectable session stores for durable context reload.
+- Rebased and adopted the bundled WebUI frontend to AgentByte's backend contract, including fixed session lookup, post-stream session refresh, richer workflow result rendering, improved debug panel behavior, and visible usage cost for agent and orchestrator sessions.
+- Added real-entity WebUI launchers under `examples/webui/`, including preset-backed agents, workflows, and all three top-level orchestration patterns: round-robin, AI-driven, and plan-based.
+- Added SQL-backed usage logging middleware so provider usage records can be persisted through a typed backend contract instead of staying in-memory only.
+
 ## What's New in 0.7.0
 
 **MicroWebUI streaming polish + bundled SSE skill**

{agentbyte-0.7.0 → agentbyte-0.8.0}/README.md

@@ -1,15 +1,24 @@
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.7.0/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.8.0/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.7.0**
+Current release: **0.8.0**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.8.0
+
+**WebUI maturity + preset expansion + SQL usage logging**
+
+- Completed the server-side WebUI session contract with user-scoped sessions, stricter `session_id` binding to `entity_id`, and injectable session stores for durable context reload.
+- Rebased and adopted the bundled WebUI frontend to AgentByte's backend contract, including fixed session lookup, post-stream session refresh, richer workflow result rendering, improved debug panel behavior, and visible usage cost for agent and orchestrator sessions.
+- Added real-entity WebUI launchers under `examples/webui/`, including preset-backed agents, workflows, and all three top-level orchestration patterns: round-robin, AI-driven, and plan-based.
+- Added SQL-backed usage logging middleware so provider usage records can be persisted through a typed backend contract instead of staying in-memory only.
+
 ## What's New in 0.7.0
 
 **MicroWebUI streaming polish + bundled SSE skill**

{agentbyte-0.7.0 → agentbyte-0.8.0}/pyproject.toml

@@ -44,6 +44,11 @@ webui = [
     "fastapi>=0.135.2",
     "uvicorn[standard]>=0.44.0",
 ]
+sql = [
+    "sqlmodel>=0.0.38",
+    "asyncpg>=0.31.0",
+    "aiosqlite>=0.22.1",
+]
 viz = [
     "graphviz>=0.21",
 ]
@@ -120,6 +125,9 @@ test = [
     "pytest-asyncio>=1.3.0",
     "pytest-cov>=7.0.0",
     "ruff>=0.15.0",
+    "aiosqlite>=0.22.1",
+    "sqlmodel>=0.0.38",
+    "greenlet>=3.0.0",
 ]
 viz = [
     "graphviz>=0.21",

{agentbyte-0.7.0 → agentbyte-0.8.0}/src/agentbyte/__about__.py

@@ -1,2 +1,2 @@
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 VERSION = __version__

{agentbyte-0.7.0 → agentbyte-0.8.0}/src/agentbyte/agents/agent.py

@@ -5,6 +5,7 @@ Concrete Agent implementation with core execution loop.
 import asyncio
 import os
 import time
+import uuid
 import warnings
 from collections.abc import AsyncGenerator
 from typing import List, Optional, Union
@@ -74,6 +75,8 @@ class Agent(BaseAgent):
         cancellation_token: Optional[CancellationToken] = None,
     ) -> AgentResponse:
         working_context = context if context is not None else AgentContext()
+        if "run_id" not in working_context.metadata:
+            working_context.metadata["run_id"] = str(uuid.uuid4())
         if not task and working_context.is_empty:
             raise AgentConfigurationError(
                 "Either 'task' must be provided or 'context' must be non-empty."

agentbyte-0.8.0/src/agentbyte/middleware/sql_usage.py

@@ -0,0 +1,140 @@
+"""SQL backend for UsageLoggerMiddleware.
+
+Persists :class:`~agentbyte.middleware.usage_logger.UsageEvent` rows to any
+SQLAlchemy-supported database using SQLModel for table definitions and
+SQLAlchemy's async session for writes.
+
+Requires the ``sql`` optional extra::
+
+    uv sync --extra sql
+
+Supports both PostgreSQL (via asyncpg) and SQLite (via aiosqlite).
+
+Usage::
+
+    from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+    from sqlalchemy.orm import sessionmaker
+    from agentbyte.middleware.sql_usage import SqlUsageBackend, create_usage_tables
+
+    engine = create_async_engine("postgresql+asyncpg://user:pass@host/db")
+    AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+    async def get_session():
+        async with AsyncSessionLocal() as session:
+            yield session
+
+    await create_usage_tables(engine)
+    backend = SqlUsageBackend(session_factory=get_session)
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+from sqlmodel import Field, SQLModel
+
+from .usage_logger import UsageEvent, UsagePersistenceBackend
+
+
+class LlmUsageEvent(SQLModel, table=True):
+    """SQLModel table that stores one row per LLM call.
+
+    This class is internal to :class:`SqlUsageBackend`.  Callers who need
+    direct DB access can import it for read-only queries.
+    """
+
+    __tablename__ = "llm_usage_events"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    run_id: Optional[str] = Field(default=None, index=True)
+    session_id: Optional[str] = Field(default=None, index=True)
+    user_id: Optional[str] = Field(default=None)
+    identifier: Optional[str] = Field(default=None, index=True)
+    agent_name: str
+    model: str
+    duration_ms: int = Field(default=0)
+    llm_calls: int = Field(default=0)
+    tokens_input: int = Field(default=0)
+    tokens_output: int = Field(default=0)
+    tool_calls: int = Field(default=0)
+    memory_operations: int = Field(default=0)
+    cost_estimate: Optional[float] = Field(default=None)
+    recorded_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+
+async def create_usage_tables(engine: AsyncEngine) -> None:
+    """Create the ``llm_usage_events`` table if it does not exist.
+
+    Call this once at application startup before any agents run::
+
+        await create_usage_tables(engine)
+    """
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+
+class SqlUsageBackend(UsagePersistenceBackend):
+    """Persists :class:`~agentbyte.middleware.usage_logger.UsageEvent` rows
+    to a SQL database via an async SQLAlchemy session.
+
+    The caller is responsible for creating the engine and session factory.
+    This backend holds only a reference to the factory — it does not own the
+    connection pool.
+
+    Args:
+        session_factory: Zero-argument async generator factory that yields one
+            :class:`~sqlalchemy.ext.asyncio.AsyncSession` per call.  The
+            factory should handle its own cleanup (e.g. via ``async with``).
+
+    Example::
+
+        from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+        from sqlalchemy.orm import sessionmaker
+
+        engine = create_async_engine("postgresql+asyncpg://user:pass@host/db")
+        AsyncSessionLocal = sessionmaker(
+            engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+        async def get_session():
+            async with AsyncSessionLocal() as session:
+                yield session
+
+        backend = SqlUsageBackend(session_factory=get_session)
+    """
+
+    def __init__(
+        self,
+        session_factory: Callable[[], AsyncGenerator[AsyncSession, None]],
+    ) -> None:
+        self._session_factory = session_factory
+
+    async def write(self, event: UsageEvent) -> None:
+        gen = self._session_factory()
+        session: AsyncSession = await gen.__anext__()
+        try:
+            row = LlmUsageEvent(
+                run_id=event.run_id,
+                session_id=event.session_id,
+                user_id=event.user_id,
+                identifier=event.identifier,
+                agent_name=event.agent_name,
+                model=event.model,
+                duration_ms=event.duration_ms,
+                llm_calls=event.llm_calls,
+                tokens_input=event.tokens_input,
+                tokens_output=event.tokens_output,
+                tool_calls=event.tool_calls,
+                memory_operations=event.memory_operations,
+                cost_estimate=event.cost_estimate,
+                recorded_at=event.recorded_at,
+            )
+            session.add(row)
+            await session.commit()
+        finally:
+            await gen.aclose()

agentbyte-0.8.0/src/agentbyte/middleware/usage_logger.py

@@ -0,0 +1,177 @@
+"""Usage logging middleware with a pluggable persistence backend.
+
+Writes one :class:`UsageEvent` per LLM ``MODEL_CALL`` to whatever
+:class:`UsagePersistenceBackend` the caller supplies.  The first concrete
+backend is :class:`~agentbyte.middleware.sql_usage.SqlUsageBackend`; future
+backends (CosmosDB, DynamoDB, …) implement the same interface.
+
+Usage::
+
+    from agentbyte.middleware.usage_logger import UsageLoggerMiddleware
+    from agentbyte.middleware.sql_usage import SqlUsageBackend, create_usage_tables
+
+    backend = SqlUsageBackend(session_factory=get_session)
+    mw = UsageLoggerMiddleware(backend=backend, identifier="my-app")
+    agent = Agent(..., middlewares=[mw])
+"""
+
+from __future__ import annotations
+
+import asyncio
+import warnings
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from .base import BaseMiddleware, MiddlewareContext, OperationType
+
+
+class UsageEvent(BaseModel):
+    """Data contract passed to every :class:`UsagePersistenceBackend`.
+
+    All fields are derived from the :class:`~agentbyte.middleware.base.MiddlewareContext`
+    and the :class:`~agentbyte.llm.types.ChatCompletionResult` returned by a
+    ``MODEL_CALL`` operation.  Backends receive this object and persist it in
+    whatever form suits their storage technology.
+    """
+
+    run_id: Optional[str] = Field(
+        default=None,
+        description="Groups all LLM calls that belong to one agent.run() invocation",
+    )
+    session_id: Optional[str] = Field(
+        default=None,
+        description="Session identifier from AgentContext",
+    )
+    user_id: Optional[str] = Field(
+        default=None,
+        description="User identifier from AgentContext",
+    )
+    identifier: Optional[str] = Field(
+        default=None,
+        description="Application or service label set at middleware init",
+    )
+    agent_name: str = Field(description="Name of the agent that made the call")
+    model: str = Field(description="Model name used for the call")
+    # Full Usage fields
+    duration_ms: int = Field(default=0, description="Wall-clock time in milliseconds")
+    llm_calls: int = Field(default=0, description="LLM call count (typically 1 per event)")
+    tokens_input: int = Field(default=0, description="Prompt tokens consumed")
+    tokens_output: int = Field(default=0, description="Completion tokens generated")
+    tool_calls: int = Field(default=0, description="Tool invocations in Usage")
+    memory_operations: int = Field(default=0, description="Memory operations in Usage")
+    cost_estimate: Optional[float] = Field(
+        default=None,
+        description="Estimated USD cost (None when provider does not supply pricing)",
+    )
+    recorded_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp when the event was created",
+    )
+
+
+class UsagePersistenceBackend(ABC):
+    """Interface that all usage storage backends must satisfy.
+
+    Implement :meth:`write` to persist a :class:`UsageEvent`.  The optional
+    :meth:`setup` and :meth:`close` hooks let backends manage connection
+    lifecycle when the caller needs explicit control.
+
+    Example — minimal custom backend::
+
+        class PrintBackend(UsagePersistenceBackend):
+            async def write(self, event: UsageEvent) -> None:
+                print(event.model_dump_json())
+    """
+
+    @abstractmethod
+    async def write(self, event: UsageEvent) -> None:
+        """Persist one usage event.  Must not raise — errors should be handled internally."""
+
+    async def setup(self) -> None:
+        """Optional: initialise connections, create tables, etc."""
+
+    async def close(self) -> None:
+        """Optional: clean up connections and flush buffers."""
+
+
+class UsageLoggerMiddleware(BaseMiddleware):
+    """Middleware that writes one :class:`UsageEvent` per LLM call to a backend.
+
+    Writes are fire-and-forget (``asyncio.create_task``).  Backend failures are
+    swallowed as ``RuntimeWarning`` and never interrupt agent execution.
+
+    Args:
+        backend: Any :class:`UsagePersistenceBackend` implementation.
+        identifier: Optional application/service label stored on every event.
+    """
+
+    def __init__(
+        self,
+        backend: UsagePersistenceBackend,
+        identifier: Optional[str] = None,
+    ) -> None:
+        self._backend = backend
+        self._identifier = identifier
+
+    async def _write(self, event: UsageEvent) -> None:
+        try:
+            await self._backend.write(event)
+        except Exception as exc:
+            warnings.warn(
+                f"UsageLoggerMiddleware: backend write failed: {exc}",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+    async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+        return context
+
+    async def process_response(
+        self,
+        context: MiddlewareContext,
+        result: Any,
+    ) -> Any:
+        if context.operation != OperationType.MODEL_CALL:
+            return result
+
+        usage = getattr(result, "usage", None)
+        if usage is None:
+            return result
+
+        agent_ctx = context.agent_context
+        run_id: Optional[str] = None
+        if agent_ctx is not None:
+            raw = agent_ctx.metadata.get("run_id")
+            if raw is not None:
+                run_id = str(raw)
+
+        model: str = context.metadata.get("model") or getattr(result, "model", "unknown")
+
+        event = UsageEvent(
+            run_id=run_id,
+            session_id=agent_ctx.session_id if agent_ctx is not None else None,
+            user_id=agent_ctx.user_id if agent_ctx is not None else None,
+            identifier=self._identifier,
+            agent_name=context.agent_name,
+            model=model,
+            duration_ms=usage.duration_ms,
+            llm_calls=usage.llm_calls,
+            tokens_input=usage.tokens_input,
+            tokens_output=usage.tokens_output,
+            tool_calls=usage.tool_calls,
+            memory_operations=usage.memory_operations,
+            cost_estimate=usage.cost_estimate,
+        )
+
+        asyncio.create_task(self._write(event))
+        return result
+
+    async def process_error(
+        self,
+        context: MiddlewareContext,
+        error: Exception,
+    ) -> Optional[Any]:
+        return None

{agentbyte-0.7.0 → agentbyte-0.8.0}/src/agentbyte/presets/workflow.py

@@ -6,7 +6,7 @@ from typing import Any
 
 from agentbyte.llm import BaseChatCompletionClient
 from agentbyte.workflow import Workflow, WorkflowConfig
-from agentbyte.workflow.core.models import StepMetadata
+from agentbyte.workflow.core.models import StepMetadata, WorkflowContext
 from agentbyte.workflow.steps import AgentStep, FunctionStep
 from agentbyte.workflow.steps.agentbyte_agent import (
     AgentbyteAgentInput,
@@ -17,6 +17,42 @@ from .agents import get_researcher, get_reviewer, get_writer
 from .clients import build_chat_client
 
 
+def _writer_to_reviewer_fn(
+    output: AgentbyteAgentOutput, context: WorkflowContext
+) -> dict:
+    """Transform writer output into reviewer input; store draft for later retrieval."""
+    context.set("writer_draft", output.response or "")
+    return {
+        "task": output.response or "",
+        "additional_context": {"messages": output.messages, "usage": output.usage},
+    }
+
+
+def _reviewer_to_writer_fn(
+    output: AgentbyteAgentOutput, context: WorkflowContext
+) -> dict:
+    """Transform reviewer output into writer_final input.
+
+    Passes the original draft plus reviewer feedback so the writer can
+    produce an improved final version. If the reviewer approved, the writer
+    is asked to confirm and present the polished version.
+    """
+    draft = context.get("writer_draft") or ""
+    feedback = (output.response or "").strip()
+    approved = feedback.upper() == "APPROVED"
+    if approved:
+        task = f"Your draft was approved by the reviewer. Output the final polished version:\n\n{draft}"
+    else:
+        task = (
+            f"Revise your draft based on the reviewer's feedback.\n\n"
+            f"Your draft:\n{draft}\n\nReviewer feedback:\n{feedback}"
+        )
+    return {
+        "task": task,
+        "additional_context": {"messages": output.messages, "usage": output.usage},
+    }
+
+
 def _create_linear_research_writer_reviewer_workflow(
     *,
     name: str,
@@ -25,7 +61,7 @@ def _create_linear_research_writer_reviewer_workflow(
     writer,
     reviewer,
 ) -> Workflow:
-    """Create the default researcher -> writer -> reviewer workflow."""
+    """Create the default researcher -> writer -> reviewer -> writer_final workflow."""
     workflow = Workflow(WorkflowConfig(name=name, description=description))
     researcher_step = AgentStep(
         step_id="researcher",
@@ -57,10 +93,19 @@ def _create_linear_research_writer_reviewer_workflow(
         metadata=StepMetadata(name="writer_to_reviewer"),
         input_type=AgentbyteAgentOutput,
         output_type=AgentbyteAgentInput,
-        func=lambda output, _context: {
-            "task": output.response or "",
-            "additional_context": {"messages": output.messages, "usage": output.usage},
-        },
+        func=_writer_to_reviewer_fn,
+    )
+    reviewer_to_writer = FunctionStep(
+        step_id="reviewer_to_writer",
+        metadata=StepMetadata(name="reviewer_to_writer"),
+        input_type=AgentbyteAgentOutput,
+        output_type=AgentbyteAgentInput,
+        func=_reviewer_to_writer_fn,
+    )
+    writer_final_step = AgentStep(
+        step_id="writer_final",
+        metadata=StepMetadata(name="writer_final"),
+        agent=writer,
     )
     workflow.chain(
         researcher_step,
@@ -68,6 +113,8 @@ def _create_linear_research_writer_reviewer_workflow(
         writer_step,
         writer_to_reviewer,
         reviewer_step,
+        reviewer_to_writer,
+        writer_final_step,
     )
     return workflow
 

{agentbyte-0.7.0 → agentbyte-0.8.0}/src/agentbyte/webui/__init__.py

@@ -4,6 +4,7 @@ from agentbyte.webui.discovery import AgentbyteScanner
 from agentbyte.webui.execution import ExecutionEngine
 from agentbyte.webui.models import (
     AgentInfo,
+    CreateSessionRequest,
     Entity,
     EntityInfo,
     HealthResponse,
@@ -29,12 +30,13 @@ from agentbyte.webui.session_store import (
     InMemorySessionStore,
     SessionStore,
 )
-from agentbyte.webui.sessions import SessionManager
+from agentbyte.webui.sessions import SessionBindingError, SessionManager
 
 __all__ = [
     "AgentInfo",
     "AgentbyteScanner",
     "AgentbyteWebUIServer",
+    "CreateSessionRequest",
     "Entity",
     "EntityInfo",
     "EntityRegistry",
@@ -46,6 +48,7 @@ __all__ = [
     "OrchestratorInfo",
     "RunEntityRequest",
     "SessionInfo",
+    "SessionBindingError",
     "SessionManager",
     "SessionStore",
     "StatsResponse",