Release v0.1.5

What's New in v0.1.5

Enhancements

• Status Command Improvements
  • Add version number display in freerouter status output
  • Clarify URL listening address - now shows (listening on 0.0.0.0) when service is accessible from external networks
  • Display version in all status scenarios (running/not running/stale PID)

UI Improvements

Before:

Status      ● Running
PID         8
URL         http://localhost:4000

After:

Status      ● Running
Version     0.1.5
PID         8
URL         http://localhost:4000 (listening on 0.0.0.0)

This makes it clearer that:

• Users can see which version is running
• The service is accessible from external IPs when 0.0.0.0 is used (not just localhost)

---

Full Changelog: v0.1.4...v0.1.5

🤖 Generated with Claude Code

Release v0.1.4 - Master Key Authentication & Docker Improvements

🔒 Security & Authentication

Master Key Authentication (NEW)

• Auto-generate secure master keys for API authentication
• Support LITELLM_MASTER_KEY environment variable for persistent keys
• Display keys in freerouter fetch, start, and status commands
• Ephemeral key mode by default (regenerates on each fetch)
• Complete test coverage with 4 passing tests

🐳 Docker Improvements

Docker Deployment

• Reorganized all Docker files into docker/ directory
• Fixed container restart loops with proper entrypoint
• Improved docker-compose.yml compatibility with 1Panel and strict parsers
• Multi-platform images (amd64, arm64) via GitHub Actions
• Images published to ghcr.io/mmdsnb/freerouter

Usage:

docker pull ghcr.io/mmdsnb/freerouter:latest
docker-compose -f docker/docker-compose.yml up -d

📦 What's Changed

