router-maestro 0.1.2__tar.gz

router_maestro-0.1.2/.env.example

@@ -0,0 +1,20 @@
+# Domain configuration
+DOMAIN=api.example.com
+
+# Cloudflare API token for DNS challenge
+# Generate at: https://dash.cloudflare.com/profile/api-tokens
+# Required permissions: Zone:DNS:Edit
+CF_DNS_API_TOKEN=your_cloudflare_api_token
+
+# Let's Encrypt email for certificate notifications
+ACME_EMAIL=your-email@example.com
+
+# Router-Maestro API key (generate a secure random string)
+ROUTER_MAESTRO_API_KEY=your_secure_api_key_here
+
+# Log level (DEBUG, INFO, WARNING, ERROR)
+ROUTER_MAESTRO_LOG_LEVEL=INFO
+
+# Traefik dashboard auth (generate with: htpasswd -nB admin)
+# Example: admin:$2y$05$... (user:bcrypt_hash)
+TRAEFIK_DASHBOARD_AUTH=admin:$$2y$$05$$your_bcrypt_hash_here

router_maestro-0.1.2/.gitignore

@@ -0,0 +1,103 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyc
+*.pyo
+*.pyd
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.whl
+*.tar.gz
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+.claude/
+.serena/
+*.swp
+*.swo
+*.project
+.pydevproject
+
+# UV
+.uv/
+
+# Ruff
+.ruff_cache/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Logs
+*.log
+
+# Project specific
+*.db
+*.sqlite3
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Temporary files
+*.tmp
+*.bak
+*~

router_maestro-0.1.2/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+```bash
+# Install dependencies
+uv pip install -e ".[dev]"
+
+# Run the CLI
+uv run router-maestro --help
+
+# Start the API server
+uv run router-maestro server start --port 8080
+
+# Run all tests
+uv run pytest tests/ -v
+
+# Run a single test file
+uv run pytest tests/test_auth.py -v
+
+# Run a specific test
+uv run pytest tests/test_auth.py::TestAuthStorage::test_empty_storage -v
+
+# Lint code
+uv run ruff check src/
+
+# Format code
+uv run ruff format src/
+```
+
+## Architecture Overview
+
+Router-Maestro is a multi-model routing system that exposes both OpenAI-compatible and Anthropic-compatible APIs. It routes requests to various LLM providers (GitHub Copilot, OpenAI, Anthropic, custom) with priority-based routing and fallback support.
+
+### Core Components
+
+**Router (`src/router_maestro/routing/router.py`)**
+- Central routing logic that selects providers based on model priorities
+- Handles auto-routing when model is `router-maestro`
+- Implements fallback to alternative providers on failure
+- Caches model availability from all providers
+
+**Providers (`src/router_maestro/providers/`)**
+- `BaseProvider` - Abstract base class defining the provider interface
+- `CopilotProvider` - GitHub Copilot integration with OAuth
+- `OpenAIProvider` - Native OpenAI API
+- `AnthropicProvider` - Native Anthropic API
+- `OpenAICompatibleProvider` - Custom providers with OpenAI-compatible APIs
+
+**Server (`src/router_maestro/server/`)**
+- FastAPI application with two API flavors:
+  - OpenAI-compatible: `/v1/chat/completions`, `/v1/models`
+  - Anthropic-compatible: `/v1/messages`, `/api/anthropic/v1/messages`
+- `translation.py` - Converts between Anthropic and OpenAI request/response formats
+- `schemas/` - Pydantic models for both API formats
+
+**CLI (`src/router_maestro/cli/`)**
+- Typer-based CLI with subcommands: `server`, `auth`, `model`, `context`, `config`, `stats`
+- Each subcommand in its own module registered in `main.py`
+
+### Data Flow
+
+1. Request arrives at API endpoint (OpenAI or Anthropic format)
+2. Anthropic requests are translated to internal OpenAI format
+3. Router selects provider based on model key and priorities
+4. Provider makes upstream API call
+5. Response is translated back if needed (for Anthropic API)
+
+### File Locations
+
+Configuration and data files follow XDG conventions:
+- **Config** (`~/.config/router-maestro/`): `providers.json`, `priorities.json`, `contexts.json`
+- **Data** (`~/.local/share/router-maestro/`): `auth.json`, `server.json`, `stats.db`
+
+### Model Identification
+
+Models are identified by `provider/model-id` format (e.g., `github-copilot/gpt-4o`). The special model name `router-maestro` triggers auto-routing based on priority configuration.

router_maestro-0.1.2/Dockerfile

@@ -0,0 +1,64 @@
+# Multi-stage build for minimal final image
+# Stage 1: Builder with compilation tools
+FROM python:3.11-alpine AS builder
+
+WORKDIR /app
+
+# Install build dependencies for native extensions
+# - gcc, musl-dev: C compiler for native extensions
+# - libffi-dev: Required by cffi/cryptography
+# - cargo, rust: Required by tiktoken
+RUN apk add --no-cache \
+    gcc \
+    musl-dev \
+    libffi-dev \
+    cargo \
+    rust
+
+# Install uv for fast package installation
+RUN pip install --no-cache-dir uv
+
+# Copy project files
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+# Install dependencies into a virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+RUN uv pip install --no-cache .
+
+# Stage 2: Minimal runtime image
+FROM python:3.11-alpine
+
+WORKDIR /app
+
+# Install runtime dependencies only (no build tools)
+RUN apk add --no-cache \
+    libffi \
+    curl
+
+# Copy virtual environment from builder
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Create non-root user
+RUN adduser -D -u 1000 maestro
+USER maestro
+
+# Create data and logs directories
+RUN mkdir -p /home/maestro/.local/share/router-maestro/logs \
+    && mkdir -p /home/maestro/.config/router-maestro
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# Expose default port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8080/health || exit 1
+
+# Run the server
+CMD ["router-maestro", "server", "start", "--host", "0.0.0.0", "--port", "8080"]

