Skip to content

v1.9.0 (Debugging & Transparency)

Latest
Latest

Choose a tag to compare

View all tags
@ngstcf ngstcf released this 09 Jan 10:10
· 4 commits to main since this release
v1.9.0
43fc1d2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes - v1.9.0 (Debugging & Transparency)

Release Date: January 9, 2026

🚀 What's New

This release brings comprehensive debugging and transparency features to help you monitor, debug, and optimize your LLM integrations.

✨ Highlights

  • 🔍 Request Tracking - Every request gets a unique ID for tracing through your system
  • 📊 Performance Metrics - Track timing, token usage, and costs
  • 🛠️ Enhanced Error Context - Get detailed error information with provider, model, status code, and request ID
  • ⚙️ Configuration Status - Check your setup with /api/config/status endpoint
  • 📝 Structured Logging - Configurable log levels (DEBUG/INFO/WARNING/ERROR)
  • 🐛 Debug Mode - Enable verbose logging with LLM_DEBUG=true

📦 Features

Structured Logging

  • Configurable log levels via LLM_LOG_LEVEL environment variable
  • Debug mode for verbose request/response logging
  • Proper logger initialization with formatted timestamps

Request & Response Metadata

  • LLMMetadata class tracks:

    • Request/response timing
    • Token usage
    • Retry count
    • Finish reason
    • Error messages
    • Rate limit info

  • LLMTiming class captures:

    • DNS lookup time
    • TCP connect time
    • TLS handshake time
    • Time to first token
    • Total duration
    • Provider processing time

Enhanced Error Handling

  • LLMError class provides:
    • Provider, model, status code context
    • Unique request ID for tracing
    • Error codes for categorization
    • Structured to_dict() for logging

Configuration Transparency

from llmservices import LLMConfig

status = LLMConfig.get_status()
# Returns: version, providers_configured, environment settings,
# client initialization status, circuit breaker states

API Endpoints

Endpoint Description
GET /health Enhanced health check with detailed status
GET /api/config/status Comprehensive configuration and provider status

🔧 Configuration

New Environment Variables

# Logging Configuration
LLM_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
LLM_DEBUG=false     # Enable verbose logging

📖 Usage Examples

Request Tracking

from llmservices import LLMService, LLMRequest

req = LLMRequest(provider="openai", model="gpt-4o", prompt="Hello")
print(f"Request ID: {req.request_id}")

response = LLMService.call(req)
print(f"Duration: {response.timing.total_duration_ms}ms")
print(f"Usage: {response.usage}")

Enhanced Error Handling

from llmservices import LLMError

try:
    response = LLMService.call(req)
except LLMError as e:
    print(f"Provider: {e.provider}")
    print(f"Status: {e.status_code}")
    print(f"Request ID: {e.request_id}")

Configuration Status

from llmservices import LLMConfig

status = LLMConfig.get_status()
print(f"Version: {status['version']}")
print(f"Providers: {status['providers_configured']}")

🧪 Testing

Added comprehensive test suite with 29 tests covering all debugging features:

  • Logging configuration
  • Request tracking with request_id
  • LLMMetadata and LLMTiming classes
  • LLMError with enhanced context
  • LLMConfig.get_status()
  • Integration tests

Run tests: pytest test_debugging.py -v

📝 Documentation Updates

  • Added Debugging & Transparency section to specs.html
  • Updated README.md with debugging examples and API reference
  • Updated .env.example with logging configuration
  • Updated provider documentation to include all 8 providers (OpenAI, Azure OpenAI, Anthropic, Gemini, DeepSeek, xAI/Grok, Perplexity, Ollama)

🔄 Full Changelog

Added

  • Structured logging system with configurable levels
  • LLMMetadata class for request/response tracking
  • LLMTiming class for performance metrics
  • LLMError class with enhanced error context
  • LLMConfig.get_status() for configuration transparency
  • Debug mode (LLM_DEBUG) for verbose logging
  • Enhanced /health endpoint with detailed status
  • New /api/config/status endpoint
  • request_id tracking for all requests
  • Debugging fields to LLMResponse
  • Debugging fields to LLMRequest
  • Test suite (test_debugging.py) with 29 tests

Changed

  • LLMResponse now includes: request_id, response_headers, rate_limit_remaining, timing, metadata
  • LLMRequest now includes: request_id, metadata
  • Updated provider documentation to include all 8 providers

⚠️ Important Notes

  • Production Warning: Avoid using LLM_DEBUG=true or LLM_LOG_LEVEL=DEBUG in production as they may log sensitive data including request payloads and response content.

🔗 Links

Full Changelog: v1.8.0...v1.9.0

Assets 2
Loading