codex-router 0.1.0__tar.gz

codex_router-0.1.0/LICENSE

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

codex_router-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: codex-router
+Version: 0.1.0
+Summary: Intelligent routing and orchestration for multi-model AI coding agents
+Author-email: Intellirim <hello@intellirim.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Intellirim/codex-router
+Project-URL: Issues, https://github.com/Intellirim/codex-router/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: anthropic>=0.18.0
+Requires-Dist: openai>=1.12.0
+Requires-Dist: google-generativeai>=0.3.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# codex-router
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**Intelligent routing and orchestration for multi-model AI coding agents**
+
+`codex-router` is a lightweight CLI tool that automatically routes coding tasks to the best available AI model (Claude, GPT, Gemini, or local) based on task complexity, cost, and availability. Manage parallel agent sessions, track token usage and costs across providers, and get unified output streaming. Makes it trivial to leverage multiple AI models without manual context switching.
+
+## Features
+
+- **Smart routing**: Analyzes task complexity and routes to optimal model (fast models for simple tasks, frontier models for complex ones)
+- **Parallel orchestration**: Run multiple AI agents on different subtasks simultaneously with unified output
+- **Cost tracking**: Real-time token usage and cost monitoring across all providers (Claude, OpenAI, Gemini)
+- **Auto-fallback**: Automatically switches to alternative model if primary hits rate limits or errors
+- **Unified config**: Single configuration file for all API keys and preferences
+- **Session management**: Save and resume multi-agent sessions with full context
+- **ASCII-only output**: Cross-platform terminal compatibility (Windows, macOS, Linux)
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install codex-router
+```
+
+## Quick Start
+
+Configure your API keys:
+
+```bash
+codex-router config --set anthropic_api_key YOUR_CLAUDE_KEY
+codex-router config --set openai_api_key YOUR_OPENAI_KEY
+codex-router config --set google_api_key YOUR_GEMINI_KEY
+```
+
+Set default preferences:
+
+```bash
+codex-router config --set-default-model claude
+```
+
+## Usage Examples
+
+Run a single coding task with intelligent model selection:
+
+```bash
+codex-router task "refactor auth module"
+```
+
+Output:
+```
+[Router] Analyzing task complexity...
+[Router] Task complexity: HIGH -> Selected model: claude-opus-4
+[Agent-1] Reading auth module...
+[Agent-1] Identified 3 refactoring opportunities
+[Agent-1] Applying changes...
+[Agent-1] DONE - 2,450 tokens used ($0.073)
+```
+
+Run parallel agents on multiple subtasks:
+
+```bash
+codex-router task "add unit tests" --parallel 2
+```
+
+Output:
+```
+[Router] Splitting task into 2 parallel agents
+[Agent-1] Testing user authentication flow...
+[Agent-2] Testing database connections...
+[Agent-1] Created 5 test cases
+[Agent-2] Created 3 test cases
+[Router] DONE - Total: 3,120 tokens ($0.094)
+```
+
+Constrain budget for cost control:
+
+```bash
+codex-router task "add unit tests" --model claude --budget 0.50
+```
+
+Check usage statistics:
+
+```bash
+codex-router status --show-costs
+```
+
+Output:
+```
+Token Usage Summary (Last 7 Days)
+---------------------------------
+Provider    | Tokens  | Cost
+---------------------------------
+Claude      | 45,230  | $1.35
+OpenAI      | 12,500  | $0.25
+Gemini      | 8,900   | $0.00
+---------------------------------
+Total                 | $1.60
+```
+
+## Configuration
+
+Configuration is stored in `~/.codex-router/config.yaml`. You can edit it manually or use the CLI:
+
+```bash
+# Set API keys
+codex-router config --set anthropic_api_key YOUR_KEY
+codex-router config --set openai_api_key YOUR_KEY
+codex-router config --set google_api_key YOUR_KEY
+
+# Set default model
+codex-router config --set-default-model gpt-4
+
+# Set budget limits
+codex-router config --set daily_budget 5.00
+```
+
+## How It Works
+
+1. **Task Analysis**: The router analyzes your task description for complexity, required context, and estimated token usage
+2. **Model Selection**: Based on complexity and your preferences, selects the optimal model (e.g., GPT-3.5 for simple tasks, Claude Opus for complex refactoring)
+3. **Execution**: Sends the task to the selected provider's API with proper context and streaming
+4. **Cost Tracking**: Records token usage and costs in a local database for monitoring
+5. **Auto-Fallback**: If the primary model fails (rate limit, timeout), automatically retries with an alternative model
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/Intellirim/codex-router.git
+cd codex-router
+```
+
+Install in development mode:
+
+```bash
+pip install -e .
+```
+
+Run tests:
+
+```bash
+pytest tests/
+```
+
+## License
+
+MIT License - Copyright (c) 2026 Intellirim
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.