router_maestro-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Router-Maestro Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

router_maestro-0.1.2/Makefile

@@ -0,0 +1,140 @@
+.PHONY: help install dev test lint format clean build push run stop logs shell docker-up docker-down docker-logs buildx-setup build-multiarch dist publish publish-test
+
+# Variables
+VERSION := $(shell grep '^version' pyproject.toml | head -1 | cut -d'"' -f2)
+IMAGE_NAME := likanwen/router-maestro
+DOCKER_TAGS := -t $(IMAGE_NAME):$(VERSION) -t $(IMAGE_NAME):latest
+PLATFORMS := linux/amd64,linux/arm64
+
+# Default target
+help:
+	@echo "Router-Maestro Development Commands"
+	@echo ""
+	@echo "Development:"
+	@echo "  make install     Install dependencies"
+	@echo "  make dev         Install with dev dependencies"
+	@echo "  make test        Run tests"
+	@echo "  make lint        Run linter (ruff check)"
+	@echo "  make format      Format code (ruff format)"
+	@echo "  make clean       Clean build artifacts"
+	@echo ""
+	@echo "Build & Publish:"
+	@echo "  make dist        Build Python package (sdist + wheel)"
+	@echo "  make publish     Publish to PyPI (requires PYPI_TOKEN)"
+	@echo ""
+	@echo "Local Server:"
+	@echo "  make run         Start local server (port 8080)"
+	@echo "  make run-debug   Start with DEBUG logging"
+	@echo "  make stop        Stop local server"
+	@echo ""
+	@echo "Docker:"
+	@echo "  make build            Build Docker image ($(IMAGE_NAME):$(VERSION))"
+	@echo "  make push             Push image to Docker Hub"
+	@echo "  make buildx-setup     Setup Docker buildx for multi-arch builds"
+	@echo "  make build-multiarch  Build and push multi-arch image (amd64, arm64)"
+	@echo "  make shell            Open shell in container"
+	@echo ""
+	@echo "Docker Compose (Production):"
+	@echo "  make docker-up   Start services (Traefik + Router-Maestro)"
+	@echo "  make docker-down Stop services"
+	@echo "  make docker-logs View logs"
+	@echo ""
+	@echo "Current version: $(VERSION)"
+
+# ============== Development ==============
+
+install:
+	uv pip install .
+
+dev:
+	uv pip install -e ".[dev]"
+
+test:
+	uv run pytest tests/ -v
+
+lint:
+	uv run ruff check src/ tests/
+
+format:
+	uv run ruff format src/ tests/
+	uv run ruff check --fix src/ tests/
+
+clean:
+	rm -rf build/ dist/ *.egg-info .pytest_cache .ruff_cache src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+
+# ============== Build & Publish ==============
+
+dist: clean
+	uv build
+
+publish: dist
+	@if [ -z "$$PYPI_TOKEN" ]; then \
+		echo "Error: PYPI_TOKEN environment variable is not set"; \
+		echo "Usage: PYPI_TOKEN=your_token make publish"; \
+		exit 1; \
+	fi
+	uv publish --token $$PYPI_TOKEN
+
+publish-test: dist
+	@if [ -z "$$PYPI_TEST_TOKEN" ]; then \
+		echo "Error: PYPI_TEST_TOKEN environment variable is not set"; \
+		echo "Usage: PYPI_TEST_TOKEN=your_token make publish-test"; \
+		exit 1; \
+	fi
+	uv publish --token $$PYPI_TEST_TOKEN --publish-url https://test.pypi.org/legacy/
+
+# ============== Local Server ==============
+
+run:
+	uv run router-maestro server start --port 8080
+
+run-debug:
+	uv run router-maestro server start --port 8080 --log-level DEBUG
+
+stop:
+	@echo "Use Ctrl+C to stop the server"
+
+# ============== Docker ==============
+
+build:
+	docker build $(DOCKER_TAGS) .
+
+push: build
+	docker push $(IMAGE_NAME):$(VERSION)
+	docker push $(IMAGE_NAME):latest
+
+buildx-setup:
+	@docker buildx inspect multiarch > /dev/null 2>&1 || docker buildx create --name multiarch --use
+	docker buildx inspect --bootstrap
+
+build-multiarch: buildx-setup
+	docker buildx build --platform $(PLATFORMS) $(DOCKER_TAGS) --push .
+
+shell:
+	docker run --rm -it $(IMAGE_NAME):latest /bin/sh
+
+# ============== Docker Compose ==============
+
+docker-up:
+	docker compose up -d
+
+docker-down:
+	docker compose down
+
+docker-logs:
+	docker compose logs -f
+
+docker-restart:
+	docker compose restart router-maestro
+
+docker-pull:
+	docker compose pull
+
+# ============== Release ==============
+
+release: lint test build push
+	@echo "Released $(IMAGE_NAME):$(VERSION)"
+	git tag -a v$(VERSION) -m "Release v$(VERSION)"
+	@echo "Don't forget to push tags: git push origin v$(VERSION)"