Metadata-Version: 2.4
Name: tracectrl-enterprise
Version: 0.2.3
Summary: TraceCtrl Enterprise SDK — agentic AI security observability for the enterprise platform
Project-URL: Homepage, https://tracectrl.ai
Project-URL: Repository, https://github.com/tracectrl/tracectrl-enterprise
Project-URL: Documentation, https://github.com/tracectrl/tracectrl-enterprise/blob/main/sdk/tracectrl-enterprise/README.md
Author: CloudsineAI
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,observability,opentelemetry,security
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Provides-Extra: agno
Requires-Dist: openinference-instrumentation-agno>=0.1.0; extra == 'agno'
Provides-Extra: all
Requires-Dist: openinference-instrumentation-agno>=0.1.0; extra == 'all'
Requires-Dist: openinference-instrumentation-crewai>=0.1.0; extra == 'all'
Requires-Dist: openinference-instrumentation-google-adk>=0.1.0; extra == 'all'
Requires-Dist: openinference-instrumentation-langchain>=0.1.0; extra == 'all'
Requires-Dist: openinference-instrumentation-strands-agents>=0.1.0; extra == 'all'
Provides-Extra: crewai
Requires-Dist: openinference-instrumentation-crewai>=0.1.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: google-adk
Requires-Dist: openinference-instrumentation-google-adk>=0.1.0; extra == 'google-adk'
Provides-Extra: langchain
Requires-Dist: openinference-instrumentation-langchain>=0.1.0; extra == 'langchain'
Provides-Extra: strands
Requires-Dist: openinference-instrumentation-strands-agents>=0.1.0; extra == 'strands'
Description-Content-Type: text/markdown

# tracectrl-enterprise

TraceCtrl Enterprise SDK — instrument your agentic AI application to send traces
to a TraceCtrl Enterprise deployment.

Apache 2.0 licensed. Built directly on [OpenTelemetry](https://opentelemetry.io/) and
[OpenInference](https://github.com/Arize-ai/openinference) — self-contained, with no other
TraceCtrl runtime dependency. Adds enterprise-specific defaults (collector endpoint, required
ingest-key auth, fail-loud behaviour) plus `configure()`, `instrument()`, and `track()` for
**deterministic, source-declared agent identity**.

## Install

```bash
pip install "tracectrl-enterprise[strands]"   # or [agno], [langchain], [crewai], [google-adk], [all]
```

The framework extras pull the matching OpenInference instrumentor. The base package
(`pip install tracectrl-enterprise`, just OpenTelemetry) is enough if you only use
`configure()` + `track()` without framework auto-instrumentation.

## Quickstart

```python
import os
from tracectrl_enterprise import configure, instrument, track

configure(ingest_key=os.environ["TRACECTRL_INGEST_KEY"])  # auth + endpoint
instrument("strands")                                      # framework auto-instrumentation

from strands import Agent
agent = track(Agent(name="PaymentAgent", system_prompt="..."))  # declare identity once

agent("refund order 123")   # every invocation is now a clean AGENT span
```

Three calls:

1. **`configure(ingest_key=...)`** — initialise the OTLP pipeline against your
   collector (required ingest key; fails loud if missing).
2. **`instrument(framework)`** — activate OpenInference auto-instrumentation for
   your framework (`"strands"`, `"agno"`, `"langchain"`, `"crewai"`,
   `"google-adk"`, a list, or `"auto"` to pick up whatever's installed), plus the
   enterprise enrichment processors.
3. **`track(agent)`** — wrap an agent object once. `track` reads the agent's
   `name` and system prompt automatically and stamps the canonical
   `openinference.span.kind=AGENT` + `tracectrl.agent.{id,name,framework}`
   (and `role`/`system_prompt` when available) **at the source** — so the
   platform never has to guess agent identity from span names. Returns the same
   agent (chainable).

Override any field explicitly when the defaults aren't right (notably for
LangChain/CrewAI/Google ADK, whose agents don't self-describe):

```python
agent = track(my_chain, id="invoice-extractor", name="InvoiceExtractor",
              framework="langchain", role="document_extraction")
```

For multi-turn flows, group traces with the session helpers:

```python
from tracectrl_enterprise import new_session
new_session()   # or set_session_id("<your conversation id>")
```

Mark externally-triggered entry points with the `ingress` decorator so the
platform records how a run was triggered:

```python
from tracectrl_enterprise import ingress

@ingress(trigger_type="email")
def handle_inbound(msg): ...
```

## Tenancy is set by the collector, never the SDK

Spans export over OTLP/gRPC with `Authorization: Bearer <ingest_key>`. The
collector resolves your ingest key to a tenant and stamps `tracectrl.tenant_id`
on every span — your app can't (and shouldn't) set tenancy itself; the collector
is the trust boundary.

## Configuration

`configure(ingest_key=..., endpoint=..., service_name=...)`:

| Argument | Env var | Default | Required |
|---|---|---|---|
| `ingest_key` | `TRACECTRL_INGEST_KEY` | — | **yes** — fails loud if not set |
| `endpoint` | `TRACECTRL_ENDPOINT` | `https://app.tracectrl.ai/ingest` | no |
| `service_name` | `TRACECTRL_SERVICE_NAME` | `tracectrl-agent` | no |

## Migrating from 0.1.x

0.1.x exposed a `tag_agent(id=, name=, framework=)` decorator placed on each agent
invocation. It has been **removed** in favour of `track()`, which reads identity
off the agent object, captures the system prompt, and composes with the framework
instrumentors. Replace `@tag_agent(id="x", name="X", framework="f")` on a function
with `agent = track(my_agent, ...)` on the agent object.

## License

Apache 2.0. The TraceCtrl Enterprise server-side platform (engine, collector,
UI) is BUSL-licensed; the SDK is permissively licensed so it can be embedded in
your proprietary code without restriction.

## Reporting issues

https://github.com/tracectrl/tracectrl-enterprise/issues