codex_router-0.1.0/README.md

@@ -0,0 +1,154 @@
+# codex-router
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**Intelligent routing and orchestration for multi-model AI coding agents**
+
+`codex-router` is a lightweight CLI tool that automatically routes coding tasks to the best available AI model (Claude, GPT, Gemini, or local) based on task complexity, cost, and availability. Manage parallel agent sessions, track token usage and costs across providers, and get unified output streaming. Makes it trivial to leverage multiple AI models without manual context switching.
+
+## Features
+
+- **Smart routing**: Analyzes task complexity and routes to optimal model (fast models for simple tasks, frontier models for complex ones)
+- **Parallel orchestration**: Run multiple AI agents on different subtasks simultaneously with unified output
+- **Cost tracking**: Real-time token usage and cost monitoring across all providers (Claude, OpenAI, Gemini)
+- **Auto-fallback**: Automatically switches to alternative model if primary hits rate limits or errors
+- **Unified config**: Single configuration file for all API keys and preferences
+- **Session management**: Save and resume multi-agent sessions with full context
+- **ASCII-only output**: Cross-platform terminal compatibility (Windows, macOS, Linux)
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install codex-router
+```
+
+## Quick Start
+
+Configure your API keys:
+
+```bash
+codex-router config --set anthropic_api_key YOUR_CLAUDE_KEY
+codex-router config --set openai_api_key YOUR_OPENAI_KEY
+codex-router config --set google_api_key YOUR_GEMINI_KEY
+```
+
+Set default preferences:
+
+```bash
+codex-router config --set-default-model claude
+```
+
+## Usage Examples
+
+Run a single coding task with intelligent model selection:
+
+```bash
+codex-router task "refactor auth module"
+```
+
+Output:
+```
+[Router] Analyzing task complexity...
+[Router] Task complexity: HIGH -> Selected model: claude-opus-4
+[Agent-1] Reading auth module...
+[Agent-1] Identified 3 refactoring opportunities
+[Agent-1] Applying changes...
+[Agent-1] DONE - 2,450 tokens used ($0.073)
+```
+
+Run parallel agents on multiple subtasks:
+
+```bash
+codex-router task "add unit tests" --parallel 2
+```
+
+Output:
+```
+[Router] Splitting task into 2 parallel agents
+[Agent-1] Testing user authentication flow...
+[Agent-2] Testing database connections...
+[Agent-1] Created 5 test cases
+[Agent-2] Created 3 test cases
+[Router] DONE - Total: 3,120 tokens ($0.094)
+```
+
+Constrain budget for cost control:
+
+```bash
+codex-router task "add unit tests" --model claude --budget 0.50
+```
+
+Check usage statistics:
+
+```bash
+codex-router status --show-costs
+```
+
+Output:
+```
+Token Usage Summary (Last 7 Days)
+---------------------------------
+Provider    | Tokens  | Cost
+---------------------------------
+Claude      | 45,230  | $1.35
+OpenAI      | 12,500  | $0.25
+Gemini      | 8,900   | $0.00
+---------------------------------
+Total                 | $1.60
+```
+
+## Configuration
+
+Configuration is stored in `~/.codex-router/config.yaml`. You can edit it manually or use the CLI:
+
+```bash
+# Set API keys
+codex-router config --set anthropic_api_key YOUR_KEY
+codex-router config --set openai_api_key YOUR_KEY
+codex-router config --set google_api_key YOUR_KEY
+
+# Set default model
+codex-router config --set-default-model gpt-4
+
+# Set budget limits
+codex-router config --set daily_budget 5.00
+```
+
+## How It Works
+
+1. **Task Analysis**: The router analyzes your task description for complexity, required context, and estimated token usage
+2. **Model Selection**: Based on complexity and your preferences, selects the optimal model (e.g., GPT-3.5 for simple tasks, Claude Opus for complex refactoring)
+3. **Execution**: Sends the task to the selected provider's API with proper context and streaming
+4. **Cost Tracking**: Records token usage and costs in a local database for monitoring
+5. **Auto-Fallback**: If the primary model fails (rate limit, timeout), automatically retries with an alternative model
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/Intellirim/codex-router.git
+cd codex-router
+```
+
+Install in development mode:
+
+```bash
+pip install -e .
+```
+
+Run tests:
+
+```bash
+pytest tests/
+```
+
+## License
+
+MIT License - Copyright (c) 2026 Intellirim
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.

