Prela SDK

Open-source Python SDK for AI agent observability, testing, and debugging.

Prela provides comprehensive instrumentation, evaluation frameworks, and replay capabilities for AI agents built with OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, AutoGen, LangGraph, and more.

Features

• 🔍 Auto-instrumentation - Zero-code observability for 10+ AI frameworks
• 📊 Evaluation Framework - 17+ assertion types for testing agent behavior
• 🔄 Replay Engine - Deterministic replay for debugging and testing
• 📤 Multiple Exporters - Console, file, HTTP, and ClickHouse outputs
• 🎯 Multi-Agent Support - Track complex agent interactions and delegations
• 🛠️ CLI Tools - Command-line interface for trace management
• 🧪 Production Ready - 836+ tests with comprehensive coverage

Installation

pip install prela

With Optional Integrations

# Install specific integrations
pip install prela[openai]       # OpenAI SDK
pip install prela[anthropic]    # Anthropic/Claude SDK
pip install prela[langchain]    # LangChain
pip install prela[llamaindex]   # LlamaIndex

# Install all integrations
pip install prela[all]

# Install with development tools
pip install prela[dev]

# Install with CLI tools
pip install prela[cli]

Quick Start

Basic Usage

import prela

# Initialize with console output
prela.init(service_name="my-agent", exporter="console")

# Your AI agent code here
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Prela automatically traces the OpenAI call

Auto-Instrumentation

Prela automatically instruments supported frameworks:

import prela

# One-line initialization
prela.init(service_name="my-app", exporter="console")

# All these frameworks are automatically traced:
# - OpenAI API calls
# - Anthropic/Claude API calls
# - LangChain chains and agents
# - LlamaIndex queries
# - CrewAI tasks
# - AutoGen conversations
# - LangGraph workflows
# - OpenAI Swarm agents

Manual Instrumentation

from prela import trace

@trace
def my_agent_function(user_input: str):
    # Your agent logic here
    return process_input(user_input)

# Or use context managers
from prela import tracer

with tracer.start_span("complex-operation") as span:
    result = do_something()
    span.set_attribute("result_count", len(result))

Evaluation Framework

from prela.evals import EvalRunner, TestCase, Assertion

# Define test cases
test_cases = [
    TestCase(
        name="greeting-test",
        input={"message": "Hello"},
        assertions=[
            Assertion.contains("hello", case_sensitive=False),
            Assertion.max_length(100)
        ]
    )
]

# Run evaluations
runner = EvalRunner()
results = runner.run(my_agent_function, test_cases)
results.print_summary()

Replay Engine

from prela.replay import ReplayEngine

# Load a trace
engine = ReplayEngine()
trace = engine.load_trace("trace_id_123")

# Replay with comparison
replay_result = engine.replay(trace)
comparison = engine.compare(trace, replay_result)

print(f"Similarity: {comparison.similarity_score}")

Supported Frameworks

Exporters

Console Exporter

prela.init(exporter="console")

File Exporter

prela.init(
    exporter="file",
    file_path="traces.jsonl"
)

HTTP Exporter

prela.init(
    exporter="http",
    endpoint="https://api.prela.io",
    api_key="your-api-key"
)

ClickHouse Exporter

prela.init(
    exporter="clickhouse",
    clickhouse_host="localhost",
    clickhouse_port=8123
)

CLI Tools

# List traces
prela list

# Show trace details
prela show <trace-id>

# Show most recent trace
prela last

# Search traces
prela search "error"

# Show failed traces
prela errors

# Interactive explorer
prela explore

Evaluation Assertions

Prela includes 17+ assertion types:

Structural Assertions:

• contains() - Check for substring
• regex() - Pattern matching
• json_schema() - Validate JSON structure
• length() - Check output length

Semantic Assertions:

• similarity() - Embedding-based similarity

Tool Assertions:

• tool_called() - Verify tool usage
• tool_args() - Validate tool arguments
• tool_sequence() - Check tool call order

Multi-Agent Assertions:

• agent_used() - Verify agent participation
• task_completed() - Check task completion
• delegation_pattern() - Validate delegation
• no_circular_delegation() - Prevent cycles
• collaboration_count() - Track interactions

Advanced Features

Sampling

from prela.core import AlwaysOnSampler, ProbabilitySampler, RateLimitSampler

# Always sample
prela.init(sampler=AlwaysOnSampler())

# Sample 10% of traces
prela.init(sampler=ProbabilitySampler(0.1))

# Sample max 100 traces/second
prela.init(sampler=RateLimitSampler(100))

Context Propagation

from prela import get_current_span

def my_function():
    span = get_current_span()
    span.set_attribute("custom_field", "value")
    span.add_event("checkpoint reached")

Custom Exporters

from prela.exporters import SpanExporter

class MyExporter(SpanExporter):
    def export(self, spans):
        for span in spans:
            # Custom export logic
            pass

prela.init(exporter=MyExporter())

Examples

See the examples/ directory for complete working examples:

• OpenAI Chatbot
• Anthropic Claude Agent
• LangChain RAG
• CrewAI Multi-Agent
• Evaluation Framework
• Replay Engine

Documentation

Full documentation is available at docs.prela.dev

• Getting Started Guide
• API Reference
• Integration Guides
• Evaluation Framework
• Replay Engine

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/garrettw2200/prela-sdk.git
cd prela-sdk

# Install development dependencies
pip install -e ".[dev,all]"

# Run tests
pytest

# Run linters
ruff check .
black .
mypy prela

Community

• GitHub Discussions
• Issue Tracker
• Discord Community (coming soon)

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

Built with ❤️ by the Prela team and contributors.

Star this repo if you find it useful! ⭐