Python SDK

pip install nodeloom-sdk

from nodeloom import NodeLoom, SpanType, TraceStatus

client = NodeLoom(api_key="sdk_...")

# Start a trace for your agent
trace = client.trace("customer-support-agent", input={"query": "How do I reset my password?"})

# Track an LLM call
with trace.span("openai-chat", type=SpanType.LLM) as span:
    result = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "How do I reset my password?"}]
    )
    span.set_output({"response": result.choices[0].message.content})
    span.set_token_usage(
        prompt_tokens=result.usage.prompt_tokens,
        completion_tokens=result.usage.completion_tokens,
        model="gpt-4o"
    )

# Track a tool call
with trace.span("lookup-user", type=SpanType.TOOL) as span:
    span.set_input({"email": "[email protected]"})
    user = lookup_user("[email protected]")
    span.set_output({"user_id": user.id})

# End the trace
trace.end(status=TraceStatus.SUCCESS, output={"answer": "You can reset your password from..."})

# Always shut down before exit
client.shutdown()

client = NodeLoom(
    api_key="sdk_...",
    batch_size=50,
    flush_interval=3.0,
    max_queue_size=5000
)

# Basic trace
trace = client.trace("my-agent")
# ... agent work ...
trace.end(status=TraceStatus.SUCCESS)

# Trace with input, output, and metadata
trace = client.trace(
    "my-agent",
    input={"query": "Tell me about AI"},
    metadata={"user_id": "u123", "session_id": "s456"},
    environment="production"  # or "development", "staging"
)
# ... agent work ...
trace.end(
    status=TraceStatus.SUCCESS,
    output={"answer": "AI is..."}
)

# Trace with error
trace = client.trace("my-agent", input={"query": "..."})
try:
    # ... agent work ...
    trace.end(status=TraceStatus.SUCCESS, output=result)
except Exception as e:
    trace.end(status=TraceStatus.ERROR, error=str(e))

# Context manager (recommended)
with trace.span("my-llm-call", type=SpanType.LLM) as span:
    span.set_input({"prompt": "Hello"})
    result = call_llm("Hello")
    span.set_output({"response": result})

# Manual span management
span = trace.span("my-tool-call", type=SpanType.TOOL)
span.set_input({"query": "search term"})
result = search_database("search term")
span.set_output({"results": result})
span.end()  # or span.end(error="something went wrong")

with trace.span("llm-call", type=SpanType.LLM) as span:
    result = openai.chat.completions.create(...)
    span.set_token_usage(
        prompt_tokens=result.usage.prompt_tokens,
        completion_tokens=result.usage.completion_tokens,
        model="gpt-4o"
    )

from nodeloom import NodeLoom
from nodeloom.integrations.langchain import NodeLoomCallbackHandler

client = NodeLoom(api_key="sdk_...")
handler = NodeLoomCallbackHandler(client)

# Use with any LangChain chain or agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o")
prompt = ChatPromptTemplate.from_template("Tell me about {topic}")
chain = prompt | llm

# The handler automatically creates traces and spans
result = chain.invoke(
    {"topic": "quantum computing"},
    config={"callbacks": [handler]}
)

client.shutdown()

from nodeloom import NodeLoom
from nodeloom.integrations.crewai import NodeLoomCrewHandler

client = NodeLoom(api_key="sdk_...")
handler = NodeLoomCrewHandler(client)

from crewai import Agent, Task, Crew

researcher = Agent(role="Researcher", goal="...", backstory="...")
task = Task(description="Research AI trends", agent=researcher)
crew = Crew(agents=[researcher], tasks=[task])

# Attach the handler to instrument the crew
result = crew.kickoff(callbacks=[handler])

client.shutdown()

# Record a custom metric
client.metric("response_latency", 1.23, unit="seconds", tags={"model": "gpt-4o"})
client.metric("tokens_per_request", 450, unit="tokens")
client.metric("user_satisfaction", 4.5, unit="score", tags={"agent": "support"})

# Submit feedback for a trace
client.feedback(trace_id=trace.trace_id, rating=5, comment="Accurate and helpful")
client.feedback(trace_id=trace.trace_id, rating=1, comment="Hallucinated facts", tags=["inaccurate"])

# Group traces into a conversation session
session_id = "conv-" + str(uuid4())

trace1 = client.trace("support-agent", session_id=session_id, input={"query": "What's my balance?"})
# ... agent logic ...
trace1.end(status=TraceStatus.SUCCESS, output={"answer": "$1,234.56"})

trace2 = client.trace("support-agent", session_id=session_id, input={"query": "Transfer $100"})
# ... agent logic ...
trace2.end(status=TraceStatus.SUCCESS, output={"answer": "Transfer initiated"})

# Register a prompt template
client.set_prompt(
    "customer-support-system",
    content="You are a helpful customer support agent for {{company_name}}. Always be polite and concise.",
    variables=["company_name"],
    model_hint="gpt-4o"
)

# Track prompt version in spans
with trace.span("llm-call", type=SpanType.LLM) as span:
    span.set_prompt_info(template="customer-support-system", version=2)
    # ... LLM call ...

# Register callback for red team testing and batch evaluation
client.register_callback("my-agent", "https://my-agent.example.com/callback")

# Your callback endpoint should handle:
# POST with {"prompt": "...", "category": "redteam|eval"}
# Return: {"response": "agent's response text"}

# Read guardrail config (configured in NodeLoom UI)
config = client.get_guardrail_config("my-agent")
if config and config.get("detectPromptInjection"):
    print("Prompt injection detection is enabled")

# Guardrails are configured per-agent in the NodeLoom UI:
# Workflows → click SDK agent → Guardrails tab

# Blocks until all events are flushed (up to 10s timeout)
client.shutdown()

# With custom timeout
client.shutdown(timeout=30.0)