Metadata-Version: 2.4
Name: causentra
Version: 0.1.0a1
Summary: Privacy-first, framework-neutral runtime telemetry for Python AI agents
Author: Causentra contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/smartbytecoder/causentra
Project-URL: Documentation, https://github.com/smartbytecoder/causentra/tree/main/docs
Project-URL: Repository, https://github.com/smartbytecoder/causentra
Project-URL: Issues, https://github.com/smartbytecoder/causentra/issues
Keywords: ai-agents,agent-observability,multi-agent,tracing,opentelemetry,otlp,langgraph,openai-agents,crewai,local-first
Classifier: Development Status :: 3 - Alpha
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: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: openai-agents
Requires-Dist: openai-agents<0.19,>=0.18; extra == "openai-agents"
Provides-Extra: langgraph
Requires-Dist: langchain-core<1.5,>=1.4; extra == "langgraph"
Requires-Dist: langgraph<1.3,>=1.2; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai<1.16,>=1.15.3; extra == "crewai"
Provides-Extra: google-adk
Requires-Dist: google-adk<2.5,>=2.4; extra == "google-adk"
Provides-Extra: semantic-kernel
Requires-Dist: semantic-kernel<1.45,>=1.44; extra == "semantic-kernel"
Provides-Extra: autogen
Requires-Dist: autogen-agentchat<0.8,>=0.7.5; extra == "autogen"
Requires-Dist: autogen-core<0.8,>=0.7.5; extra == "autogen"
Requires-Dist: opentelemetry-api<2,>=1.30; extra == "autogen"
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == "autogen"
Provides-Extra: frameworks
Requires-Dist: openai-agents<0.19,>=0.18; extra == "frameworks"
Requires-Dist: langchain-core<1.5,>=1.4; extra == "frameworks"
Requires-Dist: langgraph<1.3,>=1.2; extra == "frameworks"
Requires-Dist: crewai<1.16,>=1.15.3; extra == "frameworks"
Requires-Dist: google-adk<2.5,>=2.4; extra == "frameworks"
Requires-Dist: semantic-kernel<1.45,>=1.44; extra == "frameworks"
Requires-Dist: autogen-agentchat<0.8,>=0.7.5; extra == "frameworks"
Requires-Dist: autogen-core<0.8,>=0.7.5; extra == "frameworks"
Requires-Dist: opentelemetry-api<2,>=1.30; extra == "frameworks"
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == "frameworks"
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2,>=1.30; extra == "otel"
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30; extra == "otel"
Provides-Extra: kafka
Requires-Dist: confluent-kafka<3,>=2.12; extra == "kafka"
Provides-Extra: nats
Requires-Dist: nats-py<3,>=2.10; extra == "nats"
Provides-Extra: redis
Requires-Dist: redis<9,>=6; extra == "redis"
Provides-Extra: mqtt
Requires-Dist: paho-mqtt<3,>=2.1; extra == "mqtt"
Provides-Extra: websocket
Requires-Dist: websockets<16,>=14; extra == "websocket"
Provides-Extra: transports
Requires-Dist: confluent-kafka<3,>=2.12; extra == "transports"
Requires-Dist: nats-py<3,>=2.10; extra == "transports"
Requires-Dist: redis<9,>=6; extra == "transports"
Requires-Dist: paho-mqtt<3,>=2.1; extra == "transports"
Requires-Dist: websockets<16,>=14; extra == "transports"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
Requires-Dist: mypy<2,>=1.15; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Provides-Extra: security
Requires-Dist: bandit<2,>=1.9; extra == "security"
Requires-Dist: pip-audit<3,>=2.10; extra == "security"
Dynamic: license-file

# 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.

```python
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:

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

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:

```python
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](../docs/17-integration-guide.md). 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:

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

See the [provider support contract](../docs/23-provider-support.md) for exact extraction and compatibility guarantees.

Durable delivery and processing:

```python
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:

```bash
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 [production runtime](../docs/24-production-python-runtime.md) and [transport/plugin operations](../docs/25-transport-plugin-operations.md).

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

The source is a release candidate. Strict typing/lint, deterministic tests, exact-framework registration, clean-wheel, collector, durable transport, and package verification gates are implemented. Independent security review and target-infrastructure load/soak evidence remain release gates.