codex_router-0.1.0/codex_router/__init__.py

@@ -0,0 +1,11 @@
+"""codex-router: Intelligent routing and orchestration for multi-model AI coding agents."""
+
+__version__ = "0.1.0"
+__author__ = "Intellirim"
+__license__ = "MIT"
+
+from codex_router.router import TaskRouter
+from codex_router.config import Config
+from codex_router.tracker import CostTracker
+
+__all__ = ["TaskRouter", "Config", "CostTracker", "__version__"]

codex_router-0.1.0/codex_router/cli.py

@@ -0,0 +1,134 @@
+"""CLI entry point for codex-router."""
+
+import click
+from pathlib import Path
+from codex_router import __version__
+from codex_router.config import Config
+from codex_router.router import TaskRouter
+from codex_router.orchestrator import Orchestrator
+from codex_router.tracker import CostTracker
+from codex_router.display import Display
+
+
+@click.group()
+@click.version_option(version=__version__)
+def main():
+    """Intelligent routing and orchestration for multi-model AI coding agents."""
+    pass
+
+
+@main.command()
+@click.argument("description")
+@click.option("--model", "-m", help="Force specific model (claude, gpt-4, gemini)")
+@click.option("--parallel", "-p", type=int, default=1, help="Number of parallel agents")
+@click.option("--budget", "-b", type=float, help="Maximum budget in USD")
+def task(description: str, model: str, parallel: int, budget: float):
+    """Execute a coding task with intelligent routing."""
+    try:
+        config = Config.load()
+    except FileNotFoundError:
+        click.echo("Error: Config not found. Run 'codex-router config --init' first.", err=True)
+        raise SystemExit(1)
+
+    display = Display()
+    tracker = CostTracker()
+
+    if budget and budget <= 0:
+        click.echo("Error: Budget must be positive", err=True)
+        raise SystemExit(1)
+
+    router = TaskRouter(config)
+
+    if parallel > 1:
+        display.info(f"Splitting task into {parallel} parallel agents")
+        orchestrator = Orchestrator(config, tracker)
+        try:
+            result = orchestrator.run_parallel(description, parallel, model, budget)
+            display.success(f"DONE - Total: {result['total_tokens']} tokens (${result['total_cost']:.3f})")
+        except Exception as e:
+            display.error(f"Orchestration failed: {str(e)}")
+            raise SystemExit(2)
+    else:
+        display.info("Analyzing task complexity...")
+        try:
+            selected_model = router.select_model(description, force_model=model)
+            display.info(f"Selected model: {selected_model}")
+
+            result = router.execute_task(description, selected_model, budget)
+            tracker.record_usage(selected_model, result["tokens"], result["cost"])
+
+            display.show_result(result["output"])
+            display.success(f"DONE - {result['tokens']} tokens (${result['cost']:.3f})")
+        except ValueError as e:
+            display.error(str(e))
+            raise SystemExit(1)
+        except Exception as e:
+            display.error(f"Task execution failed: {str(e)}")
+            raise SystemExit(2)
+
+
+@main.command()
+@click.option("--show-costs", is_flag=True, help="Show cost breakdown by provider")
+@click.option("--days", "-d", type=int, default=7, help="Number of days to show")
+def status(show_costs: bool, days: int):
+    """Show usage statistics and costs."""
+    tracker = CostTracker()
+    display = Display()
+
+    try:
+        stats = tracker.get_stats(days)
+    except Exception as e:
+        click.echo(f"Error: Failed to load statistics: {str(e)}", err=True)
+        raise SystemExit(2)
+
+    if show_costs:
+        display.show_cost_table(stats, days)
+    else:
+        click.echo(f"Total requests (last {days} days): {stats['total_requests']}")
+        click.echo(f"Total tokens: {stats['total_tokens']}")
+        click.echo(f"Total cost: ${stats['total_cost']:.2f}")
+
+
+@main.command()
+@click.option("--set", "set_value", nargs=2, metavar="KEY VALUE", help="Set config value")
+@click.option("--set-default-model", metavar="MODEL", help="Set default model")
+@click.option("--init", is_flag=True, help="Initialize config with defaults")
+def config(set_value: tuple, set_default_model: str, init: bool):
+    """Manage configuration."""
+    if init:
+        try:
+            Config.init_default()
+            click.echo("Config initialized at ~/.codex-router/config.yaml")
+        except Exception as e:
+            click.echo(f"Error: Failed to initialize config: {str(e)}", err=True)
+            raise SystemExit(2)
+        return
+
+    try:
+        cfg = Config.load()
+    except FileNotFoundError:
+        click.echo("Error: Config not found. Run 'codex-router config --init' first.", err=True)
+        raise SystemExit(1)
+
+    if set_value:
+        key, value = set_value
+        try:
+            cfg.set(key, value)
+            cfg.save()
+            click.echo(f"Set {key} = {value}")
+        except ValueError as e:
+            click.echo(f"Error: {str(e)}", err=True)
+            raise SystemExit(1)
+
+    if set_default_model:
+        valid_models = ["claude", "gpt-4", "gpt-3.5", "gemini"]
+        if set_default_model not in valid_models:
+            click.echo(f"Error: Invalid model. Choose from: {', '.join(valid_models)}", err=True)
+            raise SystemExit(1)
+        cfg.set("default_model", set_default_model)
+        cfg.save()
+        click.echo(f"Set default_model = {set_default_model}")
+
+
+if __name__ == "__main__":
+    main()

