Revos

A Python library for custom LLM APIs authentication and LangChain-based LLM tools with support for multiple LLM models and robust configuration management. In this text and examples we use definition Revos API, which is a placeholder for any custom LLM API provider requiring customisation of authentication logic, auth token management.

Why Choose Revos? 🚀

🔐 Enterprise-Grade Authentication

• Dual Authentication: OAuth 2.0 with automatic fallback mechanisms
• Automatic Token Management: Background refresh with configurable intervals
• Zero Downtime: Seamless token rotation without interrupting your application
• Security First: Built-in token validation and secure credential handling

🤖 Advanced LLM Integration

• Multiple Model Support: Use GPT-4, Claude, and other models simultaneously
• Structured Data Extraction: Convert unstructured text into structured data with Pydantic models
• LangChain Integration: Leverage the full power of LangChain ecosystem
• OpenAI-Compatible: Works with any OpenAI-compatible API through Revos

⚡ Production-Ready Features

• Observer Pattern: Automatic token updates across all components with zero duplicate requests
• Background Services: Non-blocking token refresh with asyncio support
• Efficient Token Management: Single TokenManager serves all extractors
• Robust Error Handling: Comprehensive retry logic and fallback mechanisms
• Flexible Configuration: Environment variables, YAML, JSON, and programmatic setup

🛠️ Developer Experience

• Zero Configuration: Works out of the box with sensible defaults
• Custom Prefixes: Avoid conflicts with multiple applications
• FastAPI Ready: Built-in FastAPI integration patterns
• Server mode: revos serve — OpenAI-compatible proxy for IDE agents (models, chat + SSE, usage, optional Langfuse)
• Docker / Compose: Image + optional self-hosted Langfuse profile
• Comprehensive Testing: 131+ tests ensuring reliability
• Latest Version: v0.2.2 — optional sampling params for Bedrock; model discovery CLI
• CLI: revos models lists gateway-accepted model ids; revos serve runs the local proxy

📈 Scalability & Performance

• Zero Duplicate Requests: Observer Pattern eliminates redundant token API calls
• Memory Optimized: Smart caching and resource management
• Concurrent Safe: Thread-safe operations for high-traffic applications
• Monitoring Ready: Built-in logging and observability features
• Immediate Availability: Extractors get tokens instantly upon registration

Revos vs Alternatives

Perfect For

🏢 Enterprise Applications

• High Availability: Automatic token refresh ensures zero downtime
• Multi-Tenant: Custom prefixes for different clients
• Scalable: Background services handle token management
• Monitoring: Built-in logging and observability

🤖 AI/ML Applications

• Multiple Models: Use GPT-4, Claude, and others simultaneously
• Structured Data: Extract structured data from unstructured text
• LangChain Integration: Leverage the full LangChain ecosystem
• Production Ready: Robust error handling and retry logic

🚀 FastAPI Applications

• Async Support: Non-blocking token refresh with asyncio
• Background Tasks: Automatic token management in background
• Easy Integration: Built-in FastAPI patterns and examples
• Zero Configuration: Works out of the box

📊 Data Processing Pipelines

• Batch Processing: Efficient token management for large datasets
• Concurrent Operations: Thread-safe operations for parallel processing
• Error Recovery: Comprehensive retry logic and fallback mechanisms
• Resource Optimization: Smart caching and memory management

Features

• 🔐 Revos API Authentication: Dual authentication methods with automatic fallback
• 🤖 LangChain Integration: Structured data extraction using LLMs
• ⚙️ Multiple LLM Models: Support for multiple models with different configurations
• 🔄 Token Management: Automatic token refresh with configurable intervals
• 🔄 Observer Pattern: Extractors automatically get updated tokens with zero duplicate requests
• ⚡ Efficient Architecture: Single TokenManager serves all extractors
• 🛡️ Robust Error Handling: Comprehensive retry logic and fallback mechanisms
• 🔧 Flexible Configuration: Environment variables, YAML, JSON, and programmatic configuration
• 📊 OpenAI-Compatible: Works with OpenAI-compatible APIs through Revos
• 🌍 Custom Prefixes: Support for custom environment variable prefixes to avoid conflicts
• 🧭 Model discovery: list_remote_models() and revos models CLI against GET /models

Installation

From PyPi

uv add revos
# or
pip install revos

# CLI (lists gateway model ids)
uv run revos models
# or after install:
revos models

From Source

git clone https://github.com/kavodsky/revos.git
cd revos
uv sync
# or: pip install -e .

Development Installation

git clone https://github.com/kavodsky/revos.git
cd revos
pip install -e ".[dev]"

Quick Start

1. Environment Configuration

Create a .env file with your Revos API credentials:

# Required Revos API credentials
REVOS_CLIENT_ID=your_client_id
REVOS_CLIENT_SECRET=your_client_secret
REVOS_TOKEN_URL=https://api.revos.com/token
REVOS_BASE_URL=https://api.revos.com

# Optional: Token management settings
REVOS_TOKEN_BUFFER_MINUTES=5
REVOS_TOKEN_REFRESH_INTERVAL_MINUTES=45