• feat(security): add master_key authentication support (#770ce51, #8349101)
• feat(cli): display master_key in status command (#4f18d1d)
• refactor(security): simplify to ephemeral-only design (#770ce51)
• refactor(docker): organize files into docker/ directory (#b8fc060)
• fix(docker): container lifecycle improvements (#252cf4c, #03f9846)
• fix(docker): improve docker-compose.yml compatibility (#85039b4)
• security(gitignore): prevent secret leakage (#5cbce61)

🔧 Breaking Changes

• Existing .master_key files will no longer be read
• Users needing persistent keys should use LITELLM_MASTER_KEY env var

📊 Test Coverage

• Master key generation: ✅ 4/4 tests passing
• Integration tests: 3/3 tests (marked as optional)

Full Changelog: v0.1.3...v0.1.4

Release v0.1.3 - Request Filtering & Debug Improvements

🎉 What's New in v0.1.3

This release adds powerful request filtering and debugging features to help you monitor and troubleshoot API calls to your LLM providers.

✨ Key Features

🔍 Request Filtering

• New --requests flag: Filter logs to show only API requests/responses

  freerouter logs --requests

• Beautiful formatted output: Colored, structured display of HTTP requests and responses
• Smart URL completion: Automatically fixes incomplete URLs in logs

🐛 Debug Mode

• New --debug flag: Enable detailed HTTP logging for start and reload commands

  freerouter start --debug
  freerouter reload --debug

• Real-time request inspection: See exactly what's being sent to providers

🔧 Bug Fixes

• Fixed /v1/models endpoint returning empty list when authentication is configured
• Fixed incomplete URL display in debug logs
• Removed hardcoded master key checking logic
• Fixed environment variable interference in debug mode

📈 Improvements

• Enhanced list command to use API endpoint instead of config file
• Improved log parsing with dedicated LogStreamFilter class
• Better error handling and cleaner debug output

🧪 Testing

• 134 tests passing (100% on new modules)
• Code coverage: 80% (+3%)
• 32 new unit tests for request log parser

📚 Documentation

• Logging Guide
• View API Requests
• Debug Requests

📦 Installation

pip install --upgrade freerouter

🙏 Contributors

Special thanks to all contributors who helped make this release possible!

---

Full Changelog: v0.1.2...v0.1.3

v0.1.2 - Parallel Fetching Performance Update

FreeRouter v0.1.2 - Parallel Fetching Performance Update

🚀 Performance Improvements

Parallel Provider Fetching ⚡

• 5x performance improvement for freerouter fetch command
• Concurrent fetching from multiple providers using ThreadPoolExecutor
• Typical speedup: 2.5s → 0.5s with 5 providers
• Robust error handling: one provider failure doesn't block others

📊 Benchmark Results

Setup:
  Providers: 5
  Delay per provider: 0.5s

Results:
  Sequential time: 2.50s
  Parallel time: 0.50s
  Speedup: 4.99x ✓

Run the benchmark yourself:

python tests/benchmark_parallel_fetch.py

🧪 Testing & Quality

• 97 tests passing
• 83% code coverage
• New tests for parallel execution and error handling
• Benchmark script included

📚 Documentation

• New docs/PERFORMANCE.md - Detailed performance optimization guide
• New docs/features/parallel-fetching.md - Feature documentation
• Updated CHANGELOG.md with complete release notes

📦 Installation

pip install --upgrade freerouter

🔧 Usage

No changes required! Just run:

freerouter fetch  # Now 5x faster!

The parallel fetching happens automatically when you have multiple providers enabled.

🎯 What's Included

All features from v0.1.1 plus:

• ✅ Parallel provider fetching (NEW)
• ✅ Interactive model selector (freerouter select)
• ✅ Enhanced service management (status, reload, restore)
• ✅ Multi-provider support (OpenRouter, iFlow, Ollama, ModelScope, OAI, Static)
• ✅ Beautiful CLI with colors (rich library)
• ✅ Daemon-style service management

🔄 Upgrade from v0.1.1

Simply upgrade the package:

pip install --upgrade freerouter

No configuration changes needed. Your existing setup will work with the new parallel fetching automatically.

📝 Full Changelog

See CHANGELOG.md for complete details.

---

What's Next? Check out our ROADMAP.md for upcoming features!

v0.1.1 - Performance & Features Update

FreeRouter v0.1.1 - Performance & Features Update

🚀 New Features

Parallel Provider Fetching ⚡

• 5x performance improvement for freerouter fetch command
• Concurrent fetching from multiple providers using ThreadPoolExecutor
• Typical speedup: 2.5s → 0.5s with 5 providers
• Robust error handling: one provider failure doesn't block others

Interactive Model Selector 🎯

• New freerouter select command for choosing specific models
• Multi-select interface using questionary library
• Reduces LiteLLM startup time and memory usage
• Automatic config backup before changes

Enhanced Service Management 🛠️

• freerouter status - Detailed service status with uptime
• freerouter reload - Restart service with optional config refresh
• freerouter restore - Restore configuration from backup
• Improved logging and error messages

📈 Performance Improvements

• Parallel Fetching: 3-5x faster model discovery
• Thread-Safe: Concurrent execution with proper error isolation
• Scalable: Performance doesn't degrade with more providers

🧪 Testing & Quality

• 97 tests passing (up from 74)
• 83% code coverage (up from 79%)
• New benchmark script: tests/benchmark_parallel_fetch.py
• Comprehensive parallel execution tests

📚 Documentation

• New docs/PERFORMANCE.md - Performance optimization details
• New docs/features/parallel-fetching.md - Feature documentation
• Updated docs/ROADMAP.md - Feature tracking
• Enhanced CHANGELOG.md - Detailed version history

🐛 Bug Fixes

• All providers now disabled by default in freerouter init
• Fixed CONFIG_FILE_PATH environment variable conflict
• Improved error messages with context

📦 Installation

pip install --upgrade freerouter

🔧 Usage Examples

Parallel Fetching (Automatic)

freerouter fetch  # Now 5x faster!

Interactive Model Selection

freerouter select  # Choose specific models

Service Management

freerouter status   # Check service status
freerouter reload   # Restart service
freerouter reload -r  # Refresh config and restart

📊 Benchmark Results

Setup:
  Providers: 5
  Delay per provider: 0.5s

Results:
  Sequential time: 2.50s
  Parallel time: 0.50s
  Speedup: 4.99x ✓

🙏 Contributors

Thanks to all contributors who made this release possible!

📝 Full Changelog

See CHANGELOG.md for complete details.

---

What's Next? Check out our ROADMAP.md for upcoming features!

v0.1.0 - Initial PyPI Release

🎉 First Official Release

FreeRouter is now available on PyPI!

pip install freerouter

✨ Features

• Multi-Provider Support: OpenRouter, iFlow, ModelScope, Ollama, and any OpenAI-compatible API
• Automatic Model Discovery: Fetch available models from providers automatically
• CLI Tools: Easy-to-use commands for configuration and management
• LiteLLM Integration: Unified API interface for all providers
• Free Model Access: Support for multiple free LLM providers

📦 Supported Providers

Provider	Models	Free Quota	Status
OpenRouter	30+ models	Many free models	✅
iFlow	Multiple	All models free	✅
ModelScope	60+ models	2000 calls/day	✅
Ollama	Local models	Unlimited	✅
OAI	Any OpenAI-compatible	Varies	✅
Static	Manual config	N/A	✅

🚀 Quick Start

# Install
pip install freerouter

# Initialize configuration
freerouter init

# Edit config/providers.yaml with your API keys

# Fetch models and generate config
freerouter fetch

# Start the service
freerouter start

# List available models
freerouter list

📚 Documentation

• GitHub: https://github.com/mmdsnb/freerouter
• PyPI: https://pypi.org/project/freerouter/
• 中文文档: README_ZH.md

🔗 Links

• Package: https://pypi.org/project/freerouter/0.1.0/
• Repository: https://github.com/mmdsnb/freerouter
• Issues: https://github.com/mmdsnb/freerouter/issues

📝 Installation

pip install freerouter

Or from source:

git clone https://github.com/mmdsnb/freerouter.git
cd freerouter
pip install -e .

🙏 Acknowledgments

Built on top of LiteLLM - the amazing unified LLM API framework.