jharness-toolkit 0.1.0__py3-none-any.whl

jharness/toolkit/__init__.py

@@ -0,0 +1,15 @@
+"""Concrete tool catalog, adapters, and decorators for kernel."""
+
+from jharness.toolkit.decorators import CircuitBreakingTool, RetryingTool
+from jharness.toolkit.registry import ToolRegistry
+from jharness.toolkit.tool import FunctionTool, Tool, ToolFunction, function_tool
+
+__all__ = [
+    "CircuitBreakingTool",
+    "FunctionTool",
+    "RetryingTool",
+    "Tool",
+    "ToolFunction",
+    "ToolRegistry",
+    "function_tool",
+]

jharness/toolkit/decorators.py

@@ -0,0 +1,75 @@
+"""Composable tool execution policies outside kernel state-machine semantics."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from threading import Lock
+
+from jharness.kernel import SettledResult, ToolCall, ToolContext, ToolFailure, ToolResult, ToolSpec
+from jharness.toolkit.tool import Tool
+
+
+@dataclass(frozen=True, slots=True)
+class RetryingTool:
+    """Retry implementation exceptions for an explicitly idempotent tool."""
+
+    tool: Tool
+    max_attempts: int = 2
+    attempt_timeout_seconds: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        if self.max_attempts > 1 and not self.spec.execution.idempotent:
+            raise ValueError("retrying tool must be idempotent")
+        if self.attempt_timeout_seconds is not None and self.attempt_timeout_seconds <= 0:
+            raise ValueError("attempt_timeout_seconds must be > 0")
+
+    @property
+    def spec(self) -> ToolSpec:
+        return self.tool.spec
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        attempt = 1
+        while True:
+            try:
+                async with asyncio.timeout(self.attempt_timeout_seconds):
+                    return await self.tool.invoke(call, context)
+            except Exception:
+                if attempt == self.max_attempts:
+                    raise
+                attempt += 1
+                await asyncio.sleep(0)
+
+
+@dataclass(slots=True)
+class CircuitBreakingTool:
+    """Reject calls after consecutive implementation exceptions."""
+
+    tool: Tool
+    failure_threshold: int = 3
+    _lock: Lock = field(default_factory=Lock, init=False, repr=False, compare=False)
+    _failures: int = field(default=0, init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.failure_threshold < 1:
+            raise ValueError("failure_threshold must be >= 1")
+
+    @property
+    def spec(self) -> ToolSpec:
+        return self.tool.spec
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        with self._lock:
+            if self._failures >= self.failure_threshold:
+                return SettledResult(ToolFailure.from_error("circuit_open", "tool circuit is open"))
+        try:
+            result = await self.tool.invoke(call, context)
+        except Exception:
+            with self._lock:
+                self._failures += 1
+            raise
+        with self._lock:
+            self._failures = 0
+        return result

jharness/toolkit/py.typed

@@ -0,0 +1 @@
+

jharness/toolkit/registry.py

@@ -0,0 +1,181 @@
+"""Immutable invocation catalogs with compiled JSON Schema validation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from inspect import iscoroutinefunction
+from threading import Lock
+from types import MappingProxyType
+from typing import Any, cast
+from uuid import uuid4
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import SchemaError, ValidationError
+from jsonschema.protocols import Validator
+from referencing import Registry
+from referencing.jsonschema import DRAFT202012, Schema, SchemaRegistry, SchemaResource
+
+from jharness.kernel import (
+    SettledResult,
+    ToolBinding,
+    ToolCall,
+    ToolCatalog,
+    ToolContext,
+    ToolError,
+    ToolResult,
+    ToolSpec,
+    WaitingResult,
+    thaw_json_value,
+)
+from jharness.toolkit.tool import Tool
+
+
+@dataclass(frozen=True, slots=True)
+class _Registered:
+    tool: Tool
+    spec: ToolSpec
+    input_validator: Validator
+    output_validator: Validator | None
+
+
+class ToolRegistry:
+    """Thread-safe registry that opens immutable invocation catalogs."""
+
+    __slots__ = ("_entries", "_lock")
+
+    def __init__(self, tools: Sequence[Tool] = ()) -> None:
+        self._lock = Lock()
+        self._entries: dict[str, _Registered] = {}
+        for tool in tools:
+            self.register(tool)
+
+    def register(self, tool: Tool) -> None:
+        _validate_tool(tool)
+        spec = tool.spec
+        registered = _Registered(
+            tool,
+            spec,
+            _compile_schema(spec.input_schema, f"tool {spec.name} input_schema"),
+            (
+                None
+                if spec.output_schema is None
+                else _compile_schema(
+                    spec.output_schema,
+                    f"tool {spec.name} output_schema",
+                )
+            ),
+        )
+        with self._lock:
+            if spec.name in self._entries:
+                raise ValueError(f"duplicate tool name: {spec.name}")
+            self._entries[spec.name] = registered
+
+    async def open_catalog(self) -> ToolCatalog:
+        with self._lock:
+            return _Catalog(self._entries)
+
+
+class _Catalog:
+    __slots__ = ("_entries", "_specs")
+
+    def __init__(self, entries: Mapping[str, _Registered]) -> None:
+        self._entries = MappingProxyType(dict(entries))
+        self._specs = tuple(entry.spec for entry in self._entries.values())
+
+    def specs(self) -> tuple[ToolSpec, ...]:
+        return self._specs
+
+    def spec(self, name: str) -> ToolSpec | None:
+        entry = self._entries.get(name)
+        return None if entry is None else entry.spec
+
+    def bind(self, call: ToolCall) -> ToolBinding:
+        entry = self._entries.get(call.name)
+        if entry is None:
+            raise ToolError(f"unknown tool: {call.name}")
+        try:
+            entry.input_validator.validate(thaw_json_value(call.arguments))
+        except ValidationError as exc:
+            raise ToolError(
+                f"tool {call.name} arguments do not match input_schema: {exc.message}"
+            ) from exc
+        return _Binding(call, entry)
+
+
+@dataclass(frozen=True, slots=True)
+class _Binding:
+    call: ToolCall
+    _entry: _Registered
+
+    @property
+    def spec(self) -> ToolSpec:
+        return self._entry.spec
+
+    async def invoke(self, context: ToolContext) -> ToolResult:
+        result = _ensure_result(await self._entry.tool.invoke(self.call, context))
+        validator = self._entry.output_validator
+        if validator is not None:
+            try:
+                validator.validate(thaw_json_value(result.outcome.structured_content))
+            except ValidationError as exc:
+                raise ToolError(
+                    f"tool {self.call.name} structured_content does not match "
+                    f"output_schema: {exc.message}"
+                ) from exc
+        return result
+
+
+def _compile_schema(
+    schema: Mapping[str, Any] | bool,
+    label: str,
+) -> Validator:
+    plain: Schema = (
+        schema if isinstance(schema, bool) else cast(dict[str, Any], thaw_json_value(schema))
+    )
+    try:
+        Draft202012Validator.check_schema(plain)
+    except SchemaError as exc:
+        raise ValueError(f"{label} must be a valid JSON Schema: {exc.message}") from exc
+    base = (
+        cast(str, plain.get("$id"))
+        if isinstance(plain, dict) and isinstance(plain.get("$id"), str)
+        else f"urn:jharness:toolkit:schema:{uuid4()}"
+    )
+    resource: SchemaResource = DRAFT202012.create_resource(plain)
+    registry: SchemaRegistry = Registry[Schema]().with_resource(base, resource).crawl()
+    resolver = registry.resolver(base)
+    try:
+        for reference in _references(plain):
+            resolver.lookup(reference)
+    except Exception as exc:
+        raise ValueError(f"{label} contains an unresolvable reference") from exc
+    return Draft202012Validator(plain, registry=registry)
+
+
+def _ensure_result(value: object) -> ToolResult:
+    if not isinstance(value, SettledResult | WaitingResult):
+        raise ToolError("tool invoke must return SettledResult or WaitingResult")
+    return value
+
+
+def _validate_tool(value: object) -> None:
+    if not isinstance(value, Tool):
+        raise TypeError("registered tool must implement Tool")
+    if not isinstance(cast(object, value.spec), ToolSpec):
+        raise TypeError("registered tool spec must be ToolSpec")
+    if not iscoroutinefunction(value.invoke):
+        raise TypeError("registered tool invoke must be async")
+
+
+def _references(value: object) -> Iterator[str]:
+    if isinstance(value, Mapping):
+        mapping = cast(Mapping[object, object], value)
+        reference = mapping.get("$ref")
+        if isinstance(reference, str):
+            yield reference
+        for item in mapping.values():
+            yield from _references(item)
+    elif isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+        for item in cast(Sequence[object], value):
+            yield from _references(item)

jharness/toolkit/tool.py

@@ -0,0 +1,75 @@
+"""Concrete Python tool protocol and function adapter."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine, Mapping
+from dataclasses import dataclass
+from inspect import iscoroutinefunction
+from typing import Any, Protocol, cast, runtime_checkable
+
+from jharness.kernel import (
+    ToolCall,
+    ToolContext,
+    ToolExecution,
+    ToolResult,
+    ToolRisk,
+    ToolSpec,
+)
+
+
+@runtime_checkable
+class Tool(Protocol):
+    """One async invocation operation and one immutable specification."""
+
+    @property
+    def spec(self) -> ToolSpec: ...
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult: ...
+
+
+ToolFunction = Callable[[ToolCall, ToolContext], Coroutine[Any, Any, ToolResult]]
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionTool:
+    """Adapt one async function to the concrete tool protocol."""
+
+    spec: ToolSpec
+    function: ToolFunction
+
+    def __post_init__(self) -> None:
+        if not isinstance(cast(object, self.spec), ToolSpec):
+            raise TypeError("function tool spec must be ToolSpec")
+        if not iscoroutinefunction(self.function):
+            raise TypeError("function tool must be async")
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        return await self.function(call, context)
+
+
+def function_tool(
+    *,
+    name: str,
+    description: str,
+    input_schema: Mapping[str, Any] | bool,
+    output_schema: Mapping[str, Any] | bool | None = None,
+    execution: ToolExecution | None = None,
+    risk: ToolRisk | None = None,
+) -> Callable[[ToolFunction], FunctionTool]:
+    """Create a `FunctionTool` while keeping schemas and policies explicit."""
+
+    tool_execution = ToolExecution() if execution is None else execution
+    tool_risk = ToolRisk() if risk is None else risk
+    spec = ToolSpec(
+        name,
+        description,
+        input_schema,
+        output_schema,
+        tool_execution,
+        tool_risk,
+    )
+
+    def decorate(function: ToolFunction) -> FunctionTool:
+        return FunctionTool(spec, function)
+
+    return decorate

jharness_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: jharness-toolkit
+Version: 0.1.0
+Summary: JHarness tool registry, validation helpers, and execution decorators
+Project-URL: Documentation, https://github.com/Ezio2000/jharness-python/tree/main/docs
+Project-URL: Homepage, https://github.com/Ezio2000/jharness-python
+Project-URL: Issues, https://github.com/Ezio2000/jharness-python/issues
+Project-URL: Repository, https://github.com/Ezio2000/jharness-python.git
+Author: JHarness contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,json-schema,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jharness-kernel<0.2.0,>=0.1.0
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: referencing>=0.35.0
+Description-Content-Type: text/markdown
+
+# jharness-toolkit
+
+`jharness-toolkit` is the concrete Python tool-support distribution for
+`jharness.kernel`. It provides an immutable tool registry, JSON Schema
+validation, async function adapters, and retry and circuit-breaking decorators.
+
+```bash
+uv add jharness-toolkit
+```
+
+```python
+from jharness.toolkit import ToolRegistry, function_tool
+```
+
+Runtime semantics and portable tool values remain in `jharness.kernel`;
+`jharness.toolkit` only implements concrete adaptation and execution policies. See the
+[tool protocol](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/tool-protocol.md) and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jharness/toolkit/__init__.py,sha256=EgIpaFhh-JHW_xvId52bCgvMOoAKCFMLh_4yDpVmaV4,429
+jharness/toolkit/decorators.py,sha256=KB7TzP4DJtZ7x2BSf4AmugV6id1KkuCkgmu6cVhP8dQ,2590
+jharness/toolkit/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+jharness/toolkit/registry.py,sha256=FX0YH4j-fFdlVU5EJtalvmj8SI-4GXT4768-U0tFsVo,6029
+jharness/toolkit/tool.py,sha256=FGfBqzBCSzEj4ktar9yqBnKpyxszbDLhRRctWSyH6jI,2098
+jharness_toolkit-0.1.0.dist-info/METADATA,sha256=Hi6DkclC0AcUtAAAqr7QGxVDov2wibZmiI_Wj8aXQ8A,1929
+jharness_toolkit-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+jharness_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=XzIWNbzi6XETaKrN27-ExGMZwjoAMDNssS8g_F-Dcv8,1079
+jharness_toolkit-0.1.0.dist-info/RECORD,,

jharness_toolkit-0.1.0.dist-info/WHEEL

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

jharness_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
++MIT License
+
+Copyright (c) 2026 JHarness contributors
+
+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.