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

Onboarding has two phases, and they read configuration from different places. Conflating them is the most common integration failure.

Phase Command Reads

1 · Bind puvinoise-bind --env-only --env <env> --base-url <url> the environment variables below

2 · Runtime puvinoise run --agent-name <name> python agent.py .puvinoise/ state files written by bind

In strict runtime the SDK ignores PUVINOISE_BASE_URL / PUVINOISE_API_KEY from the environment and resolves them from .puvinoise/env_<env>.json and .puvinoise/agent_<id>.json. If you set them and expect the runtime to use them, it will tell you they are ignored — that is correct behaviour, not a bug.

PUVINOISE_AGENT_ID is the one exception: it is environment-authoritative in both phases and is the single source of agent identity. It is never accepted as an init() parameter.

The table below therefore describes bind-phase / legacy bootstrap() configuration. For the supported end-to-end path see env.template.

Phase	Command	Reads
1 · Bind	`puvinoise-bind --env-only --env <env> --base-url <url>`	the environment variables below
2 · Runtime	`puvinoise run --agent-name <name> python agent.py`	`.puvinoise/` state files written by bind

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 (from PUVINOISE_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.

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

Metadata

Release files for puvinoise-sdk 0.3.111

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for puvinoise-sdk 0.3.111
File	Size	Uploaded
puvinoise_sdk-0.3.111.tar.gz	469.1 kB	Sep 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for puvinoise-sdk 0.3.111
File	Interpreter	ABI	Platform	Reset
puvinoise_sdk-0.3.111-py3-none-any.whl 470.2 kB Sep 23, 2026	Python 3	none	any	Details

Total release size: 939.3 kB

Release files / puvinoise_sdk-0.3.111.tar.gz

Download URL	puvinoise_sdk-0.3.111.tar.gz
Size	469.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`3abba3b29d857ebbeb1297cd5a0bbdda61208d315858f7961b8c632fa6f4d81a`
BLAKE2b-256 checksum How to use checksums	`046e1562296fdf91bc05c5f7e4b9ea6f28d9d47fa8e0594678c812500a8e656a`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`

Release files / puvinoise_sdk-0.3.111-py3-none-any.whl

Download URL	puvinoise_sdk-0.3.111-py3-none-any.whl
Size	470.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`25da711ddc83f9d7dfe8137f952cf90b08345123b2e4c06c33ea972b57f10015`
BLAKE2b-256 checksum How to use checksums	`197eb103f92556ef243aaae1a05d7d99ecca54bf90eb5f5072ad8c270191985c`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`