# LLM Models configuration
# IMPORTANT: set MODEL to an id from `revos models` / list_remote_models()
LLM_MODELS_GPT_4_MODEL=gpt-4
LLM_MODELS_GPT_4_TEMPERATURE=0.1
LLM_MODELS_GPT_4_MAX_TOKENS=2000

LLM_MODELS_CLAUDE_MODEL=<id-from-revos-models>
LLM_MODELS_CLAUDE_TEMPERATURE=0.3
LLM_MODELS_CLAUDE_MAX_TOKENS=4000

Discover valid gateway model identifiers before configuring:

revos models
# or
uv run revos models --env-file .env

from revos import list_remote_models

print(list_remote_models())

2. Basic Usage

from revos import get_langchain_extractor
from pydantic import BaseModel

# Define your data schema
class PersonInfo(BaseModel):
    name: str
    age: int
    occupation: str
    location: str

# Create an extractor (automatically handles token acquisition)
extractor = get_langchain_extractor("gpt-4")

# Extract structured data
result = extractor.extract(
    text="John Doe is 30 years old and works as a software engineer in San Francisco.",
    schema=PersonInfo
)

print(result)  # PersonInfo(name="John Doe", age=30, occupation="software engineer", location="San Francisco")

3. Token Management with Observer Pattern

from revos import TokenManager, get_langchain_extractor
import asyncio

# Create token manager with background refresh
token_manager = TokenManager(refresh_interval_minutes=45)

# Or with custom settings (refresh interval taken from config)
token_manager = TokenManager(settings_instance=config)

# Create extractors (they automatically register for token updates)
# Extractors get tokens immediately via Observer Pattern - no duplicate requests!
extractor1 = get_langchain_extractor("gpt-4")  # Gets token instantly
extractor2 = get_langchain_extractor("claude-4")  # Gets token instantly

# Start background token refresh service
# All extractors automatically get updated tokens via Observer Pattern!
async def main():
    await token_manager.start_background_service()
    # Your application code here
    # Extractors automatically use fresh tokens with zero duplicate requests
    await token_manager.stop_background_service()

asyncio.run(main())

4. Observer Pattern Benefits

The Observer Pattern implementation provides several key advantages:

# ✅ EFFICIENT: Single TokenManager serves all extractors
token_manager = TokenManager(settings_instance=config)

# ✅ IMMEDIATE: Extractors get tokens instantly upon creation
extractor1 = get_langchain_extractor("gpt-4")  # Token provided immediately
extractor2 = get_langchain_extractor("claude-4")  # Token provided immediately

# ✅ AUTOMATIC: All extractors get updated tokens automatically
# No duplicate API calls, no manual token management needed!

Key Benefits:

• Zero Duplicate Requests: Extractors don't make their own token requests
• Immediate Availability: Extractors are ready to use instantly
• Automatic Updates: All extractors get fresh tokens automatically
• Resource Efficient: Single TokenManager handles all token operations
• Thread Safe: Concurrent operations with proper synchronization

Server mode (IDE agents)

revos serve --env-file=.env
# docker compose up -d --build

Point OpenCode / Cline / Continue at http://127.0.0.1:8000/v1.
Docs: Server mode · Docker · Langfuse · DOCKERHUB.md

Configuration Options

Environment Variables

Custom Environment Variable Prefixes

If you need to use different prefixes (e.g., to avoid conflicts), you can use custom prefixes:

from revos import create_config_with_prefixes

# Create configuration with custom prefixes
config = create_config_with_prefixes(
    revo_prefix="MYAPP_",
    llm_prefix="MYAPP_LLM_",
    logging_prefix="MYAPP_LOG_",
    token_prefix="MYAPP_TOKEN_"
)

# Use with custom settings
token_manager = TokenManager(settings_instance=config)
extractor = get_langchain_extractor("gpt-4", settings_instance=config)

Documentation

• LLM Models Configuration - Detailed guide for configuring multiple LLM models
• FastAPI Integration - FastAPI examples and patterns
• Custom Prefixes Guide - Using custom environment variable prefixes
• Token Management - Advanced token management and background services
• Configuration Reference - Complete configuration options

Examples

• Basic Usage - Simple extraction examples
• FastAPI RUMBA Example - Complete FastAPI application
• Multiple Models - Working with multiple LLM models
• Custom Prefixes - Custom environment variable prefixes

Development

Latest Improvements (v0.2.0)

• list_remote_models() / revos models: Discover ids the gateway actually accepts
• Clearer invalid-model errors: include tried model + live /models list
• Typer CLI: revos models, revos configured-models, revos version
• Removed legacy LLMConfig: configure models only via llm_models / LLM_MODELS_*
• Example defaults: marked EXAMPLE ONLY; dropped guessed claude-4-sonnet default

See CHANGELOG.

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_background_custom_settings.py -v

# Run with coverage
pytest --cov=revos

Building Documentation

make docs-serve   # http://127.0.0.1:8000
make docs         # build into site/

Or: uv run mkdocs serve / uv run mkdocs build.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For questions, issues, or contributions, please visit our GitHub repository.