agentharness-sdk 0.1.0__tar.gz

agentharness_sdk-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Environments
+.venv/
+venv/
+.env
+
+# uv
+.uv/
+
+# Docs build output
+site/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+htmlcov/
+.coverage
+.coverage.*
+
+# Codex run artifacts (local only)
+codex-core.log
+codex-core-result.txt
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

agentharness_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: agentharness-sdk
+Version: 0.1.0
+Summary: Ergonomic agent harness on top of agentharness-core: Agent, @tool, and testable, replayable runs. Imports as `agentharness`.
+Project-URL: Homepage, https://github.com/aafre/agentharness
+Project-URL: Source, https://github.com/aafre/agentharness
+Author: AgentHarness contributors
+License-Expression: Apache-2.0
+Keywords: agent,ai,deterministic,llm,replay,state-machine,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: agentharness-core>=0.1.0
+Description-Content-Type: text/markdown
+
+# agentharness
+
+The ergonomic, batteries-included layer over [`agentharness-core`](../agentharness-core).
+
+```python
+from agentharness import Agent, tool
+
+@tool
+def add(a: int, b: int) -> str:
+    """Add two numbers."""
+    return str(a + b)
+
+agent = Agent(model=my_model, tools=[add], system="You are helpful.")
+run = agent.run("What is 2 + 3?")
+print(run.result)          # "2 + 3 = 5."
+run.trace.save("run.jsonl")  # the whole run is recorded and replayable
+```
+
+- **`@tool`** turns a typed Python function into a tool — the JSON schema is generated from
+  type hints, no hand-written schemas.
+- **`Agent`** wraps a model + tools + optional system prompt. `run()` executes to completion;
+  `stream()` yields live events; `arun()`/`astream()` are the async variants.
+- Built entirely on the deterministic core, so every agent you build is inspectable and
+  replayable for free (`from agentharness_core import replay`).
+
+Test agents like ordinary code, with no network:
+
+```python
+from agentharness.testing import FakeModel, assert_used_tool, assert_answer
+
+agent = Agent(model=FakeModel([...]), tools=[add])
+run = agent.run("What is 2 + 3?")
+assert_used_tool(run, "add")
+assert_answer(run, "2 + 3 = 5.")
+```

agentharness_sdk-0.1.0/README.md

@@ -0,0 +1,35 @@
+# agentharness
+
+The ergonomic, batteries-included layer over [`agentharness-core`](../agentharness-core).
+
+```python
+from agentharness import Agent, tool
+
+@tool
+def add(a: int, b: int) -> str:
+    """Add two numbers."""
+    return str(a + b)
+
+agent = Agent(model=my_model, tools=[add], system="You are helpful.")
+run = agent.run("What is 2 + 3?")
+print(run.result)          # "2 + 3 = 5."
+run.trace.save("run.jsonl")  # the whole run is recorded and replayable
+```
+
+- **`@tool`** turns a typed Python function into a tool — the JSON schema is generated from
+  type hints, no hand-written schemas.
+- **`Agent`** wraps a model + tools + optional system prompt. `run()` executes to completion;
+  `stream()` yields live events; `arun()`/`astream()` are the async variants.
+- Built entirely on the deterministic core, so every agent you build is inspectable and
+  replayable for free (`from agentharness_core import replay`).
+
+Test agents like ordinary code, with no network:
+
+```python
+from agentharness.testing import FakeModel, assert_used_tool, assert_answer
+
+agent = Agent(model=FakeModel([...]), tools=[add])
+run = agent.run("What is 2 + 3?")
+assert_used_tool(run, "add")
+assert_answer(run, "2 + 3 = 5.")
+```

