agentharness-sdk 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+agentharness/__init__.py,sha256=5Wb6_LloiuexBXEAc4KQcvleBKJu5r58FDf8OeekzwA,1204
+agentharness/agent.py,sha256=qHi0Y_oR87b_SaFikHUZqY3XeK9ZKvqEP2zpbTwQNUs,2194
+agentharness/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentharness/testing.py,sha256=l-LHGCP-o7tmCEK8nmC_NqWb3laUBbTeRlbGYXqQ6iU,783
+agentharness/tools.py,sha256=bTYbfC4hDXuohPobTidgGIRubM2rIS2wZG2FqtGuFAI,3441
+agentharness_sdk-0.1.0.dist-info/METADATA,sha256=o5-57wjJCqiRT9bOBQ7EuPWUhfu4qEeq7HCkj0aseU4,1990
+agentharness_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentharness_sdk-0.1.0.dist-info/RECORD,,

agentharness_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any