pisama-detectors¶

pisama-detectors is a local Python library of failure detectors. It includes specialized detector families for LangGraph, Dify, n8n, and OpenClaw under the Business Source License 1.1.

The canonical MIT entry point for general local analysis is pisama. Choose pisama-detectors when you need the specialized families or the typed detector functions documented here. The package runs locally. Installing it does not connect to Pisama Cloud or to the separate Pisama for n8n server and dashboard.

The contracts below require version 0.3.2 or newer:

python -m pip install "pisama-detectors>=0.3.2,<0.4"

Context overflow token counts¶

detect_overflow(context, output) counts every non-empty output separately from context. Pass output="" when context already includes the latest output.

Without a provider count, the detector uses a bounded offline estimate. Claude estimates use cl100k_base as a proxy, so they are not exact Anthropic token counts. Near a context limit, obtain the provider's count for the complete request represented by context and output, then pass it through the keyword-only provider_token_count argument:

from pisama_detectors import detect_overflow

context = "System: Review the release evidence carefully."
output = "Assistant: The release evidence is complete."

offline_result = detect_overflow(
    context=context,
    output=output,
    model="claude-sonnet-4-6",
)
print(offline_result.details["token_count_source"])


def detect_with_provider_count(provider_token_count: int):
    return detect_overflow(
        context=context,
        output=output,
        model="claude-sonnet-4-6",
        provider_token_count=provider_token_count,
    )

provider_token_count must be a non-negative integer. The result records details["token_count_source"] as provider or offline_estimate.

Structured grounding sources and citations¶

detect_hallucination accepts plain strings and typed HallucinationSource mappings. A structured source requires content and can also provide metadata, id, label, name, source, title, or url. Numbered citations work with plain strings. Named citations can match the structured fields.

Every citation in the output is validated. One invalid citation makes the citation check fail, even when another citation is valid.

from pisama_detectors import HallucinationSource, detect_hallucination

sources: list[HallucinationSource] = [
    {
        "content": (
            "The provider token count is optional and must be a "
            "non-negative integer."
        ),
        "title": "pisama-detectors API contract",
        "url": "https://docs.pisama.ai/detectors/",
    }
]

result = detect_hallucination(
    "The provider token count is optional "
    "(source: pisama-detectors API contract).",
    sources,
)
print(result.detected, result.confidence)

Grounding compares claims with matching source clauses. A related document is not sufficient evidence for an unsupported claim.

Framework-aware routing¶

run_all_detectors accepts framework at the top level or inside the trace mapping. Recognized values are langgraph, dify, n8n, and openclaw. When one is present, adapters for the other recognized frameworks are skipped. An omitted or unknown value preserves the legacy fanout behavior.

from pisama_detectors import run_all_detectors

n8n_trace = {
    "framework": "n8n",
    "nodes": [],
    "connections": {},
}

results = run_all_detectors(
    {
        "trace": n8n_trace,
    }
)
print(sorted(results))

Framework routing selects functions inside the local library. It does not send traces to, install, or configure the separate Pisama for n8n product.

Loop option semantics¶

detect_loop accepts window_size and similarity_threshold. In version 0.3.2, the window includes the current state. The similarity threshold must be between 0 and 1, inclusive, and is applied consistently to pairwise and clustering-based semantic checks.

See the Calibration FAQ for a tuning example and the package repository for the complete detector inventory, release notes, and benchmark evidence.