Python SDK

Integrate Noveum's Python SDK for comprehensive AI application tracing.

The Noveum Python SDK (noveum-trace) provides context manager-based tracing for LLM applications, voice agents, RAG pipelines, and multi-agent systems.

Requirements: Python 3.9+

Installation

pip install noveum-trace

With framework extras:

pip install "noveum-trace[langchain]"    # LangChain / LangGraph
pip install "noveum-trace[livekit]"     # LiveKit voice agents
pip install "noveum-trace[pipecat]"     # Pipecat pipelines
pip install "noveum-trace[crewai]"      # CrewAI (Python 3.10+)

Quick Start

import noveum_trace
from openai import OpenAI

noveum_trace.init(
    api_key="your-api-key",
    project="my-llm-app",
    environment="production",
)

client = OpenAI()

def call_llm(prompt: str) -> str:
    with noveum_trace.trace_llm_call(model="gpt-4", provider="openai") as span:
        response = client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": prompt}]
        )
        span.set_attributes({
            "llm.input_tokens": response.usage.prompt_tokens,
            "llm.output_tokens": response.usage.completion_tokens,
        })
        return response.choices[0].message.content

noveum_trace.flush()

Core API

Initialization

import noveum_trace

# init() is idempotent: safe to call multiple times
noveum_trace.init(
    api_key="your-api-key",   # or NOVEUM_API_KEY env var
    project="my-app",          # or NOVEUM_PROJECT env var
    environment="production",  # optional
)

Context managers

from noveum_trace import trace_llm_call, trace_agent_operation, trace_operation

# Trace an LLM call
with trace_llm_call(model="gpt-4", provider="openai") as span:
    response = client.chat.completions.create(...)
    span.capture_response(response)   # automatic token/cost extraction
    # or set manually:
    span.set_attributes({
        "llm.input_tokens": response.usage.prompt_tokens,
        "llm.output_tokens": response.usage.completion_tokens,
    })

# Trace an agent operation
with trace_agent_operation(agent_type="planner", operation="task_planning") as span:
    plan = agent.plan(task)
    span.set_attribute("plan.steps", len(plan.steps))

# Trace any operation
with trace_operation("database_query") as span:
    results = db.query(sql)
    span.set_attribute("query.rows", len(results))

Framework Integrations

LangChain

import noveum_trace
from noveum_trace.integrations.langchain import NoveumTraceCallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

noveum_trace.init(project="langchain-app", api_key="your-api-key")

handler = NoveumTraceCallbackHandler()

prompt = ChatPromptTemplate.from_template("Summarize: {text}")
chain = prompt | ChatOpenAI() | StrOutputParser()

result = chain.invoke({"text": "your document"}, config={"callbacks": [handler]})

LiveKit

import noveum_trace
from noveum_trace.integrations.livekit import (
    LiveKitSTTWrapper, LiveKitTTSWrapper, setup_livekit_tracing
)
from livekit.agents import Agent, AgentSession, JobContext
from livekit.plugins import deepgram, cartesia, openai

noveum_trace.init(project="voice-agent", api_key="your-api-key")

async def entrypoint(ctx: JobContext):
    traced_stt = LiveKitSTTWrapper(stt=deepgram.STT(model="nova-2"), session_id=ctx.job.id)
    traced_tts = LiveKitTTSWrapper(tts=cartesia.TTS(model="sonic-english"), session_id=ctx.job.id)

    session = AgentSession(stt=traced_stt, llm=openai.LLM(), tts=traced_tts)
    setup_livekit_tracing(session)  # no metadata= parameter
    await session.start(agent=Agent(instructions="You are helpful."), room=ctx.room)

Pipecat

import noveum_trace
from noveum_trace.integrations.pipecat import NoveumPipecatTracer

noveum_trace.init(api_key="your-api-key", project="pipecat-bot")

# Two-call API: run inside your app's async setup (e.g. the Pipecat entrypoint).
async def setup_tracing(pipeline, task, transport):
    tracer = NoveumPipecatTracer(record_audio=True)
    pipeline = tracer.observe_pipeline(pipeline)
    task = await tracer.register_task_handlers(task, transport=transport)
    return pipeline, task

CrewAI

import noveum_trace
from noveum_trace.integrations.crewai import setup_crewai_tracing

# Python 3.10+ required for CrewAI
noveum_trace.init(project="crewai-app", api_key="your-api-key")

listener = setup_crewai_tracing()
crew.callback_function = listener
result = crew.kickoff()