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 setup_pipecat_tracing
from pipecat.pipeline.task import PipelineTask
 
noveum_trace.init(project="pipecat-bot", api_key="your-api-key")
 
observer = setup_pipecat_tracing(trace_name_prefix="my-bot")
task = PipelineTask(pipeline, observers=[observer])
await observer.attach_to_task(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()