langfuse-ergonomic

Ergonomic Rust client for Langfuse, the open-source LLM observability platform.

Features

🏗️ Builder Pattern - Intuitive API using the Bon builder pattern library
🔄 Async/Await - Full async support with Tokio
🔒 Type Safe - Strongly typed with compile-time guarantees
🚀 Easy Setup - Simple configuration from environment variables
📊 Comprehensive - Support for traces, observations, scores, and more

Installation

[dependencies]
langfuse-ergonomic = "0.1"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Quick Start

use langfuse_ergonomic::LangfuseClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client from environment variables
    let client = LangfuseClient::from_env()?;
    
    // Create a trace
    let trace = client.trace()
        .name("my-application")
        .input(json!({"query": "Hello, world!"}))
        .output(json!({"response": "Hi there!"}))
        .user_id("user-123")
        .tags(["production", "chat"])
        .send()
        .await?;
    
    println!("Created trace: {}", trace.id);
    Ok(())
}

Configuration

Set these environment variables:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Optional

Or configure explicitly:

let client = LangfuseClient::builder()
    .public_key("pk-lf-...")
    .secret_key("sk-lf-...")
    .base_url("https://cloud.langfuse.com")
    .build();

Examples

Check the examples/ directory for more usage examples:

# Trace examples
cargo run --example basic_trace
cargo run --example trace_with_metadata
cargo run --example multiple_traces

# Observations (spans, generations, events)
cargo run --example observations

# Scoring and evaluation
cargo run --example scores

API Coverage

Currently Implemented ✅

Traces

Full trace creation with metadata support
Session and user tracking
Tags and custom timestamps
Input/output data capture

Observations

Spans - Track execution steps and nested operations
Generations - Monitor LLM calls with token usage
Events - Log important milestones and errors
Nested observations with parent-child relationships
Log levels (DEBUG, INFO, WARNING, ERROR)

Scoring

Numeric scores - Evaluate with decimal values (0.0-1.0)
Categorical scores - Text-based classifications
Binary scores - Success/failure tracking
Rating scores - Star ratings and scales
Trace-level and observation-level scoring
Score metadata and comments

Coming Soon 🚧

Dataset management
Prompt management
Batch operations
Fetching existing traces

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE)
MIT license (LICENSE-MIT)

Contributing

See CONTRIBUTING.md for guidelines.

langfuse-ergonomic 0.1.1