Metadata-Version: 2.4
Name: uptimes-agents
Version: 0.1.2
Summary: Uptimes Agents — OpenTelemetry-based observability for AI agents. Three-line init, ships to local uptimes-monitor or direct to api.uptimes.ai.
Author-email: "Uptimes.ai" <engineering@uptimes.ai>
License: Apache-2.0
Project-URL: Homepage, https://uptimes.ai
Project-URL: Documentation, https://uptimes.ai/docs/agents/python-sdk
Project-URL: Repository, https://github.com/uptimes-ai/uptimes-agents-python
Project-URL: Issues, https://github.com/uptimes-ai/uptimes-agents-python/issues
Keywords: opentelemetry,otel,ai-agents,observability,llm,anthropic,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.27
Requires-Dist: opentelemetry-sdk>=1.27
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
Provides-Extra: anthropic
Requires-Dist: openinference-instrumentation-anthropic>=0.1.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openinference-instrumentation-openai>=0.1.0; extra == "openai"
Provides-Extra: all
Requires-Dist: openinference-instrumentation-anthropic>=0.1.0; extra == "all"
Requires-Dist: openinference-instrumentation-openai>=0.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# uptimes-agents (Python)

OpenTelemetry-based observability SDK for AI agents — three-line install,
ships to the local `uptimes-monitor` daemon or direct to `api.uptimes.ai`.

## Install

```bash
pip install uptimes-agents
# Add provider extras for auto-instrumentation:
pip install 'uptimes-agents[anthropic]'    # or [openai], or [all]
```

## Quick start

```python
import uptimes_agents
import anthropic

uptimes_agents.init(service_name="rca-agent")

client = anthropic.Anthropic()
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=[{"role": "user", "content": "hi"}],
)
# → one chat span lands in your Uptimes dashboard within ~5s.
```

## Custom spans

For non-LLM work — `init()` activates auto-instrumentation for known
provider SDKs; for everything else, wrap your code in a span:

```python
with uptimes_agents.span("execute_plan", hypothesis="db_slow"):
    ...
    uptimes_agents.current_span().set_attribute("steps_taken", 4)
```

## Configuration

| Arg / env var | Default | Notes |
|---|---|---|
| `service_name` (kwarg) | required | Becomes `agent_name` in Uptimes |
| `endpoint` / `UPTIMES_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP/HTTP target |
| `api_key` / `UPTIMES_API_KEY` | none | Required only on direct-to-cloud |
| `resource_attributes` | `{}` | Extra OTel resource attrs |
| `auto_instrument_providers` | `True` | Set False to manage your own instrumentations |

Standard OTel env vars (`OTEL_EXPORTER_OTLP_ENDPOINT`,
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) are honored — drop-in for existing
OTel-instrumented apps.

## Routing modes

Default is **via the local monitor**: spans go to `http://localhost:4318`
on the host. `uptimes-monitor` enriches them with host context, batches,
and forwards over a single TLS connection to `api.uptimes.ai`. No API key
needed in your app — the monitor's token stamps `org_id`.

For containerised environments without a host daemon, point straight at
the cloud:

```python
uptimes_agents.init(
    service_name="my-agent",
    endpoint="https://api.uptimes.ai/v1/traces/otlp",
    api_key="<your-org-token>",
)
```

## What gets captured

Auto-instrumentation produces OTel-GenAI spans for every Anthropic / OpenAI
LLM call:

- Provider, model, token usage, cost
- Latency, time-to-first-chunk, stop reason
- Tool calls (when the provider returns `tool_use` content)
- Input / output content (governable via OTel content-capture toggles)

Custom `span(...)` blocks produce regular OTel spans you can group by name
in the dashboard.

## Versioning

V0.1 — Anthropic + OpenAI auto-instrumentation. Bedrock / Vertex / Gemini
land in V0.2.
