Metadata-Version: 2.4
Name: pisama-agent-sdk
Version: 0.4.0
Summary: ATIF trace adapters and real-time failure hooks for agent runtimes (thin shim onto pisama.agents)
Project-URL: Homepage, https://pisama.ai
Project-URL: Documentation, https://docs.pisama.ai/agent-sdk
Project-URL: Repository, https://github.com/Pisama-AI/pisama-agent-sdk
Project-URL: Issues, https://github.com/Pisama-AI/pisama-agent-sdk/issues
Project-URL: Changelog, https://github.com/Pisama-AI/pisama-agent-sdk/blob/main/CHANGELOG.md
Author-email: Pisama Team <team@pisama.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,claude,detection,hooks,pisama,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: pisama>=0.6.0
Provides-Extra: dev
Requires-Dist: build>=1.5; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.16; extra == 'dev'
Requires-Dist: twine>=6.2; extra == 'dev'
Provides-Extra: evaluator
Requires-Dist: httpx>=0.24; extra == 'evaluator'
Provides-Extra: telemetry
Requires-Dist: posthog>=3.0; extra == 'telemetry'
Description-Content-Type: text/markdown

# pisama-agent-sdk

[![PyPI version](https://img.shields.io/pypi/v/pisama-agent-sdk.svg)](https://pypi.org/project/pisama-agent-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/pisama-agent-sdk.svg)](https://pypi.org/project/pisama-agent-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/Pisama-AI/pisama-agent-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Pisama-AI/pisama-agent-sdk/actions/workflows/ci.yml)
[![Downloads](https://img.shields.io/pypi/dm/pisama-agent-sdk)](https://pypistats.org/packages/pisama-agent-sdk)

ATIF trace adapters and real-time failure detection hooks for agent runtimes,
including the
[Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python),
OpenHands, and Harbor-compatible evaluation flows.

Part of the [Pisama](https://pisama.ai) platform for single-agent, multi-agent, and sub-agent failure detection.

Requires Python 3.10 or newer. Python 3.10 through 3.13 are tested.

> **As of 0.4.0**, this package is a thin, permanent compatibility shim.
> The implementation now lives in `pisama.agents` (part of the
> [`pisama`](https://pypi.org/project/pisama/) base package, installed
> automatically as a dependency); every module here re-exports its
> `pisama.agents` equivalent under the original import path. Every API
> below works exactly as documented, unchanged. New features and fixes
> land in `pisama.agents`, not here.

## Install

```bash
pip install pisama-agent-sdk
```

## Quick Start

### Passive Monitoring (hooks)

Add two lines to your Claude Agent SDK setup:

```python
from pisama_agent_sdk import pre_tool_use_hook, post_tool_use_hook

agent.hooks.pre_tool_use = pre_tool_use_hook
agent.hooks.post_tool_use = post_tool_use_hook
```

Every tool call is now checked for failure patterns in real-time (<100ms). If a loop or other issue is detected, the hook returns a blocking signal to stop the agent.

### Active Self-Check

Let the agent verify its own output:

```python
from pisama_agent_sdk import check

result = await check(
    output="The server is healthy based on the metrics.",
    context={"query": "Is auth-service down?", "sources": [...]},
)
if not result["passed"]:
    # result["issues"] describes what went wrong
    print(result["issues"])
```

### Custom Tool for Claude Agent SDK

Give the agent a tool it can call to self-check:

```python
from pisama_agent_sdk import create_check_tool
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    custom_tools=[create_check_tool()],
)
```

## Configuration

```python
from pisama_agent_sdk import configure_bridge, BridgeConfig

configure_bridge(BridgeConfig(
    fail_open=True,           # Allow execution if detection errors (default: True)
    detection_timeout_ms=80,  # Max detection time per hook (default: 80)
))
```

## Tool Matchers

Control which tools get checked:

```python
from pisama_agent_sdk import PreToolUseHook, HookMatcher

# Only check file and shell tools
matcher = HookMatcher(
    tool_name_pattern=r"^(Read|Write|Edit|Glob|Grep|Bash|bash|shell)$"
)
hook = PreToolUseHook(matcher=matcher)
agent.hooks.pre_tool_use = hook
```

Built-in matchers: `ALL_TOOLS`, `FILE_TOOLS`, `SHELL_TOOLS`, `DANGEROUS_COMMANDS`, `AGENT_TOOLS`.

## How It Works

1. Your agent makes a tool call
2. `pre_tool_use_hook` converts the call into a Pisama `Span`
3. Registered detectors run against the span + recent session context
4. If a failure is detected (e.g., 5th consecutive `Read` of the same file), the hook returns a blocking result
5. The agent receives the block signal and adjusts its behavior

Detection runs entirely locally using `pisama-core` detectors. No network calls unless you configure a remote endpoint.

## Evaluator Mode

Use Pisama as an evaluator in multi-agent harnesses:

```python
from pisama_agent_sdk import PisamaEvaluator

evaluator = PisamaEvaluator(endpoint="https://your-pisama-instance/api/v1")
result = await evaluator.evaluate(trace_data)
print(result.passed, result.failures)
```

Requires `pip install pisama-agent-sdk[evaluator]`.

## License

MIT