agentharness_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentharness-sdk"
+version = "0.1.0"
+description = "Ergonomic agent harness on top of agentharness-core: Agent, @tool, and testable, replayable runs. Imports as `agentharness`."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [{ name = "AgentHarness contributors" }]
+keywords = ["agent", "llm", "ai", "tools", "state-machine", "deterministic", "replay"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = ["agentharness-core>=0.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/aafre/agentharness"
+Source = "https://github.com/aafre/agentharness"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentharness"]

agentharness_sdk-0.1.0/src/agentharness/__init__.py

@@ -0,0 +1,61 @@
+"""AgentHarness: the ergonomic, batteries-included layer over ``agentharness-core``.
+
+    from agentharness import Agent, tool
+
+    @tool
+    def add(a: int, b: int) -> str:
+        '''Add two numbers.'''
+        return str(a + b)
+
+    agent = Agent(model=my_model, tools=[add])
+    print(agent.run("What is 2 + 3?").result)
+
+Everything here is built on the deterministic, replayable core, so any agent you build is
+inspectable and replayable for free.
+"""
+
+from __future__ import annotations
+
+# Re-export the core essentials so most users need only ``import agentharness``.
+from agentharness_core import (
+    AsyncRun,
+    DivergenceError,
+    Message,
+    Model,
+    Run,
+    State,
+    Tool,
+    ToolCall,
+    ToolResult,
+    Trace,
+    arun,
+    replay,
+    run,
+)
+
+from .agent import Agent
+from .tools import FunctionTool, tool
+
+__version__ = "0.1.0"
+
+__all__ = [  # noqa: RUF022 - grouped by concept
+    # ergonomic layer
+    "Agent",
+    "tool",
+    "FunctionTool",
+    # core re-exports
+    "run",
+    "arun",
+    "replay",
+    "Run",
+    "AsyncRun",
+    "State",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "Trace",
+    "Model",
+    "Tool",
+    "DivergenceError",
+    "__version__",
+]

agentharness_sdk-0.1.0/src/agentharness/agent.py

@@ -0,0 +1,78 @@
+"""The ``Agent`` ergonomic entry point over the core state machine."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from agentharness_core import (
+    AsyncRun,
+    Message,
+    Model,
+    Run,
+    State,
+    Tool,
+    arun,
+    run,
+)
+
+DEFAULT_MAX_STEPS = 64
+
+
+class Agent:
+    """A model plus its tools and an optional system prompt.
+
+    ``run`` is eager (executes to completion and returns the finished ``Run``, so
+    ``.result``/``.state``/``.trace`` are immediately available). ``stream`` is lazy and
+    yields the live event stream. Every run is recorded and therefore replayable.
+    """
+
+    def __init__(
+        self,
+        *,
+        model: Model,
+        tools: Sequence[Tool] = (),
+        system: str | None = None,
+        max_steps: int = DEFAULT_MAX_STEPS,
+    ) -> None:
+        self.model = model
+        self.tools = list(tools)
+        self.system = system
+        self.max_steps = max_steps
+
+    def _initial_state(self, prompt: str) -> State[None]:
+        messages: list[Message] = []
+        if self.system is not None:
+            messages.append(Message("system", self.system))
+        messages.append(Message("user", prompt))
+        return State.start(messages)
+
+    def stream(self, prompt: str) -> Run:
+        """Return a lazy ``Run`` whose iteration yields live events."""
+        return run(
+            self._initial_state(prompt),
+            model=self.model,
+            tools=self.tools,
+            max_steps=self.max_steps,
+        )
+
+    def run(self, prompt: str) -> Run:
+        """Execute to completion and return the finished ``Run``."""
+        r = self.stream(prompt)
+        r.run_to_completion()
+        return r
+
+    def astream(self, prompt: str) -> AsyncRun:
+        """Async-iterable variant of :meth:`stream`."""
+        return arun(
+            self._initial_state(prompt),
+            model=self.model,
+            tools=self.tools,
+            max_steps=self.max_steps,
+        )
+
+    async def arun(self, prompt: str) -> AsyncRun:
+        """Async variant of :meth:`run`: drain the run, then return it."""
+        r = self.astream(prompt)
+        async for _ in r:
+            pass
+        return r

agentharness_sdk-0.1.0/src/agentharness/testing.py

@@ -0,0 +1,19 @@
+"""Test helpers for agents: deterministic models and readable assertions."""
+
+from __future__ import annotations
+
+from agentharness_core import Run
+from agentharness_core.testing import FakeModel, ScriptedModel
+
+__all__ = ["FakeModel", "ScriptedModel", "assert_answer", "assert_used_tool"]
+
+
+def assert_used_tool(run: Run, name: str) -> None:
+    """Assert the agent invoked the named tool at least once during ``run``."""
+    used = [m.name for m in run.state.messages if m.role == "tool"]
+    assert name in used, f"expected tool {name!r} to be used; tools used: {used}"
+
+
+def assert_answer(run: Run, expected: str) -> None:
+    """Assert the agent's final answer equals ``expected``."""
+    assert run.result == expected, f"expected final answer {expected!r}, got {run.result!r}"

agentharness_sdk-0.1.0/src/agentharness/tools.py

@@ -0,0 +1,105 @@
+"""The ``@tool`` decorator: a typed Python function becomes a core-compatible Tool.
+
+The JSON schema is derived from type hints and the ``required`` set from which parameters
+lack defaults, so a tool is declared once, in plain Python, with no hand-written schema.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types as _pytypes
+from collections.abc import Callable
+from typing import Any, Union, get_args, get_origin, get_type_hints, overload
+
+from agentharness_core import ToolResult
+
+_JSON_SCALARS: dict[type, str] = {
+    int: "integer",
+    float: "number",
+    str: "string",
+    bool: "boolean",
+}
+
+
+def _type_to_schema(tp: Any) -> dict[str, Any]:
+    if tp in _JSON_SCALARS:
+        return {"type": _JSON_SCALARS[tp]}
+    origin = get_origin(tp)
+    if origin is list:
+        args = get_args(tp)
+        return {"type": "array", "items": _type_to_schema(args[0]) if args else {}}
+    if origin is dict:
+        return {"type": "object"}
+    if origin is Union or origin is _pytypes.UnionType:
+        non_none = [a for a in get_args(tp) if a is not type(None)]
+        if len(non_none) == 1:
+            return _type_to_schema(non_none[0])
+    return {}  # unknown / unconstrained
+
+
+def _build_schema(func: Callable[..., Any]) -> dict[str, Any]:
+    signature = inspect.signature(func)
+    hints = get_type_hints(func)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for name, param in signature.parameters.items():
+        if name == "self" or param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+        properties[name] = _type_to_schema(hints.get(name, str))
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+    return {"type": "object", "properties": properties, "required": required}
+
+
+class FunctionTool:
+    """Wraps a callable so it satisfies the core ``Tool`` protocol while staying callable."""
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        self._func = func
+        self.name = name or func.__name__
+        self.description = description or (inspect.getdoc(func) or "")
+        self.schema = _build_schema(func)
+
+    def call(self, arguments: dict[str, Any]) -> ToolResult:
+        result = self._func(**arguments)
+        if isinstance(result, ToolResult):
+            return result
+        return ToolResult(content=result if isinstance(result, str) else str(result))
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._func(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"FunctionTool(name={self.name!r})"
+
+
+@overload
+def tool(func: Callable[..., Any], /) -> FunctionTool: ...
+@overload
+def tool(
+    *, name: str | None = ..., description: str | None = ...
+) -> Callable[[Callable[..., Any]], FunctionTool]: ...
+
+
+def tool(
+    func: Callable[..., Any] | None = None,
+    /,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> FunctionTool | Callable[[Callable[..., Any]], FunctionTool]:
+    """Turn a function into a ``FunctionTool``. Usable as ``@tool`` or ``@tool(name=...)``."""
+
+    def wrap(f: Callable[..., Any]) -> FunctionTool:
+        return FunctionTool(f, name=name, description=description)
+
+    return wrap(func) if func is not None else wrap

agentharness_sdk-0.1.0/tests/test_agent.py

@@ -0,0 +1,71 @@
+"""Contract: Agent is the one-import ergonomic entry point over the core loop."""
+
+from __future__ import annotations
+
+from agentharness import Agent, tool
+from agentharness.testing import FakeModel, assert_answer, assert_used_tool
+from agentharness_core import Message, RunFinished, ToolCall
+
+
+@tool
+def add(a: int, b: int) -> str:
+    """Add two numbers."""
+    return str(a + b)
+
+
+def _add_then_answer() -> FakeModel:
+    return FakeModel(
+        [
+            Message(
+                role="assistant",
+                content=None,
+                tool_calls=(ToolCall(id="c1", name="add", arguments={"a": 2, "b": 3}),),
+            ),
+            Message(role="assistant", content="2 + 3 = 5."),
+        ]
+    )
+
+
+def test_agent_runs_to_completion_and_returns_result() -> None:
+    agent = Agent(model=_add_then_answer(), tools=[add])
+    run = agent.run("What is 2 + 3?")
+
+    assert run.result == "2 + 3 = 5."
+    assert run.state.status == "done"
+
+
+def test_agent_uses_tools() -> None:
+    agent = Agent(model=_add_then_answer(), tools=[add])
+    run = agent.run("What is 2 + 3?")
+
+    assert_used_tool(run, "add")
+    assert_answer(run, "2 + 3 = 5.")
+
+
+def test_agent_includes_system_prompt() -> None:
+    agent = Agent(
+        model=FakeModel([Message(role="assistant", content="hi")]),
+        system="You are terse.",
+    )
+    run = agent.run("hello")
+    assert run.state.messages[0].role == "system"
+    assert run.state.messages[0].content == "You are terse."
+
+
+def test_agent_stream_yields_live_events() -> None:
+    agent = Agent(model=_add_then_answer(), tools=[add])
+    events = list(agent.stream("What is 2 + 3?"))
+    assert isinstance(events[-1], RunFinished)
+
+
+def test_agent_run_is_replayable() -> None:
+    from agentharness_core import State, replay
+
+    agent = Agent(model=_add_then_answer(), tools=[add])
+    run = agent.run("What is 2 + 3?")
+
+    # The recorded run replays identically with no model and no tools.
+    start = State.start([Message("user", "What is 2 + 3?")])
+    replayed = replay(start, trace=run.trace)
+    replayed.run_to_completion()
+    assert replayed.result == run.result

agentharness_sdk-0.1.0/tests/test_tools.py

@@ -0,0 +1,97 @@
+"""Contract: @tool turns a typed Python function into a core-compatible Tool."""
+
+from __future__ import annotations
+
+from agentharness import FunctionTool, tool
+from agentharness_core import Tool, ToolResult
+
+
+def test_tool_decorator_produces_a_core_tool() -> None:
+    @tool
+    def add(a: int, b: int) -> str:
+        """Add two numbers."""
+        return str(a + b)
+
+    assert isinstance(add, FunctionTool)
+    assert isinstance(add, Tool)  # satisfies the structural core protocol
+    assert add.name == "add"
+    assert add.description == "Add two numbers."
+
+
+def test_schema_is_generated_from_type_hints() -> None:
+    @tool
+    def add(a: int, b: int) -> str:
+        return str(a + b)
+
+    assert add.schema == {
+        "type": "object",
+        "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
+        "required": ["a", "b"],
+    }
+
+
+def test_call_wraps_return_in_toolresult() -> None:
+    @tool
+    def add(a: int, b: int) -> str:
+        return str(a + b)
+
+    result = add.call({"a": 2, "b": 3})
+    assert isinstance(result, ToolResult)
+    assert result.content == "5"
+    assert result.is_error is False
+
+
+def test_tool_remains_directly_callable() -> None:
+    @tool
+    def add(a: int, b: int) -> str:
+        return str(a + b)
+
+    assert add(2, 3) == "5"  # the original function still works
+
+
+def test_non_string_return_is_stringified() -> None:
+    @tool
+    def count(n: int) -> int:
+        return n * 2
+
+    assert count.call({"n": 4}).content == "8"
+
+
+def test_toolresult_return_passes_through() -> None:
+    @tool
+    def risky(x: int) -> ToolResult:
+        return ToolResult(content="boom", is_error=True)
+
+    r = risky.call({"x": 1})
+    assert r.is_error is True
+    assert r.content == "boom"
+
+
+def test_decorator_accepts_name_and_description_overrides() -> None:
+    @tool(name="sum2", description="custom")
+    def add(a: int, b: int) -> str:
+        return str(a + b)
+
+    assert add.name == "sum2"
+    assert add.description == "custom"
+
+
+def test_optional_and_defaulted_params_are_not_required() -> None:
+    @tool
+    def greet(name: str, greeting: str = "hello", times: int | None = None) -> str:
+        return f"{greeting} {name}"
+
+    assert greet.schema["required"] == ["name"]
+    assert greet.schema["properties"]["greeting"] == {"type": "string"}
+    assert greet.schema["properties"]["times"] == {"type": "integer"}
+
+
+def test_list_param_schema() -> None:
+    @tool
+    def total(values: list[int]) -> str:
+        return str(sum(values))
+
+    assert total.schema["properties"]["values"] == {
+        "type": "array",
+        "items": {"type": "integer"},
+    }