Skip to content

OSS vs Cloud

Pisama is open-source first. pip install pisama gives you 20 heuristic detectors that run fully offline with zero network calls at zero cost. The Cloud platform adds ML-based detection, a dashboard, self-healing, and team features.

Comparison

Capability OSS (pip install pisama) Cloud (platform)
Detectors 20 core heuristic 44 (20 core + 24 platform-specific)
Detection method Pattern matching, state analysis Heuristic + embeddings + LLM judge
Cost per trace $0.00 ~$0.02--0.05 (tiered escalation)
Network calls None API calls to Pisama backend
Dashboard -- Web UI with trace waterfall, flow graph, analytics
Self-healing Recommendations only Fix generation, approval workflows, rollback
Multi-tenancy -- Tenant isolation, API keys, JWT auth
Team features -- Shared dashboard, detection feedback, audit log
Alerting -- Webhooks, integration callbacks
Custom detectors Register locally Register + calibrate with golden datasets
Frameworks All (via trace dict) All + native n8n, LangGraph, Dify, OpenClaw, Claude Managed Agents adapters
License MIT MIT (source available, cloud-hosted)

Packages

All packages are MIT licensed and published to PyPI.

Package Purpose Install
pisama High-level SDK + CLI. The main entry point. pip install pisama
pisama-core Core detection engine, 20 detectors, scoring, healing models. Dependency of pisama. pip install pisama-core
pisama-agent-sdk Claude Agent SDK hooks for real-time failure prevention. pip install pisama-agent-sdk
pisama-claude-code Claude Code integration (MCP tools, session capture). pip install pisama-claude-code

OSS path

Everything you need for offline failure detection:

pip install pisama

import pisama

result = pisama.analyze("trace.json")
for issue in result.issues:
    print(f"[{issue.type}] {issue.summary}")

What you get:

  • 20 detectors covering loops, hallucination, injection, corruption, coordination failures, and more
  • CLI for command-line analysis (pisama analyze, pisama watch, pisama detectors)
  • MCP server for Cursor and Claude Desktop integration
  • Custom detector API -- extend with your own BaseDetector subclasses
  • Framework-agnostic -- pass any trace as a file, JSON string, or Python dict
  • Zero dependencies on external services -- no API keys, no database, no Docker

See the SDK Quickstart for a complete walkthrough.

Cloud path

The Cloud platform adds production monitoring capabilities on top of the OSS core.

Self-hosted

git clone https://github.com/tn-pisama/pisama.git
cd pisama
docker compose up

This starts PostgreSQL (pgvector), Redis, the FastAPI backend (port 8000), and the Next.js dashboard (port 3000). See the Docker Compose guide for details.

What the platform adds

  • ML-based detection -- Trained models and LLM-as-Judge verification for higher accuracy on ambiguous cases
  • Tiered escalation -- Start at Tier 1 (hash, $0.00), escalate through embeddings and LLM only when needed
  • Dashboard -- Trace waterfall timelines, flow graphs, detection drill-down, cost analytics
  • Self-healing -- AI-generated fixes with approval workflows and automatic rollback
  • Framework adapters -- Native webhook integrations for n8n, LangGraph, Dify, and OpenClaw
  • OTEL ingestion -- Direct OpenTelemetry trace ingestion with gen_ai.* semantic conventions
  • Feedback loop -- Mark detections as valid or false positive to improve accuracy over time
  • Multi-tenancy -- Isolated tenants with API key authentication

Feature flags (self-hosted)

Enterprise features are controlled by feature flags in your environment:

Flag What it enables
FEATURE_ML_DETECTION ML detector, tiered escalation, LLM judge
FEATURE_ADVANCED_EVALS Quality gates, retrieval quality, role usurpation

Without these flags, the self-hosted platform uses the same 20 heuristic detectors as the OSS packages, plus the dashboard, storage, and API.

When to use which

Scenario Recommendation
Evaluating Pisama OSS -- pip install pisama and try analyze() in 2 minutes
CI/CD pipeline checks OSS -- Run pisama analyze or call analyze() in pytest
Local development OSS -- Analyze traces during development, no infrastructure needed
MCP integration OSS -- pisama mcp-server works standalone
Production monitoring Cloud -- Dashboard, alerting, historical analysis
Team visibility Cloud -- Shared dashboard, detection feedback
High-accuracy detection Cloud -- ML + LLM judge tiers improve precision on edge cases
Automated remediation Cloud -- Self-healing with approval workflows
Custom detector calibration Cloud -- Golden datasets, F1 benchmarking, threshold tuning

Migrating from OSS to Cloud

The OSS and Cloud versions use the same detection engine. Migrating is additive:

  1. Keep using pisama.analyze() for local/CI checks
  2. Add OTEL export or webhook integration to send traces to the platform
  3. Use the dashboard for monitoring and the API for programmatic access

No code changes needed in your agent -- just add a trace exporter alongside your existing setup.