prometa-sdk 0.2.3

Official Python SDK for the Prometa Agentic Lifecycle Intelligence Platform

prometa-sdk (Python)

Official Python SDK for the Prometa Agentic Lifecycle Intelligence Platform.

Wraps OpenTelemetry GenAI semantic conventions with @prometa decorators that automatically emit lifecycle metadata (solution_id, stage, agent) to your Prometa instance via OTLP/JSON.

Install

pip install prometa-sdk

Quick start

import asyncio
from prometa import Prometa

prometa = Prometa(
    endpoint="https://prometa.example.com/api/v2/otlp/v1/traces",
    api_key="prm_live_...",
    solution_id="sol_abc123",
    agent_name="customer-support",
    stage="production",
)

@prometa.workflow(name="handle-ticket")
async def handle_ticket(ticket_id: str) -> str:
    @prometa.agent(name="classifier")
    async def classify() -> str:
        return "billing"

    @prometa.tool(name="kb-search")
    async def kb_search(q: str) -> list[str]:
        return ["doc1", "doc2"]

    category = await classify()
    results = await kb_search(category)
    return f"resolved {ticket_id} via {results}"

asyncio.run(handle_ticket("T-1234"))
prometa.flush()

What gets captured

Each decorated function emits a span with:

• prometa.kind — workflow | agent | tool | task
• prometa.solution_id, prometa.stage
• gen_ai.agent.name, gen_ai.agent.id
• Parent/child relationships across async/sync calls
• Errors → span status error plus error.message

LLM client auto-instrumentation

For traces to show token usage, cost, and prompt/completion text, opt in to the per-client patcher matching the LLM library you use. Without this, spans render but the cost panel reads $0.000 and the trace UI has no prompt/completion to display.

from prometa import Prometa
from prometa.integrations import openai as prometa_openai
from prometa.integrations import anthropic as prometa_anthropic
from prometa.integrations import google as prometa_google

Prometa(endpoint=..., agent_name="my-agent")

# Call install() once at startup. Each returns False (no-op) if the
# corresponding library isn't installed — so it's safe to call all three.
prometa_openai.install()
prometa_anthropic.install()
prometa_google.install()

Once installed, every client.chat.completions.create(...), client.messages.create(...), and client.models.generate_content(...) call (sync, async, and streaming) emits a child span carrying:

• gen_ai.system (openai / anthropic / google)
• gen_ai.request.model, temperature, top_p, max_tokens
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens → drives cost
• gen_ai.prompt (truncated JSON of input messages)
• gen_ai.completion (truncated assistant reply)
• gen_ai.response.id, gen_ai.response.model, gen_ai.response.finish_reasons

Streaming spans propagate context properly — any @prometa.tool / @prometa.agent invoked from inside the stream consumer nests under the LLM span, not under whatever was active when .create() returned.

How the trace "Conversation" panel populates

The Prometa trace UI renders a Conversation panel that derives turns directly from the gen_ai.prompt / gen_ai.completion span attributes emitted by the integrations on this page. Each LLM span becomes a user turn (the latest user message extracted from gen_ai.prompt) followed by an agent turn (the completion). Token counts and timestamps come straight off the span — nothing else needs to be wired up on the platform side.

The After preprocessing vs Raw toggle is also rendered, but both modes show the same text until the platform's PII redactor / policy gate ships and starts populating the prometa.conversation_turns table. When that lands, the panel will switch back to reading the processed-vs-raw pair from that table; the SDK contract does not change.

Configuration

Param	Env var	Default
endpoint	—	required
api_key	PROMETA_API_KEY	none
solution_id	—	none
agent_name	—	"prometa-agent"
stage	—	"development"
flush_interval_seconds	—	2.0

License

Apache-2.0