runtimerouter 0.1.0__py3-none-any.whl

runtimerouter/__init__.py

@@ -0,0 +1,28 @@
+"""
+RuntimeRouter — LLM routing library for the Python AI ecosystem.
+
+Optimize the entire AI session, not just the next model call.
+"""
+
+from runtimerouter.autollm import AutoLLM
+from runtimerouter.router import Router
+from runtimerouter.types import (
+    ComplexityLevel,
+    ModelCandidate,
+    RouteContext,
+    RouteDecision,
+    RouterConfig,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AutoLLM",
+    "Router",
+    "ComplexityLevel",
+    "ModelCandidate",
+    "RouteContext",
+    "RouteDecision",
+    "RouterConfig",
+    "__version__",
+]

runtimerouter/autollm.py

@@ -0,0 +1,110 @@
+"""
+AutoLLM — the primary user-facing entry point.
+
+Responsibility:
+- Accept user prompts/messages
+- Delegate routing to Router
+- Delegate execution to LiteLLM integration
+- Return unified responses
+
+Boundary: AutoLLM orchestrates; it does NOT implement routing policies.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runtimerouter.integrations.litellm import LiteLLMIntegration
+from runtimerouter.router import Router
+from runtimerouter.types import RouteContext, RouterConfig
+
+
+class AutoLLM:
+    """
+    Automatic model selection and invocation.
+
+    Usage::
+
+        from runtimerouter import AutoLLM
+
+        llm = AutoLLM()
+        response = llm.invoke("帮我分析整个代码仓库")
+
+    The router selects an appropriate model; the user never specifies one.
+    """
+
+    def __init__(
+        self,
+        config: RouterConfig | None = None,
+        router: Router | None = None,
+        integration: LiteLLMIntegration | None = None,
+    ) -> None:
+        self.config = config or RouterConfig()
+        self.router = router or Router(config=self.config)
+        self.integration = integration or LiteLLMIntegration(config=self.config)
+
+    def invoke(
+        self,
+        prompt: str,
+        *,
+        messages: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Route the request to the best model and return the LLM response.
+
+        Args:
+            prompt: User prompt text.
+            messages: Optional chat history in OpenAI message format.
+            **kwargs: Passed through to the LiteLLM integration.
+
+        Returns:
+            LiteLLM response object (shape depends on LiteLLM version).
+
+        Raises:
+            RoutingError: No suitable model found.
+            IntegrationError: LiteLLM call failed.
+        """
+        context = RouteContext(
+            prompt=prompt,
+            messages=messages or [{"role": "user", "content": prompt}],
+        )
+        decision = self.router.route(context)
+        return self.integration.completion(
+            model=decision.selected_model,
+            messages=context.messages,
+            route_decision=decision,
+            **kwargs,
+        )
+
+    async def ainvoke(
+        self,
+        prompt: str,
+        *,
+        messages: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Async variant of :meth:`invoke`."""
+        context = RouteContext(
+            prompt=prompt,
+            messages=messages or [{"role": "user", "content": prompt}],
+        )
+        decision = self.router.route(context)
+        return await self.integration.acompletion(
+            model=decision.selected_model,
+            messages=context.messages,
+            route_decision=decision,
+            **kwargs,
+        )
+
+    def route_only(self, prompt: str) -> Any:
+        """
+        Return routing decision without invoking the model.
+
+        Useful for debugging and observability.
+        """
+        context = RouteContext(
+            prompt=prompt,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return self.router.route(context)

runtimerouter/classifier.py

@@ -0,0 +1,62 @@
+"""
+TaskClassifier — enriches RouteContext before policy evaluation.
+
+Responsibility (v0.1):
+- Estimate task complexity (ComplexityLevel)
+- Optionally estimate input token count
+
+Boundary: Classification heuristics belong here, NOT in policies or Router.
+Implementation of classification algorithms is deferred to future PRs.
+"""
+
+from __future__ import annotations
+
+from runtimerouter.types import ComplexityLevel, RouteContext
+
+
+class TaskClassifier:
+    """
+    Enriches routing context with task metadata.
+
+    v0.1 ships the interface only. Concrete classification logic
+    (rule-based, embedding-based, or LLM-as-judge) will be added
+    in subsequent releases.
+    """
+
+    def enrich(self, context: RouteContext) -> RouteContext:
+        """
+        Return a copy of context with complexity and token estimates filled in.
+
+        If complexity is already set on the input context, it is preserved.
+        """
+        complexity = context.complexity or self._classify_complexity(context)
+        tokens = context.estimated_input_tokens or self._estimate_tokens(context)
+
+        return context.model_copy(
+            update={
+                "complexity": complexity,
+                "estimated_input_tokens": tokens,
+            }
+        )
+
+    def _classify_complexity(self, context: RouteContext) -> ComplexityLevel:
+        """
+        Classify task complexity.
+
+        TODO(v0.1): Implement heuristic or model-based classification.
+        Default stub returns MODERATE for all requests.
+        """
+        _ = context
+        return ComplexityLevel.MODERATE
+
+    def _estimate_tokens(self, context: RouteContext) -> int:
+        """
+        Estimate input token count from prompt/messages.
+
+        TODO(v0.1): Integrate tiktoken or LiteLLM token counter.
+        Default stub uses a rough character-based estimate.
+        """
+        text = context.prompt or ""
+        if context.messages:
+            text = " ".join(str(m.get("content", "")) for m in context.messages)
+        return max(1, len(text) // 4)

runtimerouter/config.py

@@ -0,0 +1,38 @@
+"""
+Configuration loading utilities.
+
+Responsibility: load RouterConfig from env, dict, or YAML/JSON files.
+Does NOT contain routing logic.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from runtimerouter.types import RouterConfig
+
+
+def load_config_from_env(prefix: str = "RUNTIMEROUTER_") -> RouterConfig:
+    """
+    Build RouterConfig from environment variables.
+
+    Supported variables (v0.1):
+    - RUNTIMEROUTER_FALLBACK_MODEL
+    - RUNTIMEROUTER_ENABLE_COMPLEXITY_ROUTING (true/false)
+    - RUNTIMEROUTER_ENABLE_COST_ROUTING (true/false)
+    """
+    fallback = os.getenv(f"{prefix}FALLBACK_MODEL")
+    enable_complexity = os.getenv(f"{prefix}ENABLE_COMPLEXITY_ROUTING", "true").lower() == "true"
+    enable_cost = os.getenv(f"{prefix}ENABLE_COST_ROUTING", "true").lower() == "true"
+
+    return RouterConfig(
+        fallback_model=fallback,
+        enable_complexity_routing=enable_complexity,
+        enable_cost_routing=enable_cost,
+    )
+
+
+def load_config_from_dict(data: dict[str, Any]) -> RouterConfig:
+    """Build RouterConfig from a plain dictionary."""
+    return RouterConfig.model_validate(data)

runtimerouter/exceptions.py

@@ -0,0 +1,25 @@
+"""RuntimeRouter exception hierarchy."""
+
+
+class RuntimeRouterError(Exception):
+    """Base exception for all RuntimeRouter errors."""
+
+
+class RoutingError(RuntimeRouterError):
+    """Raised when no suitable model can be selected."""
+
+
+class PolicyError(RuntimeRouterError):
+    """Raised when a routing policy fails or returns invalid output."""
+
+
+class ClassifierError(RuntimeRouterError):
+    """Raised when task complexity classification fails."""
+
+
+class ProviderError(RuntimeRouterError):
+    """Raised when a model provider is unavailable or misconfigured."""
+
+
+class IntegrationError(RuntimeRouterError):
+    """Raised when an external integration (e.g. LiteLLM) fails."""

runtimerouter/integrations/__init__.py

@@ -0,0 +1,10 @@
+"""
+External integrations — adapters for third-party execution layers.
+
+v0.1: LiteLLM integration only.
+Future: LangGraph, PydanticAI, CrewAI, AutoGen hooks.
+"""
+
+from runtimerouter.integrations.litellm import LiteLLMIntegration
+
+__all__ = ["LiteLLMIntegration"]

runtimerouter/integrations/litellm.py

@@ -0,0 +1,74 @@
+"""
+LiteLLM integration — unified model execution layer.
+
+Responsibility:
+- Execute completion/acompletion via LiteLLM
+- Attach RouteDecision metadata for observability
+- Pass through RouterConfig.litellm_kwargs
+
+Boundary: This module calls LiteLLM; it does NOT decide which model to use.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runtimerouter.exceptions import IntegrationError
+from runtimerouter.types import RouteDecision, RouterConfig
+
+
+class LiteLLMIntegration:
+    """Thin wrapper around LiteLLM for routed completions."""
+
+    def __init__(self, config: RouterConfig | None = None) -> None:
+        self.config = config or RouterConfig()
+
+    def completion(
+        self,
+        model: str,
+        messages: list[dict[str, Any]],
+        route_decision: RouteDecision | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Synchronous completion via LiteLLM.
+
+        TODO(v0.1): Wire up litellm.completion with metadata tags.
+        """
+        try:
+            import litellm
+        except ImportError as exc:
+            raise IntegrationError(
+                "litellm is required. Install with: pip install runtimerouter"
+            ) from exc
+
+        merged_kwargs = {**self.config.litellm_kwargs, **kwargs}
+        metadata = merged_kwargs.setdefault("metadata", {})
+        if route_decision is not None:
+            metadata["runtimerouter_policy"] = route_decision.policy_name
+            metadata["runtimerouter_reason"] = route_decision.reason
+
+        return litellm.completion(model=model, messages=messages, **merged_kwargs)
+
+    async def acompletion(
+        self,
+        model: str,
+        messages: list[dict[str, Any]],
+        route_decision: RouteDecision | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Async completion via LiteLLM."""
+        try:
+            import litellm
+        except ImportError as exc:
+            raise IntegrationError(
+                "litellm is required. Install with: pip install runtimerouter"
+            ) from exc
+
+        merged_kwargs = {**self.config.litellm_kwargs, **kwargs}
+        metadata = merged_kwargs.setdefault("metadata", {})
+        if route_decision is not None:
+            metadata["runtimerouter_policy"] = route_decision.policy_name
+            metadata["runtimerouter_reason"] = route_decision.reason
+
+        return await litellm.acompletion(model=model, messages=messages, **merged_kwargs)

runtimerouter/policies/__init__.py

@@ -0,0 +1,17 @@
+"""
+Routing policies — pluggable decision modules.
+
+Each policy receives an enriched RouteContext and a list of ModelCandidates,
+and returns a filtered/reordered subset. Policies are composable and ordered
+by Router according to RouterConfig.policy_order.
+"""
+
+from runtimerouter.policies.base import RoutingPolicy
+from runtimerouter.policies.complexity import ComplexityPolicy
+from runtimerouter.policies.cost import CostPolicy
+
+__all__ = [
+    "RoutingPolicy",
+    "ComplexityPolicy",
+    "CostPolicy",
+]

runtimerouter/policies/base.py

@@ -0,0 +1,40 @@
+"""
+Base routing policy interface.
+
+All policies must implement apply(). Policies are stateless by default;
+configuration is injected via RouterConfig at construction time.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from runtimerouter.types import ModelCandidate, RouteContext, RouterConfig
+
+
+class RoutingPolicy(ABC):
+    """Abstract base class for routing policies."""
+
+    name: str = "base"
+
+    def __init__(self, config: RouterConfig | None = None) -> None:
+        self.config = config or RouterConfig()
+
+    @abstractmethod
+    def apply(
+        self,
+        context: RouteContext,
+        candidates: list[ModelCandidate],
+    ) -> list[ModelCandidate]:
+        """
+        Filter or reorder model candidates based on context.
+
+        Args:
+            context: Enriched routing context from TaskClassifier.
+            candidates: Current list of viable models.
+
+        Returns:
+            Subset (or reordered list) of candidates. Empty list means
+            no model satisfies this policy's constraints.
+        """
+        ...

runtimerouter/policies/complexity.py

@@ -0,0 +1,47 @@
+"""
+ComplexityPolicy — routes requests to models matched to task complexity.
+
+Maps ComplexityLevel → preferred model tiers, e.g.:
+- TRIVIAL/SIMPLE  → fast, cheap models (gpt-4o-mini, gemini-flash)
+- MODERATE        → balanced models (gpt-4o, claude-sonnet)
+- COMPLEX/EXPERT  → frontier models (claude-opus, o1)
+
+Boundary: Complexity mapping tables live here. Classification is in classifier.py.
+"""
+
+from __future__ import annotations
+
+from runtimerouter.policies.base import RoutingPolicy
+from runtimerouter.types import ComplexityLevel, ModelCandidate, RouteContext
+
+
+# Complexity → capability tags expected on ModelCandidate.capabilities
+_COMPLEXITY_CAPABILITY_MAP: dict[ComplexityLevel, list[str]] = {
+    ComplexityLevel.TRIVIAL: ["fast", "cheap"],
+    ComplexityLevel.SIMPLE: ["fast", "cheap"],
+    ComplexityLevel.MODERATE: ["balanced"],
+    ComplexityLevel.COMPLEX: ["frontier", "reasoning"],
+    ComplexityLevel.EXPERT: ["frontier", "reasoning"],
+}
+
+
+class ComplexityPolicy(RoutingPolicy):
+    """Select models appropriate for the detected task complexity."""
+
+    name = "complexity"
+
+    def apply(
+        self,
+        context: RouteContext,
+        candidates: list[ModelCandidate],
+    ) -> list[ModelCandidate]:
+        """
+        Filter candidates by complexity-matched capabilities.
+
+        TODO(v0.1): Implement capability matching and tier fallback.
+        Current stub passes candidates through unchanged.
+        """
+        _complexity = context.complexity or ComplexityLevel.MODERATE
+        _expected = _COMPLEXITY_CAPABILITY_MAP.get(_complexity, ["balanced"])
+        _ = _expected
+        return candidates

runtimerouter/policies/cost.py

@@ -0,0 +1,41 @@
+"""
+CostPolicy — routes requests based on budget and token cost estimates.
+
+Considers:
+- context.budget_usd (per-request budget cap)
+- ModelCandidate.input_cost_per_1k / output_cost_per_1k
+- context.estimated_input_tokens
+
+Boundary: Cost calculation and ranking logic belongs here, not in Router.
+"""
+
+from __future__ import annotations
+
+from runtimerouter.policies.base import RoutingPolicy
+from runtimerouter.types import ModelCandidate, RouteContext
+
+
+class CostPolicy(RoutingPolicy):
+    """Select the most cost-effective model that meets quality constraints."""
+
+    name = "cost"
+
+    def apply(
+        self,
+        context: RouteContext,
+        candidates: list[ModelCandidate],
+    ) -> list[ModelCandidate]:
+        """
+        Filter/rank candidates by estimated cost.
+
+        TODO(v0.1): Implement cost estimation and budget filtering.
+        Current stub returns candidates sorted by input cost (None last).
+        """
+        if context.budget_usd is not None:
+            # TODO: filter candidates exceeding budget
+            pass
+
+        return sorted(
+            candidates,
+            key=lambda c: (c.input_cost_per_1k is None, c.input_cost_per_1k or float("inf")),
+        )

runtimerouter/providers/__init__.py

@@ -0,0 +1,15 @@
+"""
+Model providers — registry and provider abstractions.
+
+Providers represent upstream LLM backends (OpenAI, Anthropic, etc.).
+The registry holds ModelCandidate metadata used during routing.
+Actual API calls go through integrations/litellm.py.
+"""
+
+from runtimerouter.providers.base import ModelProvider
+from runtimerouter.providers.registry import ModelRegistry
+
+__all__ = [
+    "ModelProvider",
+    "ModelRegistry",
+]

runtimerouter/providers/base.py

@@ -0,0 +1,28 @@
+"""
+ModelProvider — abstract interface for provider-specific metadata.
+
+v0.1 uses LiteLLM as the unified execution layer; providers here supply
+model catalog metadata rather than direct API calls.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from runtimerouter.types import ModelCandidate
+
+
+class ModelProvider(ABC):
+    """Abstract provider for model catalog entries."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def list_models(self) -> list[ModelCandidate]:
+        """Return models offered by this provider."""
+        ...
+
+    @abstractmethod
+    def resolve_model_id(self, alias: str) -> str:
+        """Resolve a friendly alias to a LiteLLM model identifier."""
+        ...

runtimerouter/providers/registry.py

@@ -0,0 +1,74 @@
+"""
+ModelRegistry — central catalog of routable models.
+
+Default v0.1 catalog includes common models across major providers.
+Users can extend via RouterConfig.default_models or register() at runtime.
+"""
+
+from __future__ import annotations
+
+from runtimerouter.types import ModelCandidate
+
+_DEFAULT_MODELS: list[ModelCandidate] = [
+    ModelCandidate(
+        model_id="gpt-4o-mini",
+        provider="openai",
+        input_cost_per_1k=0.00015,
+        output_cost_per_1k=0.0006,
+        capabilities=["fast", "cheap"],
+    ),
+    ModelCandidate(
+        model_id="gpt-4o",
+        provider="openai",
+        input_cost_per_1k=0.0025,
+        output_cost_per_1k=0.01,
+        capabilities=["balanced"],
+    ),
+    ModelCandidate(
+        model_id="claude-sonnet-4-20250514",
+        provider="anthropic",
+        input_cost_per_1k=0.003,
+        output_cost_per_1k=0.015,
+        capabilities=["balanced", "reasoning"],
+    ),
+    ModelCandidate(
+        model_id="gemini/gemini-2.0-flash",
+        provider="google",
+        input_cost_per_1k=0.0001,
+        output_cost_per_1k=0.0004,
+        capabilities=["fast", "cheap"],
+    ),
+    ModelCandidate(
+        model_id="deepseek/deepseek-chat",
+        provider="deepseek",
+        input_cost_per_1k=0.00014,
+        output_cost_per_1k=0.00028,
+        capabilities=["fast", "cheap", "reasoning"],
+    ),
+]
+
+
+class ModelRegistry:
+    """In-memory registry of model candidates available for routing."""
+
+    def __init__(self, models: list[ModelCandidate] | None = None) -> None:
+        self._models: dict[str, ModelCandidate] = {}
+        source = _DEFAULT_MODELS if models is None else models
+        for model in source:
+            self.register(model)
+
+    def register(self, model: ModelCandidate) -> None:
+        """Add or overwrite a model candidate."""
+        self._models[model.model_id] = model
+
+    def get(self, model_id: str) -> ModelCandidate | None:
+        """Look up a model by ID."""
+        return self._models.get(model_id)
+
+    def list_candidates(self) -> list[ModelCandidate]:
+        """Return all registered candidates."""
+        return list(self._models.values())
+
+    def remove(self, model_id: str) -> None:
+        """Remove a model from the registry."""
+        self._models.pop(model_id, None)

runtimerouter/router.py

@@ -0,0 +1,104 @@
+"""
+Router — orchestrates the routing pipeline.
+
+Pipeline (v0.1):
+1. Classifier enriches RouteContext (complexity, token estimates)
+2. Policies filter/rank ModelCandidates in policy_order
+3. Router returns RouteDecision
+
+Boundary: Router coordinates policies; individual policies live in policies/.
+"""
+
+from __future__ import annotations
+
+from runtimerouter.classifier import TaskClassifier
+from runtimerouter.exceptions import RoutingError
+from runtimerouter.policies.base import RoutingPolicy
+from runtimerouter.policies.complexity import ComplexityPolicy
+from runtimerouter.policies.cost import CostPolicy
+from runtimerouter.providers.registry import ModelRegistry
+from runtimerouter.types import ModelCandidate, RouteContext, RouteDecision, RouterConfig
+
+
+class Router:
+    """
+    Core routing engine.
+
+    Applies an ordered chain of pluggable policies to select the best model
+    for a given request context.
+    """
+
+    _POLICY_REGISTRY: dict[str, type[RoutingPolicy]] = {
+        "complexity": ComplexityPolicy,
+        "cost": CostPolicy,
+    }
+
+    def __init__(
+        self,
+        config: RouterConfig | None = None,
+        classifier: TaskClassifier | None = None,
+        registry: ModelRegistry | None = None,
+        policies: list[RoutingPolicy] | None = None,
+    ) -> None:
+        self.config = config or RouterConfig()
+        self.classifier = classifier or TaskClassifier()
+        self.registry = registry or ModelRegistry(self.config.default_models)
+        self.policies = policies or self._build_default_policies()
+
+    def _build_default_policies(self) -> list[RoutingPolicy]:
+        """Instantiate policies according to config.policy_order."""
+        policies: list[RoutingPolicy] = []
+        for name in self.config.policy_order:
+            if name == "complexity" and not self.config.enable_complexity_routing:
+                continue
+            if name == "cost" and not self.config.enable_cost_routing:
+                continue
+            policy_cls = self._POLICY_REGISTRY.get(name)
+            if policy_cls is not None:
+                policies.append(policy_cls(config=self.config))
+        return policies
+
+    def register_policy(self, name: str, policy: RoutingPolicy) -> None:
+        """Register a custom policy at runtime."""
+        self._POLICY_REGISTRY[name] = type(policy)
+        self.policies.append(policy)
+
+    def route(self, context: RouteContext) -> RouteDecision:
+        """
+        Run the full routing pipeline and return a model selection decision.
+
+        Raises:
+            RoutingError: When no candidate survives the policy chain.
+        """
+        enriched = self.classifier.enrich(context)
+        candidates = self.registry.list_candidates()
+
+        for policy in self.policies:
+            candidates = policy.apply(enriched, candidates)
+            if not candidates:
+                break
+
+        if not candidates and self.config.fallback_model:
+            return RouteDecision(
+                selected_model=self.config.fallback_model,
+                provider="fallback",
+                reason="No candidates after policy chain; using fallback",
+                policy_name="fallback",
+            )
+
+        if not candidates:
+            raise RoutingError("No suitable model found for the given context")
+
+        selected = candidates[0]
+        return RouteDecision(
+            selected_model=selected.model_id,
+            provider=selected.provider,
+            reason=f"Selected by policy chain: {self.config.policy_order}",
+            policy_name=self.policies[-1].name if self.policies else "default",
+            complexity=enriched.complexity,
+            candidates_considered=[c.model_id for c in candidates],
+        )
+
+    def list_models(self) -> list[ModelCandidate]:
+        """Return all registered model candidates."""
+        return self.registry.list_candidates()

runtimerouter/types.py

@@ -0,0 +1,79 @@
+"""
+Core type definitions shared across RuntimeRouter modules.
+
+This module defines the data contracts between Router, Classifier, Policies,
+Providers, and Integrations. Keep it free of routing logic.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ComplexityLevel(str, Enum):
+    """Task complexity tier used by complexity-based routing policies."""
+
+    TRIVIAL = "trivial"
+    SIMPLE = "simple"
+    MODERATE = "moderate"
+    COMPLEX = "complex"
+    EXPERT = "expert"
+
+
+class ModelCandidate(BaseModel):
+    """A model that may be selected by the router."""
+
+    model_id: str = Field(..., description="LiteLLM-compatible model identifier, e.g. gpt-4o")
+    provider: str = Field(..., description="Provider name, e.g. openai, anthropic")
+    input_cost_per_1k: float | None = Field(
+        default=None, description="Optional input token cost (USD per 1K tokens)"
+    )
+    output_cost_per_1k: float | None = Field(
+        default=None, description="Optional output token cost (USD per 1K tokens)"
+    )
+    max_context_tokens: int | None = Field(default=None)
+    capabilities: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RouteContext(BaseModel):
+    """Input context passed to policies and the router for a single routing decision."""
+
+    messages: list[dict[str, Any]] = Field(default_factory=list)
+    prompt: str | None = None
+    complexity: ComplexityLevel | None = None
+    estimated_input_tokens: int | None = None
+    budget_usd: float | None = None
+    preferred_providers: list[str] = Field(default_factory=list)
+    excluded_models: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RouteDecision(BaseModel):
+    """Output of the routing pipeline: which model to use and why."""
+
+    selected_model: str
+    provider: str
+    reason: str
+    policy_name: str
+    complexity: ComplexityLevel | None = None
+    estimated_cost_usd: float | None = None
+    candidates_considered: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RouterConfig(BaseModel):
+    """Top-level configuration for Router and AutoLLM."""
+
+    default_models: list[ModelCandidate] = Field(default_factory=list)
+    enable_complexity_routing: bool = True
+    enable_cost_routing: bool = True
+    fallback_model: str | None = None
+    litellm_kwargs: dict[str, Any] = Field(default_factory=dict)
+    policy_order: list[str] = Field(
+        default_factory=lambda: ["complexity", "cost"],
+        description="Ordered list of policy names to apply",
+    )

runtimerouter-0.1.0.dist-info/METADATA

@@ -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>

runtimerouter-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+runtimerouter/__init__.py,sha256=mGOpANV1MH0-KRG10B0jUdQROyHjx-cIal-JZ7VAPyo,545
+runtimerouter/autollm.py,sha256=Fv-AxAt-GpgvexszBiiltEtX-HkRoDKSGe8ujFFsNLg,3154
+runtimerouter/classifier.py,sha256=LPwdQrPcZP3B3HWk5ARUz4xZxAP9QsbexI_AhsZksq0,2034
+runtimerouter/config.py,sha256=td2l_W_tCOISqvvigIZM0M1S4p9bPKnFR-4Z0I3lr2c,1144
+runtimerouter/exceptions.py,sha256=IwO_mUGI0OvKfxz5wugMLXucxHtDtWnzBH3hx2ILWzI,681
+runtimerouter/router.py,sha256=mtHomaXCAAYKwM5W2dSJmHbFygjkHKGimUFGaA33frM,3886
+runtimerouter/types.py,sha256=mgQElmYYphVqYjD_uiOvbQf3VL03fJ03VpJxCvFy3yQ,2703
+runtimerouter/integrations/__init__.py,sha256=ZU5vk85mWFDL8jd1ARMFvPRftU-sOtHaH4zpFqDhJi8,265
+runtimerouter/integrations/litellm.py,sha256=6bwVEMFfd0CERK9ufAVCB_mHlL_0540SisVngdXIXW4,2450
+runtimerouter/policies/__init__.py,sha256=x9SzZMOJmxteCG30L1ZrKkV1TtNE7SC-EnnPsnoEHlE,509
+runtimerouter/policies/base.py,sha256=mvaYdeH9PgdAXmM3mbe8fh17iYImDWsImPCGkKWfibI,1081
+runtimerouter/policies/complexity.py,sha256=LChQAGjGO8m96RroQ_sS81Ecsv-mGLzbEVcYW9UyfPA,1649
+runtimerouter/policies/cost.py,sha256=UCO4iRy87j4KxJ4dOjtGpYbZiX66usAa8qLDVzHgdro,1206
+runtimerouter/providers/__init__.py,sha256=-3Nq-65J_hED-DXudMUEA17ym37owdmhjy0Rz1Kz7jA,423
+runtimerouter/providers/base.py,sha256=Qi6fBInrImIDWpvoZ_HApLtrGmQr9plm3ZRX0LJpaZ8,723
+runtimerouter/providers/registry.py,sha256=7Hk5rOHMby1FwUuTv4WvCrw2lVPoSpLi45jyakzIUkY,2283
+runtimerouter-0.1.0.dist-info/METADATA,sha256=NPC3uHTnp0fLQJmKLbWMfUsGTkV5xIptSBgNXq3u44k,8774
+runtimerouter-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+runtimerouter-0.1.0.dist-info/licenses/LICENSE,sha256=lC8UQNq3Ya2RkrlXf3o7xV8FMW4ucNc_HEdekVvkcxs,1083
+runtimerouter-0.1.0.dist-info/RECORD,,

runtimerouter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

runtimerouter-0.1.0.dist-info/licenses/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.