langfuse-prompt-library-iauro 0.1.3

A production-ready wrapper for Langfuse prompts and tracing with LLM integrations

Langfuse Prompt Library

A production-ready Python wrapper for Langfuse prompts and tracing with integrated LLM support (OpenAI, Anthropic).

Features

• Prompt Management: Create, update, fetch and manage prompts from Langfuse with built-in caching
• Multi-Provider Support: Works with OpenAI (GPT models) and Anthropic (Claude models)
• Automatic Tracing: Built-in observability and tracing for all LLM calls
• Token Tracking: Automatic token usage tracking and reporting
• Retry Logic: Configurable retry mechanism with exponential backoff
• Type Safety: Full type hints and validation
• Thread-Safe Caching: Efficient prompt caching with TTL support
• Error Handling: Comprehensive error handling and custom exceptions
• Production Ready: Designed for enterprise use with logging, metrics, and cleanup handlers

Installation

pip install langfuse-prompt-library-iauro

With Anthropic Support

pip install langfuse-prompt-library-iauro[anthropic]

Quick Start

Basic Usage

from langfuse_prompt_library import LangfuseManager

# Initialize manager (loads from environment variables)
lf = LangfuseManager()

# Call LLM with a prompt
response = lf.call_llm(
    prompt_name="customer_support_agent",
    user_input="How do I reset my password?",
    prompt_label="production",
    model="gpt-3.5-turbo"
)

Using Claude (Anthropic)

# Claude models are auto-detected
response = lf.call_llm(
    prompt_name="assistant",
    user_input="Explain quantum computing",
    model="claude-sonnet-4",
    temperature=0.7
)

Advanced Usage

from langfuse_prompt_library import LangfuseManager, LangfuseConfig

# Custom configuration
config = LangfuseConfig(
    secret_key="your-secret-key",
    public_key="your-public-key",
    host="https://cloud.langfuse.com",
    openai_api_key="your-openai-key",
    enable_caching=True,
    cache_ttl=3600,
    request_timeout=60.0
)

lf = LangfuseManager(config=config)

# Fetch prompt manually
prompt = lf.get_prompt("my_prompt", label="production")
messages = lf.compile_prompt(prompt, user_input="Hello")

# Get cache statistics
stats = lf.get_cache_stats()

# Flush traces before shutdown
lf.flush()

Prompt Management

You can create and update prompts directly via the library:

# Create a chat prompt
lf.create_prompt(
    name="my_new_prompt",
    prompt=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "{{input}}"}
    ],
    config={"model": "gpt-4", "temperature": 0.5},
    labels=["production"],
    type="chat"
)

# Create a text prompt
lf.create_prompt(
    name="text_summary",
    prompt="Summarize this: {{text}}",
    type="text"
)

# Update a prompt
lf.update_prompt(
    name="my_new_prompt",
    version=1,
    new_labels=["archived"]
)

Configuration

Set these environment variables or pass them via LangfuseConfig:

# Required
LANGFUSE_SECRET_KEY=your-secret-key
LANGFUSE_PUBLIC_KEY=your-public-key

# Optional
LANGFUSE_HOST=https://cloud.langfuse.com
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Advanced options
LANGFUSE_ENABLE_CACHING=true
LANGFUSE_CACHE_TTL=3600
LANGFUSE_REQUEST_TIMEOUT=60.0
LANGFUSE_DEBUG=false
LANGFUSE_LOG_LEVEL=INFO

API Reference

LangfuseManager

Main entry point for the library.

Methods

• call_llm(prompt_name, user_input, ...) - High-level method to fetch prompt and call LLM
• get_prompt(name, version, label, cache) - Fetch a prompt from Langfuse
• create_prompt(name, prompt, ...) - Create a new prompt (chat or text)
• update_prompt(name, version, new_labels) - Update an existing prompt version
• compile_prompt(prompt, **variables) - Compile prompt with variables
• flush() - Flush pending traces to Langfuse
• get_cache_stats() - Get cache statistics
• clear_cache() - Clear the prompt cache

LLMResponse

Response object containing:

• content - The generated text
• model - Model used
• usage - Token usage dict with 'input', 'output', 'total'
• metadata - Additional metadata
• raw_response - Raw API response

Exceptions

• LangfuseLibraryError - Base exception
• ConfigurationError - Configuration issues
• PromptNotFoundError - Prompt not found
• ProviderError - LLM provider errors
• APITimeoutError - API timeout
• RateLimitError - Rate limit exceeded
• ValidationError - Input validation failed

Examples

Error Handling

from langfuse_prompt_library import (
    LangfuseManager,
    PromptNotFoundError,
    ProviderError
)

lf = LangfuseManager()

try:
    response = lf.call_llm(
        prompt_name="nonexistent_prompt",
        user_input="Hello"
    )
except PromptNotFoundError as e:
    print(f"Prompt not found: {e}")
except ProviderError as e:
    print(f"Provider error: {e}")

Specific Prompt Version

# Use specific version
response = lf.call_llm(
    prompt_name="assistant",
    user_input="Hello",
    prompt_version=5
)

# Or use label
response = lf.call_llm(
    prompt_name="assistant",
    user_input="Hello",
    prompt_label="production"
)

Requirements

• Python >= 3.8
• langfuse >= 3.0.0
• openai >= 1.0.0
• python-dotenv >= 1.0.0
• anthropic >= 0.18.0 (optional)

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

• GitHub Issues: https://gitlab.iauro.co/hpe/backend/langfuse-prompt-library/issues
• Langfuse Documentation: https://langfuse.com/docs

Changelog

0.1.3

• Initial public release
• Support for OpenAI and Anthropic
• Automatic tracing and observability
• Thread-safe caching
• Comprehensive error handling