iQueue

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

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. Copy config/models.example.json → config/models.local.json for local keys.

Quick start

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 — 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 — designing and operating expandable LaneQueues (agents, tasks, fill/drain, kinds, stack, policy).

Orchestration + browser: docs/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)

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).

# 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)

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)

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):

{
  "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. Project agent skills live under .cursor/skills/ (iqueue-native, iqueue-lane-engineering, iqueue-integrations).

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

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.

Demo test cases (CLI / Streamlit / API)

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

See docs/CONFIG.md and docs/API.md.

Core ideas

Docs & schema

• Tutorial
• Lane Engineering
• Explanation
• External integrations (LangGraph, CrewAI, SmolAgents, DSPy)
• HTTP API suite
• MCP server (Cursor tools/resources + skills)
• Config variables
• Models & API keys
• Schema guide
• Open schema
• Roadmap
• Pivot alignment

License

Apache-2.0 — see LICENSE.