axio 0.4.1__tar.gz → 0.5.1__tar.gz

{axio-0.4.1 → axio-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axio
-Version: 0.4.1
+Version: 0.5.1
 Summary: Minimal, streaming-first, protocol-driven foundation for LLM-powered agents
 Project-URL: Homepage, https://github.com/axio-agent/axio
 Project-URL: Repository, https://github.com/axio-agent/axio
@@ -38,9 +38,24 @@ pip install axio
 
 ## Quick start
 
+<!--
+name: test_readme_quick_start
+```python
+import sys, types
+from axio.testing import StubTransport, make_text_response
+
+_m = types.ModuleType("axio_transport_openai")
+class OpenAITransport(StubTransport):
+    def __init__(self, api_key: str = "", model: str = "") -> None:
+        super().__init__([make_text_response("Hello, Alice!")])
+_m.OpenAITransport = OpenAITransport  # type: ignore[attr-defined]
+sys.modules["axio_transport_openai"] = _m
+```
+-->
+<!-- name: test_readme_quick_start -->
 ```python
 import asyncio
-from axio import Agent
+from axio.agent import Agent
 from axio.context import MemoryContextStore
 from axio.tool import Tool, ToolHandler
 
@@ -97,6 +112,7 @@ asyncio.run(main())
 
 ### CompletionTransport
 
+<!-- name: test_readme_completion_transport -->
 ```python
 from typing import Protocol, runtime_checkable
 from collections.abc import AsyncIterator
@@ -113,18 +129,30 @@ class CompletionTransport(Protocol):
 
 ### ContextStore
 
+<!-- name: test_readme_context_store -->
 ```python
-class ContextStore(ABC):
+from abc import ABC, abstractmethod
+from axio.context import ContextStore
+from axio.messages import Message
+
+class MyContextStore(ContextStore, ABC):
+    @abstractmethod
     async def append(self, message: Message) -> None: ...
+
+    @abstractmethod
     async def get_history(self) -> list[Message]: ...
-    async def fork(self) -> ContextStore: ...   # branch conversation
-    async def clear(self) -> None: ...
-    async def close(self) -> None: ...
+
+    # Everything else — session_id, close(), fork(), clear(),
+    # get/set_context_tokens() — has a default implementation.
 ```
 
 ### PermissionGuard
 
+<!-- name: test_readme_permission_guard -->
 ```python
+from typing import Protocol, runtime_checkable
+from axio.tool import ToolHandler
+
 @runtime_checkable
 class PermissionGuard(Protocol):
     async def check(self, handler: ToolHandler) -> ToolHandler: ...
@@ -144,6 +172,7 @@ class PermissionGuard(Protocol):
 
 ## Tools
 
+<!-- name: test_readme_tools -->
 ```python
 from axio.tool import Tool, ToolHandler
 
@@ -166,7 +195,9 @@ tool = Tool(
 
 ## Testing
 
+<!-- name: test_readme_testing -->
 ```python
+from axio.agent import Agent
 from axio.testing import (
     StubTransport,
     make_tool_use_response,

{axio-0.4.1 → axio-0.5.1}/README.md

@@ -25,9 +25,24 @@ pip install axio
 
 ## Quick start
 
+<!--
+name: test_readme_quick_start
+```python
+import sys, types
+from axio.testing import StubTransport, make_text_response
+
+_m = types.ModuleType("axio_transport_openai")
+class OpenAITransport(StubTransport):
+    def __init__(self, api_key: str = "", model: str = "") -> None:
+        super().__init__([make_text_response("Hello, Alice!")])
+_m.OpenAITransport = OpenAITransport  # type: ignore[attr-defined]
+sys.modules["axio_transport_openai"] = _m
+```
+-->
+<!-- name: test_readme_quick_start -->
 ```python
 import asyncio
-from axio import Agent
+from axio.agent import Agent
 from axio.context import MemoryContextStore
 from axio.tool import Tool, ToolHandler
 
@@ -84,6 +99,7 @@ asyncio.run(main())
 
 ### CompletionTransport
 
+<!-- name: test_readme_completion_transport -->
 ```python
 from typing import Protocol, runtime_checkable
 from collections.abc import AsyncIterator
@@ -100,18 +116,30 @@ class CompletionTransport(Protocol):
 
 ### ContextStore
 
+<!-- name: test_readme_context_store -->
 ```python
-class ContextStore(ABC):
+from abc import ABC, abstractmethod
+from axio.context import ContextStore
+from axio.messages import Message
+
+class MyContextStore(ContextStore, ABC):
+    @abstractmethod
     async def append(self, message: Message) -> None: ...
+
+    @abstractmethod
     async def get_history(self) -> list[Message]: ...
-    async def fork(self) -> ContextStore: ...   # branch conversation
-    async def clear(self) -> None: ...
-    async def close(self) -> None: ...
+
+    # Everything else — session_id, close(), fork(), clear(),
+    # get/set_context_tokens() — has a default implementation.
 ```
 
 ### PermissionGuard
 
+<!-- name: test_readme_permission_guard -->
 ```python
+from typing import Protocol, runtime_checkable
+from axio.tool import ToolHandler
+
 @runtime_checkable
 class PermissionGuard(Protocol):
     async def check(self, handler: ToolHandler) -> ToolHandler: ...
@@ -131,6 +159,7 @@ class PermissionGuard(Protocol):
 
 ## Tools
 
+<!-- name: test_readme_tools -->
 ```python
 from axio.tool import Tool, ToolHandler
 
@@ -153,7 +182,9 @@ tool = Tool(
 
 ## Testing
 
+<!-- name: test_readme_testing -->
 ```python
+from axio.agent import Agent
 from axio.testing import (
     StubTransport,
     make_tool_use_response,

{axio-0.4.1 → axio-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axio"
-version = "0.4.1"
+version = "0.5.1"
 description = "Minimal, streaming-first, protocol-driven foundation for LLM-powered agents"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -21,6 +21,7 @@ packages = ["src/axio"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+testpaths = ["tests", "README.md"]
 
 [tool.ruff]
 line-length = 119
@@ -40,4 +41,5 @@ dev = [
     "mypy>=1.14",
     "ruff>=0.9",
     "pytest-cov>=7.1.0",
+    "markdown-pytest>=0.6.0",
 ]

{axio-0.4.1 → axio-0.5.1}/src/axio/agent.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import json
 import logging
 from collections.abc import AsyncGenerator, Iterable
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Self
 
 from axio.blocks import TextBlock, ToolResultBlock, ToolUseBlock
 from axio.context import ContextStore
@@ -34,11 +35,15 @@ logger = logging.getLogger(__name__)
 @dataclass(slots=True)
 class Agent:
     system: str
-    tools: list[Tool]
     transport: CompletionTransport
+    tools: list[Tool] = field(default_factory=list)
     selector: ToolSelector | None = field(default=None)
     max_iterations: int = field(default=50)
 
+    def copy(self, **overrides: Any) -> Self:
+        """Return a new Agent with *overrides* applied."""
+        return dataclasses.replace(self, **overrides)
+
     def run_stream(self, user_message: str, context: ContextStore) -> AgentStream:
         return AgentStream(self._run_loop(user_message, context))
 

axio-0.5.1/src/axio/compaction.py

@@ -0,0 +1,67 @@
+"""Context compaction: summarise old history to stay within token limits."""
+
+from __future__ import annotations
+
+import logging
+
+from axio.agent import Agent
+from axio.blocks import TextBlock, ToolResultBlock
+from axio.context import ContextStore, MemoryContextStore
+from axio.messages import Message
+from axio.transport import CompletionTransport
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_COMPACTION_PROMPT = (
+    "You are a conversation summarizer. You will see a conversation between"
+    " a user and an AI assistant, including tool calls and their results."
+    " Produce a concise summary preserving: user goals, decisions made,"
+    " key facts, tool outcomes, and state changes. Write as narrative prose,"
+    " not as a transcript."
+)
+
+
+async def compact_context(
+    context: ContextStore,
+    transport: CompletionTransport,
+    *,
+    max_messages: int = 20,
+    keep_recent: int = 6,
+    system_prompt: str = _DEFAULT_COMPACTION_PROMPT,
+) -> list[Message] | None:
+    """Summarize old messages from *context*, keeping recent ones verbatim.
+
+    Returns a compacted message list ready to populate a fresh store,
+    or ``None`` when no compaction is needed.
+    """
+    history = await context.get_history()
+    if len(history) <= max_messages:
+        return None
+
+    split = _find_safe_boundary(history, keep_recent)
+    if split <= 0:
+        return None
+
+    old, recent = history[:split], history[split:]
+
+    summary_ctx = MemoryContextStore(old)
+    agent = Agent(system=system_prompt, transport=transport, max_iterations=1)
+    try:
+        summary = await agent.run("Summarize the conversation above.", summary_ctx)
+    except Exception:
+        logger.warning("Context compaction failed, keeping original history", exc_info=True)
+        return None
+
+    return [
+        Message(role="user", content=[TextBlock(text=summary)]),
+        Message(role="assistant", content=[TextBlock(text="Understood, context restored.")]),
+        *recent,
+    ]
+
+
+def _find_safe_boundary(history: list[Message], keep_recent: int) -> int:
+    """Return a split index that never separates a tool_use from its tool_result."""
+    split = len(history) - keep_recent
+    while split > 0 and any(isinstance(b, ToolResultBlock) for b in history[split].content):
+        split -= 1
+    return split

{axio-0.4.1 → axio-0.5.1}/src/axio/context.py

@@ -9,9 +9,8 @@ from dataclasses import dataclass
 from typing import Self
 from uuid import uuid4
 
-from axio.blocks import TextBlock, ToolResultBlock
+from axio.blocks import TextBlock
 from axio.messages import Message
-from axio.transport import CompletionTransport
 
 logger = logging.getLogger(__name__)
 
@@ -28,8 +27,11 @@ class SessionInfo:
 
 class ContextStore(ABC):
     @property
-    @abstractmethod
-    def session_id(self) -> str: ...
+    def session_id(self) -> str:
+        """Lazy-init UUID hex; works without calling super().__init__()."""
+        if "_session_id" not in self.__dict__:
+            self.__dict__["_session_id"] = uuid4().hex
+        return str(self.__dict__["_session_id"])
 
     @abstractmethod
     async def append(self, message: Message) -> None: ...
@@ -37,20 +39,26 @@ class ContextStore(ABC):
     @abstractmethod
     async def get_history(self) -> list[Message]: ...
 
-    @abstractmethod
-    async def clear(self) -> None: ...
+    async def clear(self) -> None:
+        raise NotImplementedError(f"{type(self).__name__} does not support clear()")
 
-    @abstractmethod
-    async def fork(self) -> ContextStore: ...
+    async def fork(self) -> ContextStore:
+        """Returns a MemoryContextStore deep copy by default."""
+        messages = copy.deepcopy(await self.get_history())
+        in_tok, out_tok = await self.get_context_tokens()
+        store = MemoryContextStore(messages)
+        await store.set_context_tokens(in_tok, out_tok)
+        return store
 
-    @abstractmethod
-    async def set_context_tokens(self, input_tokens: int, output_tokens: int) -> None: ...
+    async def set_context_tokens(self, input_tokens: int, output_tokens: int) -> None:
+        """No-op by default; tokens are silently dropped."""
 
-    @abstractmethod
-    async def get_context_tokens(self) -> tuple[int, int]: ...
+    async def get_context_tokens(self) -> tuple[int, int]:
+        """Returns (0, 0) by default."""
+        return 0, 0
 
-    @abstractmethod
-    async def close(self) -> None: ...
+    async def close(self) -> None:
+        """No-op by default."""
 
     async def list_sessions(self) -> list[SessionInfo]:
         """List available sessions. Default: returns a single entry for the current session."""
@@ -132,66 +140,3 @@ class MemoryContextStore(ContextStore):
 
     async def close(self) -> None:
         pass
-
-
-_DEFAULT_COMPACTION_PROMPT = (
-    "You are a conversation summarizer. You will see a conversation between"
-    " a user and an AI assistant, including tool calls and their results."
-    " Produce a concise summary preserving: user goals, decisions made,"
-    " key facts, tool outcomes, and state changes. Write as narrative prose,"
-    " not as a transcript."
-)
-
-
-async def compact_context(
-    context: ContextStore,
-    transport: CompletionTransport,
-    *,
-    max_messages: int = 20,
-    keep_recent: int = 6,
-    system_prompt: str | None = None,
-) -> list[Message] | None:
-    """Summarize old messages from *context*, keeping recent ones verbatim.
-
-    Returns a compacted message list ready to populate a fresh store,
-    or ``None`` when no compaction is needed.
-    """
-    history = await context.get_history()
-    if len(history) <= max_messages:
-        return None
-
-    split = _find_safe_boundary(history, keep_recent)
-    if split <= 0:
-        return None
-
-    old, recent = history[:split], history[split:]
-
-    # Deferred import to avoid circular dependency (context ↔ agent)
-    from axio.agent import Agent
-
-    summary_ctx = MemoryContextStore(old)
-    agent = Agent(
-        system=system_prompt or _DEFAULT_COMPACTION_PROMPT,
-        tools=[],
-        transport=transport,
-        max_iterations=1,
-    )
-    try:
-        summary = await agent.run("Summarize the conversation above.", summary_ctx)
-    except Exception:
-        logger.warning("Context compaction failed, keeping original history", exc_info=True)
-        return None
-
-    return [
-        Message(role="user", content=[TextBlock(text=summary)]),
-        Message(role="assistant", content=[TextBlock(text="Understood, context restored.")]),
-        *recent,
-    ]
-
-
-def _find_safe_boundary(history: list[Message], keep_recent: int) -> int:
-    """Return a split index that never separates a tool_use from its tool_result."""
-    split = len(history) - keep_recent
-    while split > 0 and any(isinstance(b, ToolResultBlock) for b in history[split].content):
-        split -= 1
-    return split

{axio-0.4.1 → axio-0.5.1}/src/axio/models.py

@@ -91,3 +91,15 @@ class ModelRegistry(MutableMapping[str, ModelSpec]):
 
     def ids(self) -> list[str]:
         return list(self._models)
+
+    def _get_model_by_index(self, index: int) -> ModelSpec:
+        vals = list(iter(self._models.values()))
+        if len(vals) >= 1:
+            return vals[index]
+        raise IndexError("ModelRegistry is empty")
+
+    def first(self) -> ModelSpec:
+        return self._get_model_by_index(0)
+
+    def last(self) -> ModelSpec:
+        return self._get_model_by_index(-1)

{axio-0.4.1 → axio-0.5.1}/src/axio/transport.py

@@ -1,4 +1,12 @@
-"""Transport protocols: completion, image gen, TTS, STT."""
+"""Transport protocols: completion, image gen, TTS, STT.
+
+Transports should be stateless — all request state lives in the arguments
+passed to each method call.  This allows multiple agents to share a single
+transport instance and call it concurrently without interference.
+
+The one allowed exception is a reusable connection pool (e.g. an
+``aiohttp.ClientSession``), which is safe to share across concurrent calls.
+"""
 
 from __future__ import annotations
 

{axio-0.4.1 → axio-0.5.1}/tests/test_context.py

@@ -6,7 +6,8 @@ from collections.abc import AsyncIterator
 from typing import Literal
 
 from axio.blocks import TextBlock, ToolResultBlock
-from axio.context import ContextStore, MemoryContextStore, _find_safe_boundary, compact_context
+from axio.compaction import _find_safe_boundary, compact_context
+from axio.context import ContextStore, MemoryContextStore
 from axio.events import StreamEvent
 from axio.messages import Message
 from axio.testing import StubTransport, make_text_response

axio-0.5.1/tests/test_models.py

@@ -0,0 +1,61 @@
+"""Tests for ModelRegistry.first() and ModelRegistry.last()."""
+
+from __future__ import annotations
+
+import pytest
+
+from axio.models import ModelRegistry, ModelSpec
+
+A = ModelSpec(id="a", input_cost=1.0)
+B = ModelSpec(id="b", input_cost=2.0)
+C = ModelSpec(id="c", input_cost=3.0)
+
+
+def test_first_single() -> None:
+    reg = ModelRegistry([A])
+    assert reg.first() == A
+
+
+def test_last_single() -> None:
+    reg = ModelRegistry([A])
+    assert reg.last() == A
+
+
+def test_first_last_same_for_single_element() -> None:
+    reg = ModelRegistry([A])
+    assert reg.first() == reg.last()
+
+
+def test_first_multi() -> None:
+    reg = ModelRegistry([A, B, C])
+    assert reg.first() == A
+
+
+def test_last_multi() -> None:
+    reg = ModelRegistry([A, B, C])
+    assert reg.last() == C
+
+
+def test_first_empty_raises() -> None:
+    reg = ModelRegistry()
+    with pytest.raises(IndexError, match="ModelRegistry is empty"):
+        reg.first()
+
+
+def test_last_empty_raises() -> None:
+    reg = ModelRegistry()
+    with pytest.raises(IndexError, match="ModelRegistry is empty"):
+        reg.last()
+
+
+def test_first_after_by_cost() -> None:
+    reg = ModelRegistry([C, A, B])
+    cheapest = reg.by_cost()
+    assert cheapest.first() == A
+
+
+def test_last_after_by_cost() -> None:
+    reg = ModelRegistry([C, A, B])
+    priciest = reg.by_cost(desc=True)
+    assert priciest.first() == C
+    assert priciest.last() == A