v1.9.0 (Debugging & Transparency)

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

v1.8.0: xAI Grok Provider Support

v1.8.0 - xAI Grok Provider Support

🎯 Summary

This release adds xAI Grok provider support, bringing access to Grok 3, Grok 4, and grok-beta models through the unified LLM Services API. All changes are backward compatible.

✨ What's New

xAI Grok Provider

• xAI Integration: Full support for xAI's Grok models via OpenAI-compatible API
• Grok 4: Reasoning model with automatic thinking tokens
• Grok 3 & grok-beta: Standard models for general use
• OpenAI-Compatible: Leverages existing OpenAI SDK infrastructure

Configuration Updates

• Environment Variable: XAI_API_KEY for xAI authentication
• Config File: Added xAI provider configuration to llm_config.json
• Documentation: Updated .env.example and specs.html

💻 Usage Examples

Basic Grok Usage

from llmservices import LLMService, LLMRequest

# Standard model (grok-beta)
req = LLMRequest(
    provider="xai",
    model="grok-beta",
    prompt="Explain quantum computing in simple terms",
    max_tokens=500
)

response = LLMService.call(req)
print(response.content)

v1.7.0: DeepSeek Reasoning Support

Release Notes - v1.7.0 (DeepSeek Reasoning Support)

Release Date: January 2025

Summary

This release adds DeepSeek thinking tokens support and improves reasoning model handling across providers. All changes are backward compatible.

New Features

DeepSeek Reasoning Support

• DeepSeek thinking tokens: Full support for reasoning_content in DeepSeek responses
• Automatic routing: When enable_thinking=True on deepseek-chat, API automatically routes to deepseek-reasoner
• Provider-specific parameters: Added extra_body support in OpenAIProvider for provider-specific features

Enhanced Reasoning Model Support

• OpenAI reasoning_effort: Added support for reasoning_effort parameter (low/medium/high) on o1 and gpt-5 models
• Documentation: Added comprehensive reasoning examples to specs.html

Provider Differences

Provider	Thinking Mode	Configuration
OpenAI	reasoning_effort	low/medium/high levels
DeepSeek	enable_thinking	Boolean (on/off) only
Anthropic	Extended Thinking	Automatic

Technical Changes

Core Library (llmservices.py)

• OpenAIProvider.call(): Added optional extra_body parameter for provider-specific features
• DeepSeekProvider: Enhanced with comprehensive docstring explaining thinking tokens behavior
• Backward compatible: All existing code continues to work without changes

Documentation

• specs.html: Added "Method 4: Reasoning Models" example
• Updated version to v1.7.0

Usage Examples

DeepSeek with Thinking

from llmservices import LLMService, LLMRequest

req = LLMRequest(
    provider="deepseek",
    model="deepseek-chat",
    prompt="Solve this step by step: What is 12345 + 67890?",
    enable_thinking=True
)

response = LLMService.call(req)
print(f"Answer: {response.content}")
print(f"Reasoning: {response.reasoning_content}")

OpenAI with Reasoning Effort

req = LLMRequest(
    provider="openai",
    model="o1",
    prompt="Solve this step by step: What is 12345 + 67890?",
    enable_thinking=True,
    reasoning_effort="high"  # low/medium/high
)

response = LLMService.call(req)

Breaking Changes

None. All changes are backward compatible.

Upgrade Notes

No action required. Existing code will continue to work as-is.

To use new DeepSeek reasoning features:

1. Set enable_thinking=True in LLMRequest
2. Access response.reasoning_content for thinking tokens

Full Changelog

• feat: add DeepSeek thinking tokens support via extra_body (bbc20ac)
• docs: add OpenAI reasoning_effort example to specs.html (2a32f77)
• chore: update version to v1.7.0 and clean up .gitignore (8b5a5e0)
• chore: add test patterns to gitignore (b1cda1d)