Causentra for Python

Python-first instrumentation, durable event delivery, processing, and authenticated collection for multi-agent applications. Every component uses the portable RuntimeEvent 1.0 contract.

Install

Causentra is published on PyPI for Python 3.10 and later. Install the stable 1.0.0 release with:

python -m pip install causentra

Add only the framework extras your application uses:

python -m pip install "causentra[openai-agents,langgraph]"

For contributor development from this repository, use the editable source installation instead:

python -m pip install -e ".[dev,openai-agents,langgraph]"

The optional signing prerequisite is installed separately when needed:

python -m pip install -e ".[dev,signing]"

causentra[signing] declares the bounded rfc8785>=0.1.4,<0.2 range and exposes canonicalize_json for RFC 8785 UTF-8 bytes, detached ECDSA signing, and collector signature verification. Review the dependency, golden vectors, key management, and security posture before using it in production.

from causentra import CausentraRuntime, HttpBatchExporter

runtime = CausentraRuntime(
    service_name="support-agents",
    exporter=HttpBatchExporter(),
)

with runtime.trace("resolve-ticket"):
    with runtime.agent("triage"):
        with runtime.model("classify", provider_name="anthropic", request_model="model-id"):
            call_model()
    with runtime.handoff("triage", "billing"):
        with runtime.tool("lookup-account"):
            lookup_account()

runtime.shutdown()

Maintained native adapters cover OpenAI Agents, LangGraph/LangChain, CrewAI, Google ADK, Semantic Kernel, and AutoGen. Install only the framework extras used by the application.

The aggregate frameworks extra exists for compatibility labs. It installs a large upstream dependency graph and is not the recommended production installation. Production environments should select named extras, lock the resolved graph, generate an SBOM, and review the current advisory evidence.

OpenAI Agents example:

from agents import add_trace_processor
from causentra.adapters.openai_agents import create_openai_agents_processor

add_trace_processor(create_openai_agents_processor("support-agents", exporter))

LangGraph uses LangGraphCallbackHandler through config={"callbacks": [handler]}. The other native registration recipes are in the integration guide. The otel extra provides OpenTelemetryEventExporter and start_otlp_exporter for standards-based pipelines.

Provider-aware call instrumentation supports eight deep integrations and all 15 canonical provider profiles:

response = runtime.call_model(
    "generate",
    lambda: client.chat.completions.create(...),
    provider_name="groq",
    request_model="model-id",
)

See the provider support contract for exact extraction and compatibility guarantees.

Durable delivery and processing:

from causentra import DurableTransportExporter, EventEngine, HttpTransport, SqliteEventSpool

exporter = DurableTransportExporter(
    SqliteEventSpool(".causentra/outbox.db"),
    HttpTransport(
        "https://collector.example/v1/events",
        headers={"Authorization": "Bearer <key>"},
    ),
)
engine = EventEngine(".causentra/events.db")
engine.subscribe("audit", audit_handler, event_types=("agent.*", "tool.*"))

The authenticated collector provides project-isolated atomic ingestion, trace query/delete, health/readiness, quotas, and operator metrics:

causentra init --config collector.json --key-output collector.key
causentra-collector --config collector.json
causentra --key-file collector.key doctor
causentra --key-file collector.key traces

The CLI keeps the raw generated key in a separate file, refuses to overwrite files, requires explicit trace-ID confirmation for deletion, and also provides consistent backup and idempotency-tombstone retention commands.

See the production deployment runbook, production runtime, and transport/plugin operations.

Prompts, outputs, tool arguments, arbitrary framework state, and error messages are not captured by default. Instrumentation failure never replaces application behavior.

Causentra 1.0.0 is the stable PyPI release. Strict typing/lint, deterministic tests, exact-framework registration, clean-wheel, collector, durable transport, and package verification gates are implemented. Production deployments still require independent security review and target-infrastructure load/soak evidence appropriate to their environment.