Python SDK

Installation

pip install observiq-sdk

Initialization

from observiq_sdk import ObservIQ
 
client = ObservIQ(
    api_key="oiq_your_key_here",
    base_url="https://your-backend.railway.app",  # your deployed backend
    enabled=True   # set False to disable in tests
)

Parameters

Parameter	Type	Required	Default	Description
`api_key`	`str`	✅	—	Your ObservIQ API key
`base_url`	`str`	❌	`http://localhost:8000`	Your backend URL
`enabled`	`bool`	❌	`True`	Set `False` to disable tracing

`client.trace()`

Use as a context manager to automatically capture trace data around any AI call.

with client.trace(model="gpt-4o-mini", feature_name="my_feature"):
    response = call_your_ai_model()

Parameters

Parameter	Type	Required	Description
`model`	`str`	✅	The model name being called
`feature_name`	`str`	❌	Label for analytics grouping
`user_identifier`	`str`	❌	User ID for per-user breakdown

With Groq

from groq import Groq
from observiq_sdk import ObservIQ
 
groq_client = Groq(api_key="gsk_...")
client = ObservIQ(api_key="oiq_...")
 
with client.trace(model="llama-3.3-70b-versatile", feature_name="customer_support"):
    response = groq_client.chat.completions.create(
        model="llama-3.3-70b-versatile",
        messages=[{"role": "user", "content": "Explain quantum computing"}],
        max_tokens=200
    )

With OpenAI

from openai import OpenAI
from observiq_sdk import ObservIQ
 
openai_client = OpenAI(api_key="sk-...")
client = ObservIQ(api_key="oiq_...")
 
with client.trace(model="gpt-4o-mini", feature_name="support-summary"):
    response = openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}]
    )

With Anthropic

import anthropic
from observiq_sdk import ObservIQ
 
anthropic_client = anthropic.Anthropic(api_key="sk-ant-...")
client = ObservIQ(api_key="oiq_...")
 
with client.trace(model="claude-sonnet-4-5", feature_name="invoice-parser"):
    response = anthropic_client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}]
    )

Feature Names

Use feature_name to group traces by the feature of your app that made the call. This shows up in the Analytics section of your dashboard (opens in a new tab).

# Customer support feature
with client.trace(model="llama-3.3-70b-versatile", feature_name="customer_support"):
    response = groq_client.chat.completions.create(...)
 
# Document summarizer feature
with client.trace(model="gpt-4o-mini", feature_name="support-summary"):
    response = openai_client.chat.completions.create(...)
 
# Invoice parser
with client.trace(model="claude-sonnet-4-5", feature_name="invoice-parser"):
    response = anthropic_client.messages.create(...)

Your dashboard will then show a breakdown by feature with call counts, cost per day, and latency.

Error Handling

ObservIQ never crashes your app. If the SDK fails to send a trace, it logs a warning and continues silently.

try:
    with client.trace(model="llama-3.3-70b-versatile", feature_name="chat"):
        response = groq_client.chat.completions.create(
            model="llama-3.3-70b-versatile",
            messages=[{"role": "user", "content": "Hello"}]
        )
except groq.APIError as e:
    # Only actual Groq errors are raised — ObservIQ failures are silent
    print(f"Groq error: {e}")

Traces are sent in a background thread so your app's response time is never affected.

Disable in Tests

import os
from observiq_sdk import ObservIQ
 
client = ObservIQ(
    api_key="oiq_...",
    enabled=os.environ.get("ENV") != "test"
)

Installation Configuration