Metadata-Version: 2.4
Name: enlight-chakra-observability
Version: 0.1.0
Summary: One-line LLM observability for Python — a thin wrapper over OpenLLMetry that exports OTLP traces to Enlight Chakra.
Author: ESDS Enlight Chakra
License: Apache-2.0
Keywords: llm,observability,opentelemetry,openllmetry,tracing,otlp
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: traceloop-sdk<1.0,>=0.30
Provides-Extra: otel
Requires-Dist: traceloop-sdk<1.0,>=0.30; extra == "otel"

# enlight-chakra-observability

One-line LLM observability for Python. A thin, vendor-neutral wrapper over
[OpenLLMetry](https://github.com/traceloop/openllmetry) (Traceloop, Apache-2.0) that
exports OTLP traces to your Enlight Chakra deployment. The single `lk_…` ingest key (copied from
the Enlight Chakra **Instrument app** page) encodes the OTLP endpoint **and** auth — no base64,
no endpoint URLs, no "which key goes where".

Under the hood it's OpenLLMetry → plain OTLP. You are never locked in.

> **Naming:** the distribution is `enlight-chakra-observability` and the import name is
> `enlight_chakra_observability`. (The earlier `enlight-sdk` / `import enlight_chakra` collided with an
> unrelated PyPI package, Holoviz `lumen`. `import enlight_chakra` still works as a deprecated
> alias when this package is installed.)

## Install

```bash
# From source (works today — not yet on public PyPI):
pip install "git+https://github.com/esds/lumen.git#subdirectory=sdk/python"
#   or, from a local checkout:   pip install ./sdk/python
#   or, from the built wheel:    pip install enlight_chakra_observability-0.1.0-py3-none-any.whl

# Once published to PyPI / your private index:
pip install enlight-chakra-observability
```

## Use

```python
import enlight_chakra_observability as lumen

enlight_chakra.init(api_key="lk_...", app_name="checkout-api")   # once, at startup
enlight_chakra.identify(user_id="u_42", session_id="s_7")        # optional, per request

# your normal OpenAI / Anthropic / LangChain / LlamaIndex code is now auto-traced
```

For short scripts/demos, flush each span immediately:

```python
enlight_chakra.init(api_key="lk_...", disable_batch=True)
```

To make traces visible in a multi-tenant Enlight Chakra, stamp your tenant as a resource
attribute (pass-through to Traceloop), or set `OTEL_RESOURCE_ATTRIBUTES=tenant.id=...`:

```python
enlight_chakra.init(api_key="lk_...", resource_attributes={"tenant.id": "tnt_shiftx"})
```

## What you get

Every request becomes a nested span tree in Enlight Chakra — retrieval, prompt assembly, the
model call, tool calls, agent steps — grouped by user and session. See it under
**Span Explorer**, **RAG & Retrieval**, **Agents & Tools**, and **Sessions**.

## The `lk_` key

`lk_<base64url(endpoint|public_key|secret_key)>`. It packs the OTLP endpoint and your
project's Basic-auth credentials into one token, so `init()` needs nothing else. It
contains a secret — treat it like any API key (env var / secrets manager; never commit).

## Publishing

```bash
python -m build              # → dist/enlight_chakra_observability-0.1.0-*.whl + .tar.gz
twine upload dist/*          # public PyPI  (or: twine upload -r <private-index> dist/*)
```

## License

Apache-2.0.
