Metadata-Version: 2.4
Name: puvinoise-sdk
Version: 0.2.3
Summary: Independent OpenTelemetry SDK for AI agents (Anthropic, OpenAI, Ollama)
Author-email: PUVI LABS PRIVATE LIMITED <kalaiselvan@puvilabs.com>
License: Proprietary
Project-URL: Homepage, https://puvilabs.com
Keywords: puvinoise,opentelemetry,otel,tracing,llm,agents,observability
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-sdk>=1.20
Requires-Dist: opentelemetry-exporter-otlp>=1.20
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: all
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: openai>=1.0; extra == "all"

# puvinoise-sdk

Independent OpenTelemetry SDK for AI agents. Supports Anthropic Claude, OpenAI, Ollama, and other LLM providers with tracing and observability.

## Install

```bash
pip install puvinoise-sdk
```

Optional provider extras:

```bash
pip install puvinoise-sdk[anthropic]
pip install puvinoise-sdk[openai]
pip install puvinoise-sdk[all]
```

## Quick start

```python
from puvinoise import bootstrap, run_with_trace

bootstrap()  # Configure via env: CUST_AGENT_NAME, CUST_LLM_PROVIDER, PUVINOISE_TENANTID, PUVINOISE_AGENTACCESSKEY, PUVINOISE_END_POINT_URL

with run_with_trace("my-agent-run"):
    # Your agent / LLM calls
    pass
```

## Environment

The SDK reads these variables from the environment (e.g. from a `.env` file):

| Variable | Description |
|----------|-------------|
| **`CUST_AGENT_NAME`** | Agent/service name (e.g. `my-agent-system`). Internally the SDK uses the variable `puvicustagentname` for this value to avoid name conflicts with customer agent code. |
| **`CUST_LLM_PROVIDER`** | Connected integration / LLM provider (e.g. `openai`, `anthropic`, `ollama`); mapped from your tenant’s connected integration |
| **`PUVINOISE_TENANTID`** | Tenant ID for multi-tenant isolation (from your PUViNoise organization) |
| **`PUVINOISE_AGENTACCESSKEY`** | Agent access key for authenticating with the OTLP endpoint (sent as Bearer token) |
| **`PUVINOISE_END_POINT_URL`** | OTLP collector URL (e.g. `http://host:4318`; `/v1/traces` is appended if missing) |

Example `.env`:

```env
CUST_AGENT_NAME=my-agent-system
CUST_LLM_PROVIDER=openai
PUVINOISE_TENANTID=your-tenant-id
PUVINOISE_AGENTACCESSKEY=your_agent_access_key
PUVINOISE_END_POINT_URL=http://localhost:4318
```

## Telemetry emitted

The SDK sends all env-derived parameters to the collector so the dashboard can display and filter by them:

- **Resource attributes** (on every span): `service.name` (from `CUST_AGENT_NAME`), `tenant.id` (from `PUVINOISE_TENANTID`), `puvinoise.llm_provider` (from `CUST_LLM_PROVIDER`).
- **Span attributes** on `agent.run`: `agent.name`, `agent.run_id`, `tenant.id`, `puvinoise.llm_provider`, `llm.provider`.

The backend and dashboard use these to scope traces by tenant, filter by agent name and LLM provider, and show tenant ID and provider in the trace list and detail views.

## License

Proprietary – PUVI LABS PRIVATE LIMITED
