langfuse-prompt-library-iauro 0.1.3
A production-ready wrapper for Langfuse prompts and tracing with LLM integrations
License: MIT
Requires Python: >=3.8
Keywords: langfuse, llm, openai, anthropic, prompt-management, tracing, observability, langchain

# Langfuse Prompt Library

A production-ready Python wrapper for [Langfuse](https://langfuse.com/) 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

```bash
pip install langfuse-prompt-library-iauro
```
## With Anthropic Support

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

## Quick Start

### Basic Usage

```python
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)

```python
# 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

```python
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:

```python
# 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`:

```bash
# 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

```python
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

```python
# 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