runtimerouter 0.1.0__tar.gz

runtimerouter-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug Report
+about: Report a bug in RuntimeRouter
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- RuntimeRouter version:
+- Python version:
+- OS:
+- LiteLLM version (if applicable):
+
+## Minimal Reproduction
+
+```python
+from runtimerouter import AutoLLM
+
+# your code here
+```
+
+## Additional Context
+
+Logs, stack traces, or screenshots.

runtimerouter-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,34 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+Describe the feature you'd like to see.
+
+## Alternatives Considered
+
+Any alternative approaches you've thought about.
+
+## Version Target
+
+Which roadmap version does this fit?
+
+- [ ] v0.1
+- [ ] v0.2
+- [ ] v0.3
+- [ ] v0.4
+- [ ] v0.5
+- [ ] Future
+
+## Additional Context
+
+Links, mockups, or related issues.

runtimerouter-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check runtimerouter tests
+
+      - name: Type check with mypy
+        run: mypy runtimerouter
+
+      - name: Run tests
+        run: pytest --cov=runtimerouter --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false

runtimerouter-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

runtimerouter-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.*
+
+# Docs build
+site/
+
+# OS
+.DS_Store
+Thumbs.db

runtimerouter-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing to RuntimeRouter
+
+Thank you for your interest in contributing! RuntimeRouter is an open-source Python library, and we welcome contributions of all sizes.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- git
+
+### Setup
+
+```bash
+git clone https://github.com/chenyu-dev25/RuntimeRouter.git
+cd RuntimeRouter
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+### Run tests
+
+```bash
+pytest
+pytest --cov=runtimerouter --cov-report=term-missing
+```
+
+### Lint & type check
+
+```bash
+ruff check runtimerouter tests
+ruff format runtimerouter tests
+mypy runtimerouter
+```
+
+---
+
+## Project Structure
+
+```
+runtimerouter/
+├── autollm.py          # User-facing API — keep minimal
+├── router.py           # Pipeline orchestrator — no policy logic here
+├── classifier.py       # Task classification — complexity & tokens
+├── policies/           # One file per policy, extend RoutingPolicy
+├── providers/          # Model catalog metadata
+└── integrations/       # LiteLLM, future framework adapters
+```
+
+### Module boundaries (important)
+
+| Module | Responsibility | Must NOT contain |
+|--------|---------------|------------------|
+| `autollm.py` | Orchestrate route + invoke | Policy logic |
+| `router.py` | Run policy chain in order | Classification heuristics |
+| `classifier.py` | Enrich RouteContext | Model selection |
+| `policies/*` | Filter/rank candidates | LiteLLM calls |
+| `integrations/*` | Execute completions | Routing decisions |
+
+---
+
+## Adding a new Policy
+
+1. Create `runtimerouter/policies/your_policy.py`
+2. Subclass `RoutingPolicy` and implement `apply()`
+3. Register in `Router._POLICY_REGISTRY`
+4. Add tests in `tests/test_policies/`
+5. Document in `docs/architecture.md`
+
+Example skeleton:
+
+```python
+from runtimerouter.policies.base import RoutingPolicy
+from runtimerouter.types import ModelCandidate, RouteContext
+
+class MyPolicy(RoutingPolicy):
+    name = "my_policy"
+
+    def apply(
+        self,
+        context: RouteContext,
+        candidates: list[ModelCandidate],
+    ) -> list[ModelCandidate]:
+        # filter or reorder candidates
+        return candidates
+```
+
+---
+
+## Pull Request Guidelines
+
+1. **One concern per PR** — don't mix unrelated changes
+2. **Add tests** for new behavior
+3. **Update docs** if you change public API
+4. **Follow existing style** — ruff + mypy must pass
+5. **Write a clear PR description** — what, why, how to test
+
+### Commit messages
+
+Use conventional style:
+
+```
+feat: add budget-aware cost policy filtering
+fix: handle empty candidate list in Router
+docs: update Quick Start with async example
+test: add complexity policy unit tests
+```
+
+---
+
+## Reporting Issues
+
+- **Bug reports:** use the Bug Report issue template
+- **Feature requests:** use the Feature Request issue template
+- Include Python version, runtimerouter version, and minimal reproduction code
+
+---
+
+## Code of Conduct
+
+Be respectful and constructive. We're building infrastructure for the community.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

runtimerouter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RuntimeRouter 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.

runtimerouter-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: runtimerouter
+Version: 0.1.0
+Summary: Optimize the entire AI session, not just the next model call.
+Project-URL: Homepage, https://github.com/chenyu-dev25/RuntimeRouter
+Project-URL: Documentation, https://github.com/chenyu-dev25/RuntimeRouter#readme
+Project-URL: Repository, https://github.com/chenyu-dev25/RuntimeRouter
+Project-URL: Issues, https://github.com/chenyu-dev25/RuntimeRouter/issues
+Project-URL: Changelog, https://github.com/chenyu-dev25/RuntimeRouter/blob/main/ROADMAP.md
+Author: RuntimeRouter Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,langgraph,litellm,llm,model-selection,pydantic-ai,routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# RuntimeRouter
+
+> **Optimize the entire AI session, not just the next model call.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/runtimerouter.svg)](https://pypi.org/project/runtimerouter/)
+
+RuntimeRouter is a **Python-first LLM routing library** for the AI ecosystem. It sits **above** agent frameworks — LangGraph, PydanticAI, CrewAI, AutoGen — as a **Runtime Router**, not a replacement for them.
+
+You write agents with your favorite framework. RuntimeRouter decides **which model** to call, **when**, and **why** — across the full session lifecycle.
+
+---
+
+## Vision
+
+Traditional routers optimize a single inference call: given a prompt, pick the cheapest or fastest model.
+
+RuntimeRouter's long-term goal is different: **optimize the entire AI session** — model selection, cost, latency, context, caching, and privacy — as a unified runtime decision layer.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Agent Framework (LangGraph / PydanticAI / …)      │
+├─────────────────────────────────────────────────────────┤
+│  RuntimeRouter  ← session-aware routing (this library)  │
+├─────────────────────────────────────────────────────────┤
+│  LiteLLM / Provider APIs (OpenAI, Anthropic, …)         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Why RuntimeRouter?
+
+| Problem | RuntimeRouter approach |
+|---------|------------------------|
+| Hard-coding `model="gpt-4o"` everywhere | `AutoLLM()` picks the right model per request |
+| Simple tasks burning frontier-model budget | Complexity routing sends easy tasks to cheap models |
+| No visibility into routing decisions | Every call returns a `RouteDecision` with reason |
+| Framework lock-in | Framework-agnostic; works with any LiteLLM-compatible stack |
+| Proxy-only routers | Designed for **session-level** optimization (roadmap) |
+
+---
+
+## vs OpenRouter
+
+| | **OpenRouter** | **RuntimeRouter** |
+|---|----------------|-------------------|
+| **What it is** | Unified API proxy to 100+ models | Python routing **library** embedded in your app |
+| **Scope** | Single HTTP request → model | Entire AI **session** (roadmap) |
+| **Integration** | Replace your API base URL | Drop-in `AutoLLM()` or `Router` in Python code |
+| **Policies** | Provider-side routing rules | Pluggable Python **Policy** classes you own |
+| **Framework** | Language-agnostic HTTP | **Python-first**, native LangGraph/PydanticAI hooks (v0.2+) |
+
+OpenRouter is excellent as a model gateway. RuntimeRouter is a **runtime decision engine** you control in-process.
+
+---
+
+## vs Not Diamond
+
+| | **Not Diamond** | **RuntimeRouter** |
+|---|-----------------|-------------------|
+| **What it is** | Managed routing SaaS | Open-source Python library |
+| **Deployment** | Cloud API | In-process, self-hosted |
+| **Customization** | Platform-configured | Full **plugin Policy** architecture |
+| **Session scope** | Per-call model selection | Session-aware optimization (roadmap) |
+| **Cost** | SaaS pricing | Free & open (MIT) |
+
+Not Diamond provides intelligent routing as a service. RuntimeRouter gives you the same **concept** as extensible, auditable Python code.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+pip install runtimerouter
+```
+
+### Basic usage
+
+```python
+from runtimerouter import AutoLLM
+
+llm = AutoLLM()
+
+# RuntimeRouter automatically selects Claude, Gemini, DeepSeek, OpenAI, etc.
+response = llm.invoke("帮我分析整个代码仓库")
+
+print(response.choices[0].message.content)
+```
+
+### Inspect routing decisions
+
+```python
+decision = llm.route_only("Summarize this paragraph in one sentence.")
+print(decision.selected_model)  # e.g. "gpt-4o-mini"
+print(decision.reason)          # why this model was chosen
+print(decision.complexity)      # e.g. ComplexityLevel.SIMPLE
+```
+
+### Configure policies
+
+```python
+from runtimerouter import AutoLLM, RouterConfig
+
+config = RouterConfig(
+    enable_complexity_routing=True,
+    enable_cost_routing=True,
+    fallback_model="gpt-4o-mini",
+    policy_order=["complexity", "cost"],
+)
+
+llm = AutoLLM(config=config)
+```
+
+### Use Router directly (without invoking)
+
+```python
+from runtimerouter import Router, RouteContext
+
+router = Router()
+decision = router.route(RouteContext(prompt="Explain quantum entanglement"))
+print(decision.selected_model)
+```
+
+---
+
+## Architecture
+
+```
+runtimerouter/
+├── autollm.py          # User-facing entry point
+├── router.py           # Routing pipeline orchestrator
+├── classifier.py       # Task complexity & token estimation
+├── types.py            # Shared data contracts (Pydantic models)
+├── config.py           # Config loading utilities
+├── policies/           # Pluggable routing policies
+│   ├── base.py         # RoutingPolicy ABC
+│   ├── complexity.py   # Complexity-based routing
+│   └── cost.py         # Cost-based routing
+├── providers/          # Model catalog & provider metadata
+│   ├── base.py         # ModelProvider ABC
+│   └── registry.py     # ModelRegistry (default model catalog)
+└── integrations/       # External execution layers
+    └── litellm.py      # LiteLLM completion wrapper
+```
+
+**Routing pipeline (v0.1):**
+
+```
+User prompt
+    │
+    ▼
+TaskClassifier.enrich()     ← complexity, token estimate
+    │
+    ▼
+Policy chain (ordered)      ← complexity → cost
+    │
+    ▼
+RouteDecision               ← selected model + reason
+    │
+    ▼
+LiteLLMIntegration          ← execute completion
+```
+
+See [docs/architecture.md](docs/architecture.md) for module boundaries and extension points.
+
+---
+
+## Roadmap
+
+| Version | Focus |
+|---------|-------|
+| **v0.1** *(current)* | Auto Model Selection, Complexity Routing, Cost Routing, LiteLLM Integration |
+| **v0.2** | LangGraph Integration, PydanticAI Integration |
+| **v0.3** | Cache-aware Routing |
+| **v0.4** | Context-aware Routing |
+| **v0.5** | Session-aware Optimization |
+
+Full details: [ROADMAP.md](ROADMAP.md)
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/chenyu-dev25/RuntimeRouter.git
+cd RuntimeRouter
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  <strong>RuntimeRouter</strong><br>
+  Optimize the entire AI session, not just the next model call.
+</p>