oculo-sdk 0.1.0

Python SDK for Oculo — The Glass Box for AI Agents

Oculo Python SDK

Oculo is a "Glass Box" for AI agents—a comprehensive observability tool that lets you see inside your agent's cognition. This SDK provides the Python instrumentation to capture traces, spans, and memory mutations and send them to the Oculo daemon.

Note: This SDK requires the oculo-daemon to be running locally. Please refer to the main Oculo repository for daemon installation instructions.

📦 Installation

You can install the Oculo SDK directly from PyPI (coming soon) or from source:

# Install from source
pip install git+https://github.com/Mr-Dark-debug/oculo.git#subdirectory=sdk/python

Or, if developing locally:

cd sdk/python
pip install -e .

🚀 Quick Start

Instrumenting your agent is simple. Wrap your agent's execution in a trace, and wrap individual steps (like LLM calls or tool usage) in a span.

from oculo import OculoTracer

# 1. Initialize the tracer
tracer = OculoTracer(agent_name="research-agent-v1")

# 2. Start a trace
with tracer.trace() as t:
    
    # 3. Create a span for an LLM call
    with t.span("step_1_planning", operation_type="LLM") as s:
        prompt = "Plan a research trip to Mars."
        s.set_prompt(prompt)
        
        # ... call your LLM ...
        response = my_llm_function(prompt)
        
        s.set_completion(
            response.text, 
            prompt_tokens=response.usage.prompt_tokens, 
            completion_tokens=response.usage.completion_tokens
        )
        
    # 4. Track memory changes
    with t.span("update_memory", operation_type="MEMORY") as s:
        # Create a tracker wrapper around your agent's memory dict
        memory = s.memory_tracker(initial_state=agent.memory)
        
        # Mutations are automatically detected and logged!
        memory["current_goal"] = "Calculate trajectory"
        memory["constraints"].append("Fuel limit")

📚 Core Concepts

Traces (tracer.trace())

A Trace represents a complete execution workflow of your agent, from the initial user prompt to the final answer. It groups all subsequent operations together.

Spans (trace.span())

A Span represents a single unit of work. Spans can be nested to show causal relationships (e.g., a "CoT" span containing multiple "LLM" spans).

Supported operation_type values:

• LLM: Large Language Model calls
• TOOL: External tool invocations (search, calculator, etc.)
• MEMORY: Memory read/write operations
• PLANNING: Planning or reasoning steps
• RETRIEVAL: RAG or database lookups

Memory Tracking (span.memory_tracker())

Oculo excels at visualizing how your agent's state changes over time. The MemoryTracker wraps a standard Python dictionary and automatically records ADD, UPDATE, and DELETE events whenever you modify it.

# Automatic diffing
tracker = span.memory_tracker(agent.state)
tracker["status"] = "thinking"  # -> Generates an UPDATE event

🔧 Configuration

The OculoTracer can be configured with the following parameters:

tracer = OculoTracer(
    agent_name="my-agent",
    host="127.0.0.1",       # Daemon host
    port=9876,              # Daemon port
    auto_start=True,        # Connect immediately
    metadata={"env": "prod"} # Global tags
)

🤝 Contributing

We welcome contributions! Please see the main repository for contribution guidelines.

📄 License

MIT License. See LICENSE for details.