Metadata-Version: 2.4
Name: atomiclens
Version: 0.1.0
Summary: Atomic Lens Python SDK. OpenTelemetry-native auto-instrumentation for LLM agents.
Project-URL: Homepage, https://github.com/Worldwideblake/atomic-lens
Project-URL: Repository, https://github.com/Worldwideblake/atomic-lens
Project-URL: Issues, https://github.com/Worldwideblake/atomic-lens/issues
Author: Blake Mills
License: Apache-2.0
Keywords: agents,anthropic,cost-tracking,llm,observability,openai,opentelemetry,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api>=1.27
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
Requires-Dist: opentelemetry-sdk>=1.27
Provides-Extra: all
Requires-Dist: anthropic>=0.34; extra == 'all'
Requires-Dist: huggingface-hub>=0.24; extra == 'all'
Requires-Dist: openai>=1.40; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34; extra == 'anthropic'
Provides-Extra: huggingface
Requires-Dist: huggingface-hub>=0.24; extra == 'huggingface'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Description-Content-Type: text/markdown

# atomiclens

OpenTelemetry-native observability for LLM agents. One `init()` call
auto-instruments your OpenAI, Anthropic, and Hugging Face calls and exports
priced, attributed spans (tokens, USD cost, latency, model) to any OTLP
endpoint, including the open-source [Atomic Lens](https://github.com/Worldwideblake/atomic-lens)
backend and dashboard.

```sh
pip install atomiclens            # core
pip install "atomiclens[openai]"  # + OpenAI auto-instrumentation
pip install "atomiclens[all]"     # OpenAI + Anthropic + Hugging Face
```

## Quickstart

```python
import atomiclens

atomiclens.init(service_name="my-agent", otlp_endpoint="http://localhost:4318")

# Every OpenAI / Anthropic / Hugging Face call is now traced with token
# counts and USD cost, with no other code change.
from openai import OpenAI

client = OpenAI()
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
```

Streaming calls are handled too: `stream_options.include_usage` is injected so
token usage and cost are captured even when you stream.

## Attribution

Tag spans with the workflow, agent, user, and team they belong to so the
dashboard can break cost down by any of them:

```python
from atomiclens import workflow, agent, set_user, set_team

set_user("user_123")
set_team("growth")

with workflow("weekly-report"):
    summarize()          # spans inherit workflow="weekly-report"

@agent("researcher")
def research(topic): ...  # spans inherit agent_name="researcher"
```

## Configuration

`init()` reads sensible defaults from the environment so you can configure it
without touching code:

| Env var | Purpose |
|---|---|
| `ATOMICLENS_OTLP_ENDPOINT` | Where spans are exported (defaults to `http://localhost:4318`) |
| `ATOMICLENS_API_KEY` | Sent as the ingest key to a protected backend |

`service_name` is a required argument to `init()`. `init()` is idempotent, so
calling it more than once is safe (pass `force=True` to reconfigure).

## Framework integrations

LangChain and LlamaIndex callback handlers are available as optional extras
(`pip install "atomiclens[langchain]"` / `"atomiclens[llamaindex]"`).

## License

Apache-2.0. Source and the full self-hostable backend + dashboard live at
[github.com/Worldwideblake/atomic-lens](https://github.com/Worldwideblake/atomic-lens).
