Metadata-Version: 2.4
Name: iqueue
Version: 0.2.0
Summary: iQueue — intent-stabilized multi-queue reasoning with expandable highway lanes and multi-model steering
Author: iQueue contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/ehallford11714/iQueue
Project-URL: Documentation, https://github.com/ehallford11714/iQueue/blob/main/docs/API.md
Project-URL: Repository, https://github.com/ehallford11714/iQueue
Project-URL: Issues, https://github.com/ehallford11714/iQueue/issues
Keywords: iqueue,agents,multi-queue,highway,steering,rag,vae,knn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: networkx>=3.2
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: local
Requires-Dist: torch>=2.1.0; extra == "local"
Requires-Dist: transformers>=4.40.0; extra == "local"
Requires-Dist: huggingface_hub>=0.23.0; extra == "local"
Requires-Dist: peft>=0.11.0; extra == "local"
Requires-Dist: accelerate>=0.30.0; extra == "local"
Requires-Dist: psutil>=5.9.0; extra == "local"
Provides-Extra: ui
Requires-Dist: streamlit>=1.32.0; extra == "ui"
Requires-Dist: psutil>=5.9.0; extra == "ui"
Provides-Extra: api
Requires-Dist: fastapi>=0.110.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "api"
Requires-Dist: pydantic>=2.0.0; extra == "api"
Provides-Extra: qlora
Requires-Dist: torch>=2.1.0; extra == "qlora"
Requires-Dist: transformers>=4.40.0; extra == "qlora"
Requires-Dist: huggingface_hub>=0.23.0; extra == "qlora"
Requires-Dist: peft>=0.11.0; extra == "qlora"
Requires-Dist: accelerate>=0.30.0; extra == "qlora"
Requires-Dist: bitsandbytes>=0.43.0; extra == "qlora"
Provides-Extra: frontier
Provides-Extra: integrations
Requires-Dist: langgraph>=0.2.0; extra == "integrations"
Requires-Dist: crewai>=0.80.0; extra == "integrations"
Requires-Dist: smolagents>=1.0.0; extra == "integrations"
Requires-Dist: dspy>=2.5.0; extra == "integrations"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: torch>=2.1.0; extra == "all"
Requires-Dist: transformers>=4.40.0; extra == "all"
Requires-Dist: huggingface_hub>=0.23.0; extra == "all"
Requires-Dist: peft>=0.11.0; extra == "all"
Requires-Dist: accelerate>=0.30.0; extra == "all"
Requires-Dist: psutil>=5.9.0; extra == "all"
Requires-Dist: streamlit>=1.32.0; extra == "all"
Requires-Dist: fastapi>=0.110.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "all"
Requires-Dist: pydantic>=2.0.0; extra == "all"
Requires-Dist: langgraph>=0.2.0; extra == "all"
Requires-Dist: crewai>=0.80.0; extra == "all"
Requires-Dist: smolagents>=1.0.0; extra == "all"
Requires-Dist: dspy>=2.5.0; extra == "all"
Requires-Dist: mcp>=1.2.0; extra == "all"
Dynamic: license-file

# iQueue

<p align="center">
  <img src="docs/assets/iqueue-logo.png" alt="iQueue logo" width="280"/>
</p>

**Intent-stabilized multi-queue reasoning for agentic systems.**

iQueue is an open-source control plane for agentic AI: bidirectional expandable highway lanes, rotator multi-queues, pivot-anchored embeddings, KNN + VAE ranking, lightweight + **large-model steering**, and a γ discount for veering off-highway. Scored queues serialize to markdown contexts for future runs.

## Multi-model support

| Provider | Mode | Notes |
|----------|------|-------|
| **OpenAI** | frontier API | `sol` / `terra` / `luna` → GPT-5.6 (`gpt-5.6-sol`, …) |
| **Anthropic** | frontier API | `opus5` / `fable` / `sonnet5` → Claude 5 family |
| **Google** | frontier API | `gemini-3.6-flash` |
| **Qwen** | DashScope / local | cloud `qwen-plus` or HF/Ollama |
| **OpenRouter** | gateway | one key → Sol/Opus/etc. |
| **mock (offline)** | local | **auto-downloads HF Qwen**, else deterministic text |

```python
import iqueue

iqueue.configure(
    openai_api_key="sk-...",
    qwen_api_key="sk-...",
    ollama_base_url="http://127.0.0.1:11434",
)
client = iqueue.get_client("qwen")
```

See [docs/MODELS.md](docs/MODELS.md). Copy `config/models.example.json` → `config/models.local.json` for local keys.

## Quick start

```bash
git clone https://github.com/ehallford11714/iQueue.git
cd iQueue
python -m venv .venv
# Windows: .venv\Scripts\activate
pip install -r requirements.txt
set IQUEUE_SKIP_HF_DOWNLOAD=1
python -m src.tutorial_demo        # progressive tutorial demo (or: iqueue-tutorial)
python -m src.demo
python -m src.highway.demo
python -m src.highway.stack_demo   # stacked levels + trainable velocities
python -m src.models.demo          # dedicated multi-provider + LM steering
python -m src.experiments.train_eval   # proper train/eval loop + metrics
python -m src.experiments.run_gamma_ablation
```