codex_router-0.1.0/codex_router/config.py

@@ -0,0 +1,143 @@
+"""Configuration management for API keys, defaults, and budgets."""
+
+import yaml
+from pathlib import Path
+from typing import Any, Optional
+
+
+class Config:
+    """Manage configuration file with API keys and preferences."""
+
+    DEFAULT_CONFIG = {
+        "anthropic_api_key": "",
+        "openai_api_key": "",
+        "google_api_key": "",
+        "default_model": "claude",
+        "daily_budget": 10.0,
+        "max_parallel_agents": 5
+    }
+
+    def __init__(self, config_path: Path, data: dict):
+        """Initialize configuration.
+
+        Args:
+            config_path: Path to config file
+            data: Configuration dictionary
+        """
+        self.config_path = config_path
+        self.data = data
+
+    @classmethod
+    def load(cls, config_path: Optional[str] = None) -> "Config":
+        """Load configuration from file.
+
+        Args:
+            config_path: Optional custom config path
+
+        Returns:
+            Config instance
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+        """
+        if config_path:
+            path = Path(config_path)
+        else:
+            path = Path.home() / ".codex-router" / "config.yaml"
+
+        if not path.exists():
+            raise FileNotFoundError(f"Config not found: {path}")
+
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML in config: {str(e)}")
+
+        if not isinstance(data, dict):
+            raise ValueError("Config must be a YAML dictionary")
+
+        return cls(path, data)
+
+    @classmethod
+    def init_default(cls, config_path: Optional[str] = None) -> "Config":
+        """Initialize config with default values.
+
+        Args:
+            config_path: Optional custom config path
+
+        Returns:
+            New Config instance
+        """
+        if config_path:
+            path = Path(config_path)
+        else:
+            path = Path.home() / ".codex-router" / "config.yaml"
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = cls.DEFAULT_CONFIG.copy()
+        path.write_text(yaml.dump(data, default_flow_style=False), encoding="utf-8")
+
+        return cls(path, data)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get configuration value.
+
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Configuration value
+        """
+        return self.data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set configuration value.
+
+        Args:
+            key: Configuration key
+            value: Value to set
+
+        Raises:
+            ValueError: If key is invalid
+        """
+        valid_keys = {
+            "anthropic_api_key", "openai_api_key", "google_api_key",
+            "default_model", "daily_budget", "max_parallel_agents"
+        }
+
+        if key not in valid_keys:
+            raise ValueError(f"Invalid config key: {key}. Valid keys: {', '.join(valid_keys)}")
+
+        if key == "daily_budget" or key == "max_parallel_agents":
+            try:
+                value = float(value) if key == "daily_budget" else int(value)
+            except ValueError:
+                raise ValueError(f"{key} must be a number")
+
+            if value < 0:
+                raise ValueError(f"{key} must be non-negative")
+
+        self.data[key] = value
+
+    def save(self) -> None:
+        """Save configuration to file."""
+        self.config_path.write_text(
+            yaml.dump(self.data, default_flow_style=False),
+            encoding="utf-8"
+        )
+
+    def validate(self) -> bool:
+        """Check if at least one API key is configured.
+
+        Returns:
+            True if valid, False otherwise
+        """
+        api_keys = [
+            self.data.get("anthropic_api_key"),
+            self.data.get("openai_api_key"),
+            self.data.get("google_api_key")
+        ]
+
+        return any(key and key.strip() for key in api_keys)