harnessed 0.1.0__tar.gz

harnessed-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mathisarends
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harnessed-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: harnessed
+Version: 0.1.0
+Summary: A composable Python agent SDK with reversible plugins and a durable session log.
+Author: mathisarends
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/mathisarends/harnessed/blob/main/docs/index.md
+Project-URL: Repository, https://github.com/mathisarends/harnessed
+Project-URL: Issues, https://github.com/mathisarends/harnessed/issues
+Project-URL: Changelog, https://github.com/mathisarends/harnessed/blob/main/docs/releases.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: openai
+Requires-Dist: pydantic-ai-slim[openai]<3,>=2.63; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: pydantic-ai-slim[anthropic]<3,>=2.63; extra == "anthropic"
+Provides-Extra: google
+Requires-Dist: pydantic-ai-slim[google]<3,>=2.63; extra == "google"
+Provides-Extra: skills
+Requires-Dist: pyyaml<7,>=6.0.3; extra == "skills"
+Dynamic: license-file
+
+# Harnessed
+
+A Python agent SDK built from reversible plugins. Harnessed owns the loop,
+tool policies and append-only session log; optional provider integrations use
+PydanticAI's Direct API. Python **3.12-3.14**, Pydantic v2 and modern generics.
+
+Harnessed 0.1.x is **alpha software**. APIs and persisted session formats may
+change in minor releases before 1.0. See the
+[release notes and compatibility policy](https://github.com/mathisarends/harnessed/blob/main/docs/releases.md).
+
+## Core SDK
+
+```bash
+uv add "harnessed[openai]"
+```
+
+```python
+import asyncio
+from harnessed import Agent, Plugin, tool
+
+
+class Calculator(Plugin):
+    @tool(readonly=True)
+    async def add(self, a: int, b: int) -> int:
+        """Add two integers."""
+        return a + b
+
+
+agent = Agent(
+    model="deepseek:deepseek-chat",  # DEEPSEEK_API_KEY
+    instructions="Keep answers concise.",
+    plugins=[Calculator()],
+)
+
+
+async def main():
+    async with agent.session() as session:
+        result = await session.run("What is 19 + 23?")
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+`Agent` has three configuration inputs: `model`, `instructions`, and `plugins`.
+It is reusable; each session owns its runtime and plugin lifetimes.
+
+- **Composition:** tools, policies and capabilities are plugins. Slots replace
+  defaults, and `agent.plugins` shows the resolved composition.
+- **Ownership:** removing a plugin removes its registrations and effects.
+  Explicit `needs` suspend and rebuild dependent plugins as services change.
+- **Context:** instructions and plugin guidance are fixed per session; named
+  context values and steering supply changes during a run.
+- **History:** immutable events are the source of truth. Persistence, replay,
+  forks and control outcomes use the same append-only log.
+
+## Test without credentials
+
+```python
+from harnessed.testing import ScriptedModel, assert_tool_called, call, reply
+
+model = ScriptedModel([call(Calculator.add, a=19, b=23), reply("42")])
+agent = Agent(model=model, plugins=[Calculator()])
+
+# Inside an async function:
+# result = await agent.run("Add 19 and 23")
+# assert_tool_called(result, "add", a=19, b=23)
+```
+
+## Read by topic
+
+Start with the [documentation index](https://github.com/mathisarends/harnessed/blob/main/docs/index.md) or the
+[SDK reference](https://github.com/mathisarends/harnessed/blob/main/docs/reference/sdk.md).
+
+- [Models and provider settings](https://github.com/mathisarends/harnessed/blob/main/docs/guides/models.md)
+- [Tools, hooks and cancellation](https://github.com/mathisarends/harnessed/blob/main/docs/guides/tools.md)
+- [Plugin composition and lifecycle](https://github.com/mathisarends/harnessed/blob/main/docs/guides/plugins.md)
+- [Instructions and changing context](https://github.com/mathisarends/harnessed/blob/main/docs/guides/context.md)
+- [Sessions, controls, persistence and forks](https://github.com/mathisarends/harnessed/blob/main/docs/guides/sessions.md)
+- [Namespaced events and custom extensions](https://github.com/mathisarends/harnessed/blob/main/docs/guides/events.md)
+- [Approvals and headless operation](https://github.com/mathisarends/harnessed/blob/main/docs/guides/approvals.md)
+- [Offline testing](https://github.com/mathisarends/harnessed/blob/main/docs/guides/testing.md)
+- [Executable examples](https://github.com/mathisarends/harnessed/blob/main/docs/guides/examples.md)
+- [Development and CI](https://github.com/mathisarends/harnessed/blob/main/docs/contributing/development.md)
+
+The standalone `harnessed.kernel` uses only the standard library. Optional
+features live under `harnessed.plugins`; providers live under `harnessed.models`.
+
+Inspired by [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+and [Cordis](https://github.com/cordiverse/cordis).
+
+Released under the [MIT License](https://github.com/mathisarends/harnessed/blob/main/LICENSE).

harnessed-0.1.0/README.md

@@ -0,0 +1,92 @@
+# Harnessed
+
+A Python agent SDK built from reversible plugins. Harnessed owns the loop,
+tool policies and append-only session log; optional provider integrations use
+PydanticAI's Direct API. Python **3.12-3.14**, Pydantic v2 and modern generics.
+
+Harnessed 0.1.x is **alpha software**. APIs and persisted session formats may
+change in minor releases before 1.0. See the
+[release notes and compatibility policy](https://github.com/mathisarends/harnessed/blob/main/docs/releases.md).
+
+## Core SDK
+
+```bash
+uv add "harnessed[openai]"
+```
+
+```python
+import asyncio
+from harnessed import Agent, Plugin, tool
+
+
+class Calculator(Plugin):
+    @tool(readonly=True)
+    async def add(self, a: int, b: int) -> int:
+        """Add two integers."""
+        return a + b
+
+
+agent = Agent(
+    model="deepseek:deepseek-chat",  # DEEPSEEK_API_KEY
+    instructions="Keep answers concise.",
+    plugins=[Calculator()],
+)
+
+
+async def main():
+    async with agent.session() as session:
+        result = await session.run("What is 19 + 23?")
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+`Agent` has three configuration inputs: `model`, `instructions`, and `plugins`.
+It is reusable; each session owns its runtime and plugin lifetimes.
+
+- **Composition:** tools, policies and capabilities are plugins. Slots replace
+  defaults, and `agent.plugins` shows the resolved composition.
+- **Ownership:** removing a plugin removes its registrations and effects.
+  Explicit `needs` suspend and rebuild dependent plugins as services change.
+- **Context:** instructions and plugin guidance are fixed per session; named
+  context values and steering supply changes during a run.
+- **History:** immutable events are the source of truth. Persistence, replay,
+  forks and control outcomes use the same append-only log.
+
+## Test without credentials
+
+```python
+from harnessed.testing import ScriptedModel, assert_tool_called, call, reply
+
+model = ScriptedModel([call(Calculator.add, a=19, b=23), reply("42")])
+agent = Agent(model=model, plugins=[Calculator()])
+
+# Inside an async function:
+# result = await agent.run("Add 19 and 23")
+# assert_tool_called(result, "add", a=19, b=23)
+```
+
+## Read by topic
+
+Start with the [documentation index](https://github.com/mathisarends/harnessed/blob/main/docs/index.md) or the
+[SDK reference](https://github.com/mathisarends/harnessed/blob/main/docs/reference/sdk.md).
+
+- [Models and provider settings](https://github.com/mathisarends/harnessed/blob/main/docs/guides/models.md)
+- [Tools, hooks and cancellation](https://github.com/mathisarends/harnessed/blob/main/docs/guides/tools.md)
+- [Plugin composition and lifecycle](https://github.com/mathisarends/harnessed/blob/main/docs/guides/plugins.md)
+- [Instructions and changing context](https://github.com/mathisarends/harnessed/blob/main/docs/guides/context.md)
+- [Sessions, controls, persistence and forks](https://github.com/mathisarends/harnessed/blob/main/docs/guides/sessions.md)
+- [Namespaced events and custom extensions](https://github.com/mathisarends/harnessed/blob/main/docs/guides/events.md)
+- [Approvals and headless operation](https://github.com/mathisarends/harnessed/blob/main/docs/guides/approvals.md)
+- [Offline testing](https://github.com/mathisarends/harnessed/blob/main/docs/guides/testing.md)
+- [Executable examples](https://github.com/mathisarends/harnessed/blob/main/docs/guides/examples.md)
+- [Development and CI](https://github.com/mathisarends/harnessed/blob/main/docs/contributing/development.md)
+
+The standalone `harnessed.kernel` uses only the standard library. Optional
+features live under `harnessed.plugins`; providers live under `harnessed.models`.
+
+Inspired by [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+and [Cordis](https://github.com/cordiverse/cordis).
+
+Released under the [MIT License](https://github.com/mathisarends/harnessed/blob/main/LICENSE).

harnessed-0.1.0/harnessed/__init__.py

@@ -0,0 +1,58 @@
+import logging
+from importlib import import_module
+from typing import Any
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+# Keep the standalone kernel independent of Pydantic and optional provider SDKs.
+_EXPORTS = {
+    "Agent": ("harnessed.agent", "Agent"),
+    "ApprovalAnswer": ("harnessed.core.messages", "ApprovalAnswer"),
+    "ApprovalRequest": ("harnessed.core.session.events", "ApprovalRequested"),
+    "Context": ("harnessed.kernel", "Context"),
+    "File": ("harnessed.core.attachments", "File"),
+    "Image": ("harnessed.core.attachments", "Image"),
+    "ImageDetail": ("harnessed.core.messages", "ImageDetail"),
+    "Inject": ("harnessed.kernel", "Inject"),
+    "Observation": ("harnessed.core.messages", "Observation"),
+    "OutputContract": ("harnessed.core.outputs", "OutputContract"),
+    "Plugin": ("harnessed.core.plugin", "Plugin"),
+    "PluginConfig": ("harnessed.core.plugin", "PluginConfig"),
+    "PluginState": ("harnessed.kernel", "PluginState"),
+    "PluginConflict": ("harnessed.core.errors", "PluginConflict"),
+    "PolicyDecision": ("harnessed.core.messages", "PolicyDecision"),
+    "Role": ("harnessed.core.messages", "Role"),
+    "RunHandle": ("harnessed.core.runtime.handles", "RunHandle"),
+    "RunResult": ("harnessed.core.runtime.result", "RunResult"),
+    "Section": ("harnessed.core.prompt.values", "Section"),
+    "Session": ("harnessed.core.runtime.session", "Session"),
+    "SessionClosed": ("harnessed.core.errors", "SessionClosed"),
+    "SessionStatus": ("harnessed.core.runtime.control", "SessionStatus"),
+    "StopReason": ("harnessed.core.model", "StopReason"),
+    "StreamOverflow": ("harnessed.core.errors", "StreamOverflow"),
+    "ToolCall": ("harnessed.core.messages", "ToolCall"),
+    "ToolContext": ("harnessed.core.tools.context", "ToolContext"),
+    "ToolError": ("harnessed.core.tools.registry", "ToolError"),
+    "ToolResult": ("harnessed.core.messages", "ToolResult"),
+    "ToolStatus": ("harnessed.core.messages", "ToolStatus"),
+    "hook": ("harnessed.kernel", "hook"),
+    "plugin": ("harnessed.kernel", "plugin"),
+    "tool": ("harnessed.core.tools.decorator", "tool"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module, attribute = _EXPORTS[name]
+    value = getattr(import_module(module), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_EXPORTS))
+
+
+__all__ = sorted(_EXPORTS)

harnessed-0.1.0/harnessed/__init__.pyi

@@ -0,0 +1,68 @@
+from harnessed.agent import Agent as Agent
+from harnessed.core.attachments import File as File
+from harnessed.core.attachments import Image as Image
+from harnessed.core.errors import PluginConflict as PluginConflict
+from harnessed.core.errors import SessionClosed as SessionClosed
+from harnessed.core.errors import StreamOverflow as StreamOverflow
+from harnessed.core.messages import ApprovalAnswer as ApprovalAnswer
+from harnessed.core.messages import ImageDetail as ImageDetail
+from harnessed.core.messages import Observation as Observation
+from harnessed.core.messages import PolicyDecision as PolicyDecision
+from harnessed.core.messages import Role as Role
+from harnessed.core.messages import ToolCall as ToolCall
+from harnessed.core.messages import ToolResult as ToolResult
+from harnessed.core.messages import ToolStatus as ToolStatus
+from harnessed.core.model import StopReason as StopReason
+from harnessed.core.outputs import OutputContract as OutputContract
+from harnessed.core.plugin import Plugin as Plugin
+from harnessed.core.plugin import PluginConfig as PluginConfig
+from harnessed.core.prompt.values import Section as Section
+from harnessed.core.runtime.control import SessionStatus as SessionStatus
+from harnessed.core.runtime.handles import RunHandle as RunHandle
+from harnessed.core.runtime.result import RunResult as RunResult
+from harnessed.core.runtime.session import Session as Session
+from harnessed.core.session.events import ApprovalRequested as ApprovalRequest
+from harnessed.core.tools.context import ToolContext as ToolContext
+from harnessed.core.tools.decorator import tool as tool
+from harnessed.core.tools.registry import ToolError as ToolError
+from harnessed.kernel import Context as Context
+from harnessed.kernel import Inject as Inject
+from harnessed.kernel import PluginState as PluginState
+from harnessed.kernel import hook as hook
+from harnessed.kernel import plugin as plugin
+
+from . import events as events
+
+__all__ = [
+    "Agent",
+    "ApprovalAnswer",
+    "ApprovalRequest",
+    "Context",
+    "File",
+    "Image",
+    "ImageDetail",
+    "Inject",
+    "Observation",
+    "OutputContract",
+    "Plugin",
+    "PluginConfig",
+    "PluginConflict",
+    "PolicyDecision",
+    "Role",
+    "RunHandle",
+    "RunResult",
+    "Section",
+    "Session",
+    "SessionClosed",
+    "SessionStatus",
+    "StopReason",
+    "StreamOverflow",
+    "ToolCall",
+    "ToolContext",
+    "ToolError",
+    "ToolResult",
+    "ToolStatus",
+    "hook",
+    "plugin",
+    "tool",
+]

harnessed-0.1.0/harnessed/agent.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Iterable
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, Unpack, overload
+
+from harnessed.core.approvals import Approvals
+from harnessed.core.errors import PluginConflict
+from harnessed.core.event_registry import EventRegistry
+from harnessed.core.model import Model
+from harnessed.core.outputs import OutputContract, OutputTypes
+from harnessed.core.plugin import Service, plugin_contribution, plugin_events
+from harnessed.core.prompt.instructions import Instructions
+from harnessed.core.prompt.values import InstructionValues, PromptComposition
+from harnessed.core.runtime.agent_loop import AgentLoop
+from harnessed.core.runtime.opener import open_session
+from harnessed.core.runtime.options import RunOptions
+from harnessed.core.runtime.result import RunResult
+from harnessed.core.runtime.services import RuntimeServices
+from harnessed.core.runtime.session import Session
+from harnessed.core.session.repository import SessionRepository
+from harnessed.core.session.session import SessionLog
+from harnessed.core.session.store import MemorySessions
+from harnessed.core.tools.output_limit import ToolOutputLimit
+from harnessed.core.tracing import NoopTracer
+from harnessed.kernel import Context, PluginLike
+from harnessed.kernel.plugin import as_plugin_spec
+from harnessed.models.pydantic_ai import PydanticAIModel
+
+if TYPE_CHECKING:
+    from harnessed.models.pydantic_ai import NativeModel
+
+
+class Agent:
+    """Resolve model, instructions and plugins into a reusable configuration.
+
+    Each opened session owns its runtime and plugin lifetimes. The configured
+    session-store plugin retains conversations and enforces a single writer.
+    """
+
+    def __init__(
+        self,
+        *,
+        model: Model | str | NativeModel | None = None,
+        instructions: InstructionValues | None = None,
+        plugins: Iterable[PluginLike] = (),
+    ) -> None:
+        supplied: list[PluginLike] = list(plugins)
+        if instructions is not None:
+            supplied.insert(0, Instructions(instructions))
+        if model is not None:
+            supplied.insert(0, Service(Model, model))
+        normalized: list[PluginLike] = []
+        for value in supplied:
+            if isinstance(value, Service) and value.key is Model:
+                implementation = value.value
+                if not isinstance(implementation, Model):
+                    implementation = PydanticAIModel(implementation)
+                value = Service(Model, implementation)
+            normalized.append(value)
+        declared = next((value for value in normalized if isinstance(value, Instructions)), None)
+        self.prompt = PromptComposition(
+            declared.values if declared is not None else (),
+            (plugin_contribution(value) for value in normalized),
+        )
+        defaults: list[PluginLike] = [
+            AgentLoop(),
+            MemorySessions(),
+            ToolOutputLimit(),
+            Approvals(),
+            NoopTracer(),
+            Instructions(composition=self.prompt),
+        ]
+        occupied = {as_plugin_spec(value).slot: index for index, value in enumerate(defaults)}
+        explicit: set[str] = set()
+        for value in normalized:
+            if isinstance(value, Instructions):
+                value = Instructions(value.values, composition=self.prompt)
+            spec = as_plugin_spec(value)
+            if spec.slot is not None:
+                if spec.slot in explicit:
+                    raise PluginConflict(f"Multiple plugins in slot {spec.slot!r}")
+                explicit.add(spec.slot)
+                if spec.slot in occupied:
+                    defaults[occupied[spec.slot]] = value
+                    continue
+                occupied[spec.slot] = len(defaults)
+            defaults.append(value)
+        self.plugins = (RuntimeServices(), *defaults)
+        self._events = EventRegistry(
+            kind for plugin in self.plugins for kind in plugin_events(plugin)
+        )
+        self.sessions = SessionRepository(self.plugins, registry=self._events)
+
+    @asynccontextmanager
+    async def session(
+        self,
+        session_id: str | SessionLog | None = None,
+        *,
+        restore_outputs: Iterable[type[Any] | OutputContract[Any]] = (),
+    ) -> AsyncGenerator[Session]:
+        """Open or resume a conversation; omit its ID to create a new one."""
+        async with Context() as ctx:
+            ctx.provide(EventRegistry, self._events.copy())
+            # Validators are per session, so dynamic output types never leak between them.
+            outputs = OutputTypes()
+            for output in restore_outputs:
+                outputs.register(output)
+            ctx.provide(OutputTypes, outputs)
+            await ctx.install(self.plugins, settle=True)
+            yield await open_session(ctx, session_id)
+
+    @overload
+    async def run[T](
+        self, prompt: str, *, output: type[T] | OutputContract[T], **options: Unpack[RunOptions]
+    ) -> RunResult[T]: ...
+
+    @overload
+    async def run(
+        self, prompt: str, *, output: None = None, **options: Unpack[RunOptions]
+    ) -> RunResult[None]: ...
+
+    async def run(
+        self,
+        prompt: str,
+        *,
+        output: type[Any] | OutputContract[Any] | None = None,
+        **options: Unpack[RunOptions],
+    ) -> RunResult[Any]:
+        """Run one task in a new session."""
+        async with self.session() as session:
+            return await session.run(prompt, output=output, **options)