agentabi 0.2.0__tar.gz → 0.2.2__tar.gz

{agentabi-0.2.0/src/agentabi.egg-info → agentabi-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentabi
-Version: 0.2.0
+Version: 0.2.2
 Summary: Unified async Python API for driving coding agent CLIs — Claude Code, Codex, Gemini CLI, and more
 Author-email: Peng Ding <pding.dp@foxmail.com>
 License-Expression: MIT
@@ -38,14 +38,19 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: ruff>=0.15.0; extra == "dev"
-Requires-Dist: ty>=0.0.31; extra == "dev"
+Requires-Dist: ruff==0.15.20; extra == "dev"
+Requires-Dist: ty==0.0.54; extra == "dev"
 Requires-Dist: build>=1.2.2.post1; extra == "dev"
 Requires-Dist: twine>=6.1.0; extra == "dev"
 Dynamic: license-file
 
 # agentabi
 
+[![PyPI version](https://img.shields.io/pypi/v/agentabi?color=green)](https://pypi.org/project/agentabi/)
+[![GitHub release](https://img.shields.io/github/v/release/Oaklight/agentabi?color=green)](https://github.com/Oaklight/agentabi/releases/latest)
+[![CI](https://github.com/Oaklight/agentabi/actions/workflows/ci.yml/badge.svg)](https://github.com/Oaklight/agentabi/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
 Unified interface layer for agentic coding CLIs.
 
 One interface. Any coding agent.
@@ -138,10 +143,10 @@ print(caps["supports_streaming"]) # True
 
 ```
 agentabi  →  Agent CLI unified interface  →  like an OS ABI
-llmir     →  LLM API format conversion    →  like a compiler IR
+llm-rosetta  →  LLM API format conversion    →  like a compiler IR
 ```
 
-- [llmir](https://github.com/Oaklight/llmir) — LLM Intermediate Representation for converting between LLM provider API formats (OpenAI, Anthropic, Google)
+- [llm-rosetta](https://github.com/Oaklight/llm-rosetta) — LLM API format conversion layer for translating between LLM provider API formats (OpenAI, Anthropic, Google)
 
 ## License
 

{agentabi-0.2.0 → agentabi-0.2.2}/README.md

@@ -1,5 +1,10 @@
 # agentabi
 
+[![PyPI version](https://img.shields.io/pypi/v/agentabi?color=green)](https://pypi.org/project/agentabi/)
+[![GitHub release](https://img.shields.io/github/v/release/Oaklight/agentabi?color=green)](https://github.com/Oaklight/agentabi/releases/latest)
+[![CI](https://github.com/Oaklight/agentabi/actions/workflows/ci.yml/badge.svg)](https://github.com/Oaklight/agentabi/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
 Unified interface layer for agentic coding CLIs.
 
 One interface. Any coding agent.
@@ -92,10 +97,10 @@ print(caps["supports_streaming"]) # True
 
 ```
 agentabi  →  Agent CLI unified interface  →  like an OS ABI
-llmir     →  LLM API format conversion    →  like a compiler IR
+llm-rosetta  →  LLM API format conversion    →  like a compiler IR
 ```
 
-- [llmir](https://github.com/Oaklight/llmir) — LLM Intermediate Representation for converting between LLM provider API formats (OpenAI, Anthropic, Google)
+- [llm-rosetta](https://github.com/Oaklight/llm-rosetta) — LLM API format conversion layer for translating between LLM provider API formats (OpenAI, Anthropic, Google)
 
 ## License
 

{agentabi-0.2.0 → agentabi-0.2.2}/pyproject.toml

@@ -58,8 +58,8 @@ dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "pytest-cov",
-    "ruff>=0.15.0",
-    "ty>=0.0.31",
+    "ruff==0.15.20",
+    "ty==0.0.54",
     "build>=1.2.2.post1",
     "twine>=6.1.0",
 ]

{agentabi-0.2.0 → agentabi-0.2.2}/src/agentabi/__init__.py

@@ -19,6 +19,14 @@ Sync convenience:
     from agentabi import run_sync
     result = run_sync(prompt="List Python files", agent="claude_code")
 
+Middleware:
+    from agentabi.middleware import LoggingMiddleware, TimeoutMiddleware
+
+    session = Session(
+        agent="claude_code",
+        middleware=[LoggingMiddleware(), TimeoutMiddleware(120)],
+    )
+
 Discovery:
     from agentabi import detect_agents, get_agent_capabilities
     agents = detect_agents()
@@ -26,6 +34,14 @@ Discovery:
 """
 
 from .auto_detect import detect_agents, get_agent_capabilities, get_default_agent
+from .middleware import (
+    LoggingMiddleware,
+    Middleware,
+    StreamHandler,
+    TimeoutMiddleware,
+    UsageMeterMiddleware,
+    chain_middleware,
+)
 from .providers.base import Provider
 from .providers.registry import AgentNotAvailable, get_provider
 from .session import Session, run_sync
@@ -53,7 +69,7 @@ from .types.ir import (
     UsageEvent,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 __all__ = [
     # Consumer API
@@ -92,4 +108,11 @@ __all__ = [
     "PermissionConfig",
     "PermissionLevel",
     "PermissionRequest",
+    # Middleware
+    "Middleware",
+    "StreamHandler",
+    "chain_middleware",
+    "LoggingMiddleware",
+    "TimeoutMiddleware",
+    "UsageMeterMiddleware",
 ]

agentabi-0.2.2/src/agentabi/middleware/__init__.py

@@ -0,0 +1,119 @@
+"""
+agentabi - Middleware Pipeline
+
+Composable middleware for intercepting Session.stream() calls.
+Middleware can inspect/modify TaskConfig, filter/transform IREvents,
+and run side effects (logging, metering, timeouts).
+
+Architecture:
+    Middleware follows the onion model (like ASGI). Each middleware
+    wraps a ``StreamHandler`` and returns a new ``StreamHandler``.
+    The first middleware in the list is the outermost wrapper.
+
+Quick start::
+
+    from agentabi.middleware import LoggingMiddleware, TimeoutMiddleware
+
+    session = Session(
+        agent="claude_code",
+        middleware=[LoggingMiddleware(), TimeoutMiddleware(120)],
+    )
+
+Custom middleware::
+
+    from agentabi.middleware import Middleware, StreamHandler
+
+    class MyMiddleware:
+        def __call__(self, handler: StreamHandler) -> StreamHandler:
+            async def wrapper(task):
+                task = {**task, "prompt": task["prompt"].strip()}
+                async for event in handler(task):
+                    yield event
+            return wrapper
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from typing import Callable
+
+from ..types.ir.events import IREvent
+from ..types.ir.task import TaskConfig
+from .logging import LoggingMiddleware
+from .timeout import TimeoutMiddleware
+from .usage import UsageMeterMiddleware
+
+# ============================================================================
+# Core type aliases
+# ============================================================================
+
+StreamHandler = Callable[[TaskConfig], AsyncIterator[IREvent]]
+"""A callable that takes a TaskConfig and returns an async iterator of IREvents.
+
+This is the fundamental unit of the middleware pipeline. The provider's
+``stream()`` method is the innermost StreamHandler; each middleware wraps
+it with additional behavior.
+"""
+
+Middleware = Callable[[StreamHandler], StreamHandler]
+"""A callable that wraps a StreamHandler with additional behavior.
+
+Middleware receives the next handler in the chain and returns a new
+handler. The wrapper can:
+
+- Modify TaskConfig before passing to the next handler (copy-on-mutate
+  recommended: ``task = {**task, "key": new_value}``)
+- Filter or transform yielded IREvents
+- Run side effects (logging, timing, metering)
+- Short-circuit the pipeline (e.g., timeout)
+"""
+
+
+# ============================================================================
+# Pipeline chaining
+# ============================================================================
+
+
+def chain_middleware(
+    handler: StreamHandler,
+    middleware: Sequence[Middleware],
+) -> StreamHandler:
+    """Chain middleware around a base handler using the onion model.
+
+    The first middleware in the sequence becomes the outermost wrapper.
+    When the pipeline executes, control flows inward through each
+    middleware, reaches the base handler, then flows back outward.
+
+    Args:
+        handler: The base StreamHandler (typically provider.stream).
+        middleware: Sequence of middleware to apply. Empty sequence
+            returns the handler unchanged.
+
+    Returns:
+        A new StreamHandler with all middleware applied.
+
+    Example::
+
+        pipeline = chain_middleware(
+            provider.stream,
+            [LoggingMiddleware(), TimeoutMiddleware(30)],
+        )
+        async for event in pipeline(task):
+            ...
+    """
+    for mw in reversed(middleware):
+        handler = mw(handler)
+    return handler
+
+
+__all__ = [
+    # Core types
+    "StreamHandler",
+    "Middleware",
+    # Pipeline
+    "chain_middleware",
+    # Built-in middleware
+    "LoggingMiddleware",
+    "TimeoutMiddleware",
+    "UsageMeterMiddleware",
+]

agentabi-0.2.2/src/agentabi/middleware/logging.py

@@ -0,0 +1,112 @@
+"""
+agentabi - Logging Middleware
+
+Logs task execution and IR events at configurable levels.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import AsyncIterator
+from typing import Callable
+
+from ..types.ir.events import IREvent
+from ..types.ir.task import TaskConfig
+
+StreamHandler = Callable[[TaskConfig], AsyncIterator[IREvent]]
+
+_DEFAULT_LOGGER = logging.getLogger("agentabi.middleware")
+
+
+class LoggingMiddleware:
+    """Middleware that logs task execution and IR events.
+
+    Logs task start/end at INFO level and individual events at DEBUG
+    level. Uses the ``agentabi.middleware`` logger by default.
+
+    Args:
+        logger: Logger instance to use. Defaults to ``agentabi.middleware``.
+        level: Log level for event-level messages. Defaults to DEBUG.
+        log_events: Whether to log individual IR events. Defaults to True.
+        log_event_types: If set, only log events whose ``type`` is in
+            this set. Defaults to None (log all events).
+
+    Example::
+
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+
+        session = Session(
+            agent="claude_code",
+            middleware=[LoggingMiddleware()],
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        logger: logging.Logger | None = None,
+        level: int = logging.DEBUG,
+        log_events: bool = True,
+        log_event_types: set[str] | None = None,
+    ) -> None:
+        self._logger = logger or _DEFAULT_LOGGER
+        self._level = level
+        self._log_events = log_events
+        self._log_event_types = log_event_types
+
+    def __call__(self, handler: StreamHandler) -> StreamHandler:
+        """Wrap a StreamHandler with logging."""
+        logger = self._logger
+        level = self._level
+        log_events = self._log_events
+        log_event_types = self._log_event_types
+
+        async def wrapper(task: TaskConfig) -> AsyncIterator[IREvent]:
+            prompt_preview = task["prompt"][:80]
+            agent = task.get("agent", "unknown")
+            logger.info("Task started: agent=%s prompt=%r", agent, prompt_preview)
+
+            start = time.monotonic()
+            event_count = 0
+            failed = False
+
+            try:
+                async for event in handler(task):
+                    event_count += 1
+                    if log_events:
+                        etype = event.get("type", "unknown")
+                        if log_event_types is None or etype in log_event_types:
+                            logger.log(level, "Event #%d: type=%s", event_count, etype)
+                    yield event
+            except Exception:
+                failed = True
+                raise
+            finally:
+                elapsed = time.monotonic() - start
+                if failed:
+                    logger.error(
+                        "Task failed: agent=%s elapsed=%.2fs events=%d",
+                        agent,
+                        elapsed,
+                        event_count,
+                    )
+                else:
+                    logger.info(
+                        "Task completed: agent=%s elapsed=%.2fs events=%d",
+                        agent,
+                        elapsed,
+                        event_count,
+                    )
+
+        return wrapper
+
+    def __repr__(self) -> str:
+        return (
+            f"LoggingMiddleware(logger={self._logger.name!r}, "
+            f"level={self._level}, log_events={self._log_events})"
+        )
+
+
+__all__ = ["LoggingMiddleware"]

agentabi-0.2.2/src/agentabi/middleware/timeout.py

@@ -0,0 +1,84 @@
+"""
+agentabi - Timeout Middleware
+
+Enforces a wall-clock timeout on streaming task execution.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator
+from typing import Callable
+
+from ..types.ir.events import IREvent
+from ..types.ir.task import TaskConfig
+
+StreamHandler = Callable[[TaskConfig], AsyncIterator[IREvent]]
+
+
+class TimeoutMiddleware:
+    """Middleware that enforces a wall-clock timeout on task execution.
+
+    Wraps each ``__anext__`` call on the event stream with
+    ``asyncio.wait_for``, so the timeout fires even if the stream
+    stalls mid-iteration (not just between events).
+
+    Raises ``asyncio.TimeoutError`` if the total elapsed time exceeds
+    the configured timeout.
+
+    Args:
+        timeout: Maximum wall-clock seconds for the entire stream.
+            Must be positive.
+
+    Example::
+
+        session = Session(
+            agent="claude_code",
+            middleware=[TimeoutMiddleware(120)],
+        )
+
+        try:
+            result = await session.run(prompt="Long task")
+        except asyncio.TimeoutError:
+            print("Task timed out after 120s")
+
+    Note:
+        The timeout is per-stream invocation, not cumulative across
+        multiple calls. Each ``stream()`` or ``run()`` gets a fresh
+        timeout budget.
+    """
+
+    def __init__(self, timeout: float) -> None:
+        if timeout <= 0:
+            raise ValueError(f"timeout must be positive, got {timeout}")
+        self._timeout = timeout
+
+    def __call__(self, handler: StreamHandler) -> StreamHandler:
+        """Wrap a StreamHandler with timeout enforcement."""
+        timeout = self._timeout
+
+        async def wrapper(task: TaskConfig) -> AsyncIterator[IREvent]:
+            start = time.monotonic()
+            aiter = handler(task).__aiter__()
+
+            while True:
+                elapsed = time.monotonic() - start
+                remaining = timeout - elapsed
+                if remaining <= 0:
+                    raise asyncio.TimeoutError(
+                        f"Task exceeded timeout of {timeout}s (elapsed: {elapsed:.1f}s)"
+                    )
+                try:
+                    event = await asyncio.wait_for(aiter.__anext__(), timeout=remaining)
+                except StopAsyncIteration:
+                    break
+                yield event
+
+        return wrapper
+
+    def __repr__(self) -> str:
+        return f"TimeoutMiddleware(timeout={self._timeout})"
+
+
+__all__ = ["TimeoutMiddleware"]

agentabi-0.2.2/src/agentabi/middleware/usage.py

@@ -0,0 +1,134 @@
+"""
+agentabi - Usage Meter Middleware
+
+Tracks cumulative token usage and cost across multiple task executions.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import AsyncIterator
+from typing import Callable
+
+from typing_extensions import TypedDict
+
+from ..types.ir.events import IREvent
+from ..types.ir.task import TaskConfig
+
+StreamHandler = Callable[[TaskConfig], AsyncIterator[IREvent]]
+
+
+class UsageSummary(TypedDict, total=False):
+    """Cumulative usage statistics across multiple task executions."""
+
+    call_count: int
+    total_input_tokens: int
+    total_output_tokens: int
+    total_cache_read_tokens: int
+    total_cache_creation_tokens: int
+    total_tokens: int
+    total_cost_usd: float
+
+
+class UsageMeterMiddleware:
+    """Middleware that accumulates token usage and cost across calls.
+
+    Watches for ``usage`` events in the stream and accumulates token
+    counts and cost. The accumulated totals are available via the
+    ``summary`` property at any time.
+
+    Thread-safe: uses a lock for counter updates so the summary can
+    be read from any thread.
+
+    Example::
+
+        meter = UsageMeterMiddleware()
+        session = Session(agent="claude_code", middleware=[meter])
+
+        await session.run(prompt="Task 1")
+        await session.run(prompt="Task 2")
+
+        print(meter.summary)
+        # {'call_count': 2, 'total_input_tokens': 1500, ...}
+
+        meter.reset()
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._call_count = 0
+        self._input_tokens = 0
+        self._output_tokens = 0
+        self._cache_read_tokens = 0
+        self._cache_creation_tokens = 0
+        self._total_tokens = 0
+        self._cost_usd = 0.0
+
+    @property
+    def summary(self) -> UsageSummary:
+        """Return cumulative usage statistics.
+
+        Returns:
+            A UsageSummary dict with all accumulated counters.
+        """
+        with self._lock:
+            result: UsageSummary = {
+                "call_count": self._call_count,
+                "total_input_tokens": self._input_tokens,
+                "total_output_tokens": self._output_tokens,
+                "total_tokens": self._total_tokens,
+                "total_cost_usd": self._cost_usd,
+            }
+            if self._cache_read_tokens:
+                result["total_cache_read_tokens"] = self._cache_read_tokens
+            if self._cache_creation_tokens:
+                result["total_cache_creation_tokens"] = self._cache_creation_tokens
+            return result
+
+    def reset(self) -> None:
+        """Reset all accumulated counters to zero."""
+        with self._lock:
+            self._call_count = 0
+            self._input_tokens = 0
+            self._output_tokens = 0
+            self._cache_read_tokens = 0
+            self._cache_creation_tokens = 0
+            self._total_tokens = 0
+            self._cost_usd = 0.0
+
+    def __call__(self, handler: StreamHandler) -> StreamHandler:
+        """Wrap a StreamHandler with usage metering."""
+
+        async def wrapper(task: TaskConfig) -> AsyncIterator[IREvent]:
+            with self._lock:
+                self._call_count += 1
+
+            async for event in handler(task):
+                if event.get("type") == "usage":
+                    usage = event.get("usage", {})
+                    cost = event.get("cost_usd")
+                    with self._lock:
+                        self._input_tokens += usage.get("input_tokens", 0)
+                        self._output_tokens += usage.get("output_tokens", 0)
+                        self._cache_read_tokens += usage.get("cache_read_tokens", 0)
+                        self._cache_creation_tokens += usage.get(
+                            "cache_creation_tokens", 0
+                        )
+                        self._total_tokens += usage.get("total_tokens", 0)
+                        if cost is not None:
+                            self._cost_usd += cost
+                yield event
+
+        return wrapper
+
+    def __repr__(self) -> str:
+        return (
+            f"UsageMeterMiddleware(calls={self._call_count}, "
+            f"tokens={self._total_tokens}, cost=${self._cost_usd:.4f})"
+        )
+
+
+__all__ = [
+    "UsageMeterMiddleware",
+    "UsageSummary",
+]

{agentabi-0.2.0 → agentabi-0.2.2}/src/agentabi/providers/base.py

@@ -7,13 +7,14 @@ abstraction layer between Session and agent CLIs/SDKs.
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import AsyncIterator
 from typing import Any
 
 from typing_extensions import Protocol, runtime_checkable
 
 from ..types.ir.capabilities import AgentCapabilities
-from ..types.ir.events import IREvent, UsageInfo
+from ..types.ir.events import ErrorEvent, IREvent, UsageInfo
 from ..types.ir.session import SessionResult, SessionStatus
 from ..types.ir.task import TaskConfig
 
@@ -71,6 +72,54 @@ class Provider(Protocol):
         ...
 
 
+async def collect_subprocess_errors(
+    proc: asyncio.subprocess.Process,
+    *,
+    timed_out: bool = False,
+    timeout_seconds: float | None = None,
+) -> list[ErrorEvent]:
+    """Collect stderr and exit-code errors after a subprocess finishes.
+
+    Call after the stdout reading loop ends and ``await proc.wait()``
+    has been called so that ``proc.returncode`` is set.
+
+    Args:
+        proc: The completed subprocess.
+        timed_out: Whether the process was killed due to timeout.
+        timeout_seconds: The configured timeout value (for the error message).
+
+    Returns:
+        A (possibly empty) list of ErrorEvents to yield.
+    """
+    events: list[ErrorEvent] = []
+    stderr_text = ""
+
+    if proc.stderr:
+        stderr_data = await proc.stderr.read()
+        if stderr_data:
+            stderr_text = stderr_data.decode().strip()
+            if stderr_text:
+                events.append(ErrorEvent(type="error", error=stderr_text))
+
+    if timed_out:
+        events.append(
+            ErrorEvent(
+                type="error",
+                error=f"Process timed out after {timeout_seconds}s",
+                is_fatal=True,
+            )
+        )
+    elif proc.returncode:
+        events.append(
+            ErrorEvent(
+                type="error",
+                error=f"Process exited with code {proc.returncode}",
+            )
+        )
+
+    return events
+
+
 class _RunState:
     """Mutable accumulator for default_run event aggregation."""
 
@@ -163,5 +212,6 @@ async def default_run(provider: Any, task: TaskConfig) -> SessionResult:
 
 __all__ = [
     "Provider",
+    "collect_subprocess_errors",
     "default_run",
 ]