Metadata-Version: 2.4
Name: pisama
Version: 0.6.2
Summary: Multi-agent failure detection for production AI systems
Project-URL: Homepage, https://pisama.ai
Project-URL: Documentation, https://docs.pisama.ai
Project-URL: Repository, https://github.com/Pisama-AI/pisama-python
Project-URL: Issues, https://github.com/Pisama-AI/pisama-python/issues
Project-URL: Changelog, https://github.com/Pisama-AI/pisama-python/blob/main/CHANGELOG.md
Author-email: Pisama Team <team@pisama.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,failure-detection,monitoring,multi-agent,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: pisama-core<2,>=1.8.2
Requires-Dist: rich>=13.0
Provides-Extra: agents
Requires-Dist: httpx>=0.24; extra == 'agents'
Provides-Extra: auto
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'auto'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'auto'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'auto'
Requires-Dist: wrapt>=1.15.0; extra == 'auto'
Provides-Extra: dev
Requires-Dist: anthropic>=0.40; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openai>=1.50; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Provides-Extra: telemetry
Requires-Dist: posthog>=3.0; extra == 'telemetry'
Description-Content-Type: text/markdown

# Pisama

**Find and fix failures in AI agent systems. No LLM calls required.**

[![PyPI](https://img.shields.io/pypi/v/pisama?color=blue)](https://pypi.org/project/pisama/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Pisama ships heuristic detectors that apply across frameworks including n8n, LangGraph, Dify and OpenClaw, with per-platform gating (for example `coordination` runs only on multi-agent platforms). They run locally with zero LLM cost on the heuristic tier.

## Install

```bash
pip install pisama
```

## Usage

```python
from pisama import analyze

result = analyze("trace.json")  # also accepts dicts and JSON strings

for issue in result.issues:
    print(f"[{issue.type}] {issue.summary} (severity: {issue.severity})")
    print(f"  Fix: {issue.recommendation}")
```

## CLI

```bash
pisama analyze trace.json          # Analyze a trace
pisama watch python my_agent.py    # Watch a live agent (pip install "pisama[auto]")
pisama replay <trace-id>           # Re-run detection on stored traces
pisama smoke-test --last 50        # Batch test recent traces
pisama detectors                   # List all core detectors
pisama mcp-server                  # Start MCP server (pip install pisama[mcp])
```

## MCP Server

Works in Cursor, Claude Desktop, and Windsurf. No API key is needed:

```json
{
  "mcpServers": {
    "pisama": { "command": "pisama", "args": ["mcp-server"] }
  }
}
```

## Optional extras

The base `pisama` install has zero-cost heuristic detection covered. Two extras
add opt-in functionality on top.

### Auto-instrumentation: `pisama[auto]`

Zero-code tracing for LLM calls. `init()` patches supported clients (Anthropic,
OpenAI) so every call after it emits an OTEL trace Pisama can analyze, no
manual instrumentation needed.

```bash
pip install "pisama[auto]"
```

```python
import pisama.auto

pisama.auto.init(api_key="ps_...")

# All subsequent LLM calls are automatically traced
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(...)  # traced automatically
```

This used to require the standalone `pisama-auto` package. That package still
works and stays fully supported for existing installs; `pisama[auto]` is the
same code, folded into the base package so there is one less dependency to
track. New projects should install it this way.

### Agent hooks and tools: `pisama[agents]`

Real-time hooks, tools, and self-check utilities for agent runtimes (built for
the Claude Agent SDK), wired to Pisama's detection infrastructure for
in-loop failure prevention rather than after-the-fact analysis.

```bash
pip install "pisama[agents]"
```

```python
from pisama.agents 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
```

Active self-check is available the same way:

```python
from pisama.agents 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"]:
    ...  # revise output based on result["issues"]
```

This used to require the standalone `pisama-agent-sdk` package. That package
still works and stays fully supported for existing installs; `pisama[agents]`
is the recommended path for new projects, one package instead of two.

## Detectors

Core detectors, gated per platform (n8n, LangGraph, Dify, OpenClaw and others). A representative selection:

| Detector | What It Catches |
|----------|----------------|
| `loop` | Infinite loops, retry storms, stuck patterns |
| `coordination` | Deadlocked handoffs, message storms |
| `hallucination` | Factual errors, fabricated tool results |
| `injection` | Prompt injection, jailbreak attempts |
| `corruption` | State corruption, type drift |
| `persona_drift` | Persona drift, role confusion |
| `derailment` | Task deviation, goal drift |
| `context` | Context neglect, ignored instructions |
| `specification` | Output vs. requirement mismatch |
| `communication` | Inter-agent message breakdown |
| `decomposition` | Poor task breakdown, circular dependencies |
| `workflow` | Unreachable nodes, missing error handling |
| `completion` | Premature completion, unfinished work |
| `withholding` | Suppressed findings, hidden errors |
| `convergence` | Metric plateau, regression, thrashing |
| `overflow` | Context window exhaustion |
| `propagation` | Silent error propagation across steps |
| `citation` | Fabricated citations and source misattribution |
| `routing` | Inputs misrouted to the wrong specialist agent |
| `mcp_protocol` | MCP tool-communication failures |

## Links

- [Documentation](https://docs.pisama.ai)
- [GitHub](https://github.com/Pisama-AI/pisama-python)
- [Platform](https://pisama.ai)

## License

MIT

## Source boundary

This repository is the public source for the MIT-licensed `pisama` Python
package. It does not contain the Pisama Cloud backend, dashboard, calibration
data, managed detection tiers, or paid automation.
