Metadata-Version: 2.4
Name: tracectrl-enterprise
Version: 0.1.0
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: tracectrl<0.4,>=0.3
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
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. Thin wrapper over the OSS [`tracectrl`](https://pypi.org/project/tracectrl/)
package — `tracectrl` does the OpenTelemetry SDK heavy lifting; this package
adds enterprise-specific defaults (collector endpoint, required ingest-key
auth, fail-loud behaviour) and the `tag_agent()` API for self-identifying
agent spans.

## Install

```bash
pip install tracectrl-enterprise
```

## Quickstart

```python
import os
from tracectrl_enterprise import configure, tag_agent

configure(ingest_key=os.environ["TRACECTRL_INGEST_KEY"])

@tag_agent(
    id="payment-bot",
    name="PaymentAgent",
    framework="strands",  # framework you're running on; informational
    role="payment_processing",
)
def run_payment(query: str) -> str:
    # ... your agent logic ...
    return "ok"
```

Every call to `run_payment` creates an OpenTelemetry span with the canonical
TraceCtrl attributes (`openinference.span.kind=AGENT`,
`tracectrl.agent.id`, `tracectrl.agent.name`, etc.), exported via OTLP/gRPC
with `Authorization: Bearer <ingest_key>` to your TraceCtrl Enterprise
collector. The collector resolves your ingest key to a tenant and stamps
`tracectrl.tenant_id` on every span — your SDK doesn't (and can't) set
tenancy itself; the collector is the trust boundary.

## Configuration

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

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

If you call `configure()` without an `ingest_key` argument, it reads
`TRACECTRL_INGEST_KEY` from the environment. If neither is set, it raises
`ValueError` — unlike the OSS SDK which can be configured to fail silently,
enterprise installs always fail loud on missing auth.

## Framework instrumentation

For automatic tracing of supported frameworks (Strands, etc.), install the OSS
instrumentor package alongside this one:

```bash
pip install tracectrl-instrumentation-strands
```

The instrumentor hooks into the same global OpenTelemetry TracerProvider that
`tracectrl-enterprise.configure()` sets up, so spans from instrumented
framework calls are exported the same way as your `@tag_agent`-decorated
functions.

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