**Tutorial:** [docs/TUTORIAL.md](docs/TUTORIAL.md) — install, core APIs, config, learn-the-road, and copy-paste use cases (diagnosis, incident, research, planning, policy, stack tiers).

**Lane Engineering:** [docs/LANE_ENGINEERING.md](docs/LANE_ENGINEERING.md) — designing and operating expandable `LaneQueue`s (agents, tasks, fill/drain, kinds, stack, policy).

**Orchestration + browser:** [docs/ORCHESTRATION.md](ORCHESTRATION.md) — harness pipeline (`iqueue-harness`), soft `/v1/orchestration` + MCP `iqueue_orchestrate`, and `web/` IndexedDB / WebGPU / Wasm demo.

### Streamlit demo (variable config + learn the road)

```bash
pip install -e ".[ui,local]"   # streamlit + torch/transformers/peft
# optional CUDA 4-bit: pip install -e ".[qlora]"
streamlit run app.py
```

All knobs (`highway.*`, `train.*`, `qlora.*`, `policy.*`, `stack.*`, `models.*`, `trace.*`) are editable in the sidebar or via JSON (`config/iqueue.example.json`).

```bash
# CLI trace with variables
set IQUEUE_SKIP_HF_DOWNLOAD=1
python -m src.trace_runner --config config/iqueue.example.json
# light QLoRA + SFT while learning the road:
python -m src.trace_runner --config config/iqueue.example.json --qlora
```

### HTTP API suite (FastAPI)

```bash
pip install -e ".[api]"
set IQUEUE_SKIP_HF_DOWNLOAD=1
python -m src.api --port 8765
# docs: http://127.0.0.1:8765/docs
```

Route groups: `/health`, `/config`, `/hardware`, `/highway`, `/stack`, `/policy`,
`/rotator`, `/ranking`, `/pivotgraph`, `/models`, `/train`, `/trace`, `/cases`,
`/integrations`.

### MCP server (Cursor / agent hosts)

```bash
pip install -e ".[mcp]"
set IQUEUE_SKIP_HF_DOWNLOAD=1
python -m src.mcp_server          # or: iqueue-mcp
```

Register in Cursor MCP config (`cwd` = this repo):

```json
{
  "mcpServers": {
    "iqueue": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "<path-to-iQueue>",
      "env": { "IQUEUE_SKIP_HF_DOWNLOAD": "1" }
    }
  }
}
```

Full tool/resource list: [docs/MCP.md](docs/MCP.md). Project agent skills live under [`.cursor/skills/`](.cursor/skills/) (`iqueue-native`, `iqueue-lane-engineering`, `iqueue-integrations`).

### External agent frameworks (LangGraph / CrewAI / SmolAgents / DSPy)

```bash
pip install -e ".[integrations]"   # optional; demos work without it via mock/sim
set IQUEUE_SKIP_HF_DOWNLOAD=1
python -m src.integrations.demo --framework mock
python -m src.integrations.demo --framework langgraph --use-case uc_incident
```

Lanes can attach a framework runner (`attach_framework` / `run_on_lane`). See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).

### Demo test cases (CLI / Streamlit / API)

```bash
set IQUEUE_SKIP_HF_DOWNLOAD=1
python -m src.cases_cli --list
python -m src.cases_cli
```

See [docs/CONFIG.md](docs/CONFIG.md) and [docs/API.md](docs/API.md).

## Core ideas

| Piece | Role |
|-------|------|
| **Pivots** | Invariant latent anchors per system / use-case |
| **Lane Engineering** | Design/operate `LaneQueue`s: kinds, agents, tasks, expand, policy |
| **Expandable lanes** | Own requests, spawn/assign agents, track tasks, expand under pressure |
| **Stacked highways** | Multiple levels with different velocities; router + velocities are trainable |
| **Highway** | Bidirectional FORWARD / REVERSE with lane control & changes |
| **Rotator** | KNN + VAE specificity selection |
| **LM steering** | Frontier/local models judge adherence → fit steering vector |
| **γ veer penalty** | `tuple_score = base × γ^{veer_steps} × lane_bonus` |
| **Context packs** | Markdown queue serialization for future context |

## Docs & schema

- [Tutorial](docs/TUTORIAL.md)
- [Lane Engineering](docs/LANE_ENGINEERING.md)
- [Explanation](docs/EXPLANATION.md)
- [External integrations](docs/INTEGRATIONS.md) (LangGraph, CrewAI, SmolAgents, DSPy)
- [HTTP API suite](docs/API.md)
- [MCP server](docs/MCP.md) (Cursor tools/resources + skills)
- [Config variables](docs/CONFIG.md)
- [Models & API keys](docs/MODELS.md)
- [Schema guide](docs/SCHEMA.md)
- [Open schema](schema/iqueue.schema.json)
- [Roadmap](docs/ROADMAP.md)
- [Pivot alignment](src/research/PIVOT_ALIGNMENT.md)

## License

Apache-2.0 — see [LICENSE](LICENSE).
