puvinoise-sdk
Independent OpenTelemetry SDK for AI agents. Supports Anthropic Claude, OpenAI, Ollama, and other LLM providers with tracing and observability.
Install
pip install puvinoise-sdk
Optional provider extras:
pip install puvinoise-sdk[anthropic]
pip install puvinoise-sdk[openai]
pip install puvinoise-sdk[all]
Quick start
from puvinoise import bootstrap, run_with_trace
bootstrap() # Configure via env: PUVINOISE_AGENT_NAME, CUST_LLM_PROVIDER, PUVINOISE_TENANTID, PUVINOISE_API_KEY, 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 |
|---|---|
PUVINOISE_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_API_KEY |
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:
PUVINOISE_AGENT_NAME=my-agent-system
CUST_LLM_PROVIDER=openai
PUVINOISE_TENANTID=your-tenant-id
PUVINOISE_API_KEY=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(fromPUVINOISE_AGENT_NAME),tenant.id(fromPUVINOISE_TENANTID),puvinoise.llm_provider(fromCUST_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.
Decision telemetry (AI agent signals)
The SDK can emit decision telemetry for behaviour intelligence (intent, tool candidates, reasoning checkpoints, decision confidence, tool selection reasoning, agent state transitions). See DECISION_TELEMETRY_SDK_DESIGN.md for the full design.
Optional run-level intent (set on agent.run span and propagated to child spans):
from puvinoise import bootstrap, run_with_trace
run_with_trace(my_agent_fn, agent_name="my-agent", goal="answer user question", task_type="qa", intent="answer_question")
Emit signals explicitly (must be inside an active trace, e.g. inside run_with_trace or under an agent.run span):
from puvinoise import (
record_intent_classification,
record_tool_candidates,
record_reasoning_checkpoint,
record_decision_confidence,
record_tool_selection_reasoning,
record_agent_state_transition,
)
# Intent (also sets agent.intent / agent.goal / agent.task_type on current span)
record_intent_classification("answer_question", goal="answer user question", task_type="qa", confidence=0.92)
# Tool candidates and selection reasoning (on tool span)
record_tool_candidates(["web_search", "calculator"], selected_name="web_search", reasoning="need current info", confidence=0.9)
record_tool_selection_reasoning("web_search", "need current info", confidence=0.9)
# Reasoning checkpoint (e.g. after LLM call)
record_reasoning_checkpoint("after_system_prompt", summary="model ready", step_index=1)
# Decision confidence
record_decision_confidence(0.88, scope="turn")
# Agent state transition (updates context state)
record_agent_state_transition("thinking", "tool_calling", reason="model decided to use tool")
Tool decorator with decision telemetry:
from puvinoise import instrument_tool_call
@instrument_tool_call(
"web_search",
tool_candidates=["web_search", "calculator"],
selection_reasoning="need current info",
selection_confidence=0.9,
)
def search_web(query: str):
...
Spans are still exported on the same schedule (default every 1 second via the batch processor). Decision signals appear as span attributes and as decision.* span events so the behaviour pipeline can build decision graphs and run the behaviour intelligence engine.
License
Proprietary – PUVI LABS PRIVATE LIMITED
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file puvinoise_sdk-0.3.69.tar.gz.
File metadata
- Download URL: puvinoise_sdk-0.3.69.tar.gz
- Upload date:
- Size: 309.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a2098f1ba05140a54e33e23638d45c6516aa542fb2cbefda32fe38e8501f8761
|
|
| MD5 |
30e29bffba782d8db310e65b289a288a
|
|
| BLAKE2b-256 |
ef7359363fdea03e50e5de9ed60feb181868086ebdb5312063597414ca9bfcc6
|
File details
Details for the file puvinoise_sdk-0.3.69-py3-none-any.whl.
File metadata
- Download URL: puvinoise_sdk-0.3.69-py3-none-any.whl
- Upload date:
- Size: 336.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8cf4d7a0489f58619ddb8fee201c6658acb7411375575675eb4cf010ba0b8e52
|
|
| MD5 |
4f1e6e678cbca9db6365f412c8984938
|
|
| BLAKE2b-256 |
f40fe9a41b5a0f063702c34da8cdd046c13e7df14a7bf02f61c47cb5048c1a27
|
