pisama-core 1.7.0

Core detection, scoring, and healing engine for Pisama agent forensics

pisama-core

Detection, scoring, and healing engine for AI agent systems. Detect failure modes like infinite loops, hallucinations, cost overruns, and coordination breakdowns in your LLM agents -- entirely offline, no API keys required.

Part of the Pisama platform for multi-agent failure detection.

Install

pip install pisama-core

Quick Start

import asyncio
from pisama_core import Trace, SpanKind, DetectionOrchestrator

# Build a trace from your agent's execution
trace = Trace()
for i in range(8):
    trace.create_span(name="Read", kind=SpanKind.TOOL)

# Run all built-in detectors
orchestrator = DetectionOrchestrator()
result = asyncio.run(orchestrator.analyze(trace))

for detection in result.detections:
    print(f"[{detection.detector_name}] {detection.summary}")
    print(f"  Severity: {detection.severity}/100")
    print(f"  Fix: {detection.fix_recommendation.instruction}")

Output:

[loop] Tool 'Read' repeated 8x consecutively
  Severity: 45/100
  Fix: Stop the current loop. Try a different approach or ask the user for guidance.

No API key. Detector runs are local — your traces never leave the process. The package sends a single anonymous install ping on first use; see Telemetry below.

Built-in Detectors

Detector	What it catches
Loop	Consecutive repetitions, cyclic patterns (A->B->A->B), low tool diversity
Repetition	Similar actions with slight variations, tool dominance
Cost	Token budget overruns, excessive LLM/tool calls
Hallucination	Failed file operations, error rate spikes
Coordination	Message storms, agent imbalance, handoff loops

All detectors support both batch analysis (full trace) and real-time hooks (per-span).

Use Individual Detectors

import asyncio
from pisama_core import Trace, SpanKind
from pisama_core.detection.detectors.loop import LoopDetector
from pisama_core.detection.detectors.cost import CostDetector

trace = Trace()
# ... add spans representing your agent's execution

loop = LoopDetector()
cost = CostDetector()

loop_result = asyncio.run(loop.detect(trace))
cost_result = asyncio.run(cost.detect(trace))

if loop_result.detected:
    print(f"Loop detected: {loop_result.summary}")

Write Your Own Detector

from pisama_core import BaseDetector, DetectionResult, Trace
from pisama_core.detection.result import FixType

class MyDetector(BaseDetector):
    name = "my_detector"
    description = "Detects my custom failure pattern"
    version = "0.1.0"

    async def detect(self, trace: Trace) -> DetectionResult:
        # Your detection logic here
        tool_names = trace.get_tool_sequence()
        if len(set(tool_names)) == 1 and len(tool_names) > 5:
            return DetectionResult.issue_found(
                detector_name=self.name,
                severity=50,
                summary="Agent is stuck using a single tool",
                fix_type=FixType.SWITCH_STRATEGY,
                fix_instruction="Try a different approach",
            )
        return DetectionResult.no_issue(self.name)

Register it so the orchestrator picks it up:

from pisama_core import registry
registry.register(MyDetector())

Core Concepts

• Trace -- A complete agent execution session containing multiple spans
• Span -- A single unit of work (tool call, LLM inference, agent turn) with kind, timing, and optional I/O data
• DetectionResult -- Detector output: issue found (yes/no), severity (0-100), evidence, fix recommendation
• DetectorRegistry -- Plugin system for registering detectors (built-ins auto-register on import)
• DetectionOrchestrator -- Runs all registered detectors and aggregates results

Platform Support

Traces are framework-agnostic. Set platform for platform-aware threshold tuning:

from pisama_core import Trace, TraceMetadata, Platform

trace = Trace(metadata=TraceMetadata(platform=Platform.LANGGRAPH))

Works with Claude Agent SDK, LangGraph, AutoGen, CrewAI, n8n, Dify, and custom agents.

Pisama Platform

For production monitoring with 25+ calibrated detectors, ML-based detection, LLM-as-judge verification, and a dashboard, see pisama.ai.

Telemetry

Starting in 1.7.0, pisama-core sends a single anonymous install ping the first time you instantiate DetectionOrchestrator in a process. This helps us understand which Python versions, operating systems, and runtime environments to support. The first run prints a one-line consent notice to stderr.

What is sent (one HTTP POST to https://api.pisama.ai/api/v1/telemetry/install):

Field	Example
install_id	locally-generated UUID4, persisted at ~/.pisama/install_id
sdk_version	1.7.0
python	3.12.3
os	Darwin, Linux, Windows
os_release	25.2.0 (truncated to 64 chars)
runtime_env	github_actions, aws_lambda, vercel, fly, modal, kubernetes, docker, local, etc.
event	first_run once, session thereafter

What is NOT sent: trace contents, detector outputs, file paths, environment variables, hostnames, IPs (the server discards them on receipt), API keys, or user identifiers.

How to disable (any one of these works, before or after install):

export PISAMA_TELEMETRY=0           # also: false / no / off / empty
export DO_NOT_TRACK=1               # consoledonottrack.com convention
touch ~/.pisama/telemetry_disabled  # opt-out file

Or programmatically, anywhere in your code:

import pisama_core
pisama_core.disable_telemetry()

The implementation is a single ~150-line file: src/pisama_core/utils/_telemetry.py. Stdlib-only, daemon-thread send, 2-second timeout, swallows all exceptions — telemetry can never block, slow down, or crash your process.

License

MIT