Metadata-Version: 2.4
Name: aix-route
Version: 1.0.1
Summary: Aix-Route — a production routing layer that decides when an agent should reason with an LLM vs. delegate to a tool, based on the Deterministic Horizon.
Author: Dongxin Guo, Jikun Wu, Siu Ming Yiu
Author-email: Mohammad Iqbal Patan <aqbalpatan12@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Mohammad Iqbal Patan
        Copyright (c) 2026 Dongxin Guo, Jikun Wu, Siu Ming Yiu (upstream: deterministic-horizon)
        
        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.
        
Project-URL: Homepage, https://github.com/iPatan7/Aix-Route
Project-URL: Repository, https://github.com/iPatan7/Aix-Route
Project-URL: Issues, https://github.com/iPatan7/Aix-Route/issues
Project-URL: Documentation, https://github.com/iPatan7/Aix-Route/blob/main/README.md
Project-URL: Changelog, https://github.com/iPatan7/Aix-Route/blob/main/CHANGELOG.md
Keywords: chain-of-thought,reasoning,tool-use,transformer,state-tracking,inference-time-compute,llm-evaluation,agentic-reasoning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.upstream
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: omegaconf>=2.3
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: pydantic>=2.6
Requires-Dist: tenacity>=8.2
Requires-Dist: python-dotenv>=1.0
Requires-Dist: tqdm>=4.65
Requires-Dist: matplotlib>=3.7
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: requests>=2.31
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: groq
Requires-Dist: openai>=1.30; extra == "groq"
Provides-Extra: ollama
Requires-Dist: openai>=1.30; extra == "ollama"
Provides-Extra: local
Requires-Dist: torch>=2.1; extra == "local"
Requires-Dist: transformers>=4.40; extra == "local"
Requires-Dist: accelerate>=0.30; extra == "local"
Requires-Dist: peft>=0.11; extra == "local"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Requires-Dist: seaborn>=0.13; extra == "viz"
Requires-Dist: pandas>=2.0; extra == "viz"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0; extra == "notebook"
Requires-Dist: ipywidgets>=8.0; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: black>=24.3; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pre-commit>=3.6; extra == "dev"
Provides-Extra: all
Requires-Dist: openai>=1.30; extra == "all"
Requires-Dist: anthropic>=0.30; extra == "all"
Requires-Dist: matplotlib>=3.7; extra == "all"
Requires-Dist: seaborn>=0.13; extra == "all"
Requires-Dist: pandas>=2.0; extra == "all"
Requires-Dist: jupyter>=1.0; extra == "all"
Dynamic: license-file

<div align="center">

# Aix-Route

### A production routing layer that decides when an agent should reason with an LLM and when it should delegate to a tool

Built on the Deterministic Horizon result: extended chain-of-thought stops helping past a measurable depth, and beyond it tool delegation becomes *necessary*.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](https://www.python.org/downloads/)

<br/>

</div>

---

## Headline findings

| Metric | Value | Why it matters |
|---|---|---|
| Deterministic Horizon $d^*$ | **19–31 steps** | Beyond this depth, neural CoT accuracy < 50%. |
| Tool-integrated accuracy | **86–94%** | Across 8 task domains and 12 models. |
| Neural CoT accuracy | **24–42%** | The same tasks, no tools. |
| Cross-model correlation $r$ | **0.81–0.91** | Models from 6 orgs fail on the *same* instances ⇒ architectural, not training-specific. |
| Fine-tuning recovery | **+3.2%** | Theorem 4.10 predicts < 5%; the competing theory predicts > 30%. |
| Cost efficiency (tool vs. CoT) | **4.2–4.7×** | Lower cost-per-correct-solution. |
| Decoherence-model fit | **R² = 0.96** | Super-exponential decay beats linear (0.71) and exponential (0.83). |

---

## Python API

```python
from deterministic_horizon import (
    PermutationTask, generate_instances, evaluate,
    estimate_horizon, fit_decoherence_model,
    should_delegate, should_delegate_batch, delegation_decision,
    horizon_table, recommend_model,
)

# 1. Generate BFS-optimal-depth instances (depth == true BFS optimum)
task = PermutationTask(n_elements=8, seed=42)          # S_8, diameter C(8,2)=28
instances = task.generate_instances(n_instances=500, min_depth=5, max_depth=28)

# 2. Evaluate a model (needs an API key in .env)
results = evaluate(model="gpt-4o", instances=instances, conditions=["C1", "C3"])

# 3. Estimate the horizon (super-exponential fit of Theorem 4.2)
horizon = estimate_horizon(results, threshold=0.5)
print(f"d* = {horizon['d_star']:.1f}  (R² = {horizon['r_squared']:.3f})")

# 4. Route in your own agent
should_delegate(estimated_depth=horizon['d_star'] + 5, model="gpt-4o")   # → True

# 5. Plan a whole decomposition at once, or pick the right model for a depth
should_delegate_batch([5, 8, 35], model="gpt-4o")   # → [False, False, True]
recommend_model(estimated_depth=18)                  # → least over-powered model that still clears 50%
horizon_table()                                       # → per-model d* / ε₀ / L_eff rows (sorted) — the source for `dh horizons`
```

### The five experimental conditions

| Condition | Description |
|---|---|
| **C1** | Neural chain-of-thought (standard prompting) |
| **C2** | Depth-limited CoT (oracle optimal length) |
| **C3** | Tool-integrated (BFS / verifier access) |
| **C4** | Length-encouraged prompting ("take as many steps as needed") |
| **C5** | Fine-tuned on optimal-length traces |

---

## What's inside

```
deterministic-horizon/
├── src/
│   ├── policy.py        # should_delegate / delegation_decision  ← the engineering hook
│   ├── tasks/           # PermutationProbe, FSA-Sim, ArithChain, CircuitTrace, CodeProbe (+ BFS oracle)
│   ├── models/          # Uniform interface: OpenAI / Anthropic / DeepSeek / Gemini / Together / local
│   ├── metrics/         # SSJ, SFE, super-exponential horizon fit, bootstrap CIs
│   ├── analysis.py      # Figures + tables (+ plot_model_horizons comparison)
│   ├── runners.py       # High-level evaluate(...) Python API
│   └── cli.py           # evaluate | analyze | delegate | horizons 
├── configs/             # OmegaConf configs (model × task × experiment)
└── tests/               # pytest suite (smoke · metrics · tasks · policy · analysis)
```

