Python SDK

# Without tracing, you have no idea what happened:
result = my_agent("Summarize this document")
# Did it work? How long did it take? What LLM calls were made?
# What tools were used? Why did it fail? 🤷

# With tracing, you see everything:
@notarylabs.observe("my-agent")
def my_agent(question: str):
    # Every step is recorded with timing, inputs, outputs
    ...

import notarylabs

notarylabs.init(api_key="nl_live_xxx")

# The @observe decorator wraps your function and records:
# - When it started and ended
# - What arguments were passed in
# - What value was returned (or what error was raised)
# - How long it took
# - All LLM calls and tool calls made inside

@notarylabs.observe("document-summarizer")
def summarize_document(doc: str) -> str:
    # Everything inside here is traced
    summary = call_llm(f"Summarize: {doc}")
    return summary

result = summarize_document("Long document text...")
# A trace event is automatically sent to your dashboard

# Traces can be nested. When you call an observed function
# from inside another observed function, a parent-child
# relationship is automatically created.

@notarylabs.observe("orchestrator")
def orchestrator(task: str):
    # This trace is the parent
    plan = planner(task)        # Child trace
    result = executor(plan)      # Child trace
    return result

@notarylabs.observe("planner")
def planner(task: str):
    # This trace is a child of "orchestrator"
    return create_plan(task)

@notarylabs.observe("executor")
def executor(plan: list):
    # This trace is also a child of "orchestrator"
    return execute_plan(plan)

# In your dashboard, you'll see:
# orchestrator
# ├── planner
# └── executor

# Tools are external actions your agent takes:
# - API calls
# - Database queries
# - File operations
# - Web searches
# - Any side effect

# Use the tool() context manager to log these:

@notarylabs.observe("research-agent")
def research_agent(topic: str):

    # Log a web search tool call
    with notarylabs.tool("web-search") as t:
        t.set_input({"query": topic})      # What went into the tool
        results = search_api(topic)         # Actually call the tool
        t.set_output({"results": results})  # What came out

    # Log a database query
    with notarylabs.tool("database-lookup") as t:
        t.set_input({"table": "documents", "filter": topic})
        docs = db.query(topic)
        t.set_output({"count": len(docs)})

    return process_results(results, docs)

# Errors are automatically captured. If an exception is raised
# inside a tool() block, the SDK records the error and re-raises it.

with notarylabs.tool("risky-api-call") as t:
    t.set_input({"endpoint": "/data"})
    response = requests.get("https://api.example.com/data")
    response.raise_for_status()  # Might raise an exception
    t.set_output(response.json())

# If raise_for_status() throws, your dashboard shows:
# - tool_name: "risky-api-call"
# - status: "error"
# - error: "HTTPError: 500 Server Error"
# - duration_ms: 1234

# Problem: LLM calls are the most important thing to monitor,
# but manually logging every call is tedious and error-prone.

# Without auto-capture (tedious):
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": query}]
)
# Now manually log: model, messages, response, tokens, latency...

# With auto-capture (automatic):
from notarylabs.clients import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": query}]
)
# Automatically logged: model, messages, response, token usage, latency

from notarylabs.clients import OpenAI

# This is a drop-in replacement for openai.OpenAI
# The API is identical - just change your import
client = OpenAI(api_key="sk-...")

@notarylabs.observe("qa-agent")
def qa_agent(question: str):
    # This LLM call is automatically captured
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": question}
        ]
    )
    return response.choices[0].message.content

# Your dashboard shows the LLM call with:
# - provider: "openai"
# - model: "gpt-4"
# - input_messages: [...]
# - output_content: "..."
# - token usage: {prompt: X, completion: Y, total: Z}
# - duration_ms: 1234