Metadata-Version: 2.4
Name: agent-hooks-sdk
Version: 0.1.0a1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: jsonschema>=4.21 ; extra == 'ctk'
Requires-Dist: pytest>=7.4 ; extra == 'ctk'
Requires-Dist: agent-hooks-sdk[ctk] ; extra == 'dev'
Requires-Dist: mypy>=1.8 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2.0 ; extra == 'dev'
Provides-Extra: ctk
Provides-Extra: dev
Summary: Framework-neutral agent control contract: interception points, agent context, verdict, and conformance test kit. Python wrapper over the canonical Rust core.
Keywords: ai-agents,governance,interception,control,conformance
Author-email: Responsible AI <responsibleai@microsoft.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/responsibleai/agent-hooks
Project-URL: Specification, https://github.com/responsibleai/agent-hooks/blob/main/spec/AGENT-HOOKS-0.1.md

# agent-hooks (Python SDK)

Python implementation of [AGENT-HOOKS-0.1](../../spec/AGENT-HOOKS-0.1.md):
interception-point enums, `AgentContext` builder, `Verdict` types, host-side
`InterceptionEmitter`, and the Conformance Test Kit.

```bash
# Not yet on PyPI (the name "agent-hooks" is held by an unrelated
# project; the distribution is named agent-hooks-sdk). Install from source:
pip install "agent-hooks-sdk @ git+https://github.com/responsibleai/agent-hooks#subdirectory=sdk/python"
```

## Host (framework adapter) usage

```python
from agent_hooks import AgentContextBuilder, InterceptionEmitter, InterceptionBlocked

builder = AgentContextBuilder(agent_id="...", framework="my-fw", session_id="...")
emitter = InterceptionEmitter().register(my_consumer)

await emitter.emit(builder.agent_startup(tools_registered=[...]))
ctx = builder.pre_tool_call(call_id="tc-1", name="http_get", args={"url": u})
try:
    await emitter.emit(ctx)
except InterceptionBlocked as e:
    return tool_error(e.result.verdict.reason)
result = invoke_tool(ctx["tool_call"]["args"])  # post-transform args
```

## Interceptor usage

```python
from agent_hooks import Interceptor, AgentContext, Verdict, Decision

class MyPolicy:
    def intercept(self, ctx: AgentContext) -> Verdict:
        if ctx["interception_point"] == "pre_tool_call" and ctx["tool_call"]["name"] == "rm":
            return Verdict(Decision.DENY, reason="dangerous")
        return Verdict.ALLOW
```

## Running the CTK against your framework

Implement `agent_hooks.ctk.Harness` (see `conformance/HARNESS.md`), then:

```bash
pytest --agent-hooks-harness=my_pkg:MyHarness \
       --agent-hooks-vectors=path/to/conformance/vectors
```

