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.

Docs

Documentation	Explanation
Tutorial	API
Config	MCP
Lane Engineering	Orchestration
Multimodal	Cloud
Integrations	Ablations H1–H7
Roadmap	Source / Issues

PyPI: iqueue · Repo: ehallford11714/iQueue

Session SDK (v0.3)

Session routes and stabilizes work (score → lane → service → pack). It does not generate model text — your client does (client.complete). See Walkthrough below.

import iqueue

with iqueue.Session() as s:
    s.configure(skip_hf_download=True)
    s.admit("Plan fever differential", system_id="uc_diagnosis")
    s.service(ticks=1)
    s.pack_contexts()
    s.export_audit("outputs/audit")  # JSON + Markdown

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

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
python -m src.experiments.run_h1_h7    # full H1–H7 ablation battery (or: iqueue-ablation)
python -m src.v03_demo                 # Session + kernel admit + audit + integrations smoke

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

Examples

Ten domain scripts under examples/ — each uses Session to route/stabilize and client.complete to generate. Full index + run notes: examples/README.md.

Script	Domain
01_build_apps.py	Apps / CLI scaffold
02_build_games.py	Games
03_conduct_research.py	Research loop
04_code_review_refactor.py	Code review
05_data_analysis.py	Data / pandas
06_customer_support_agent.py	Support
07_education_tutor.py	Tutoring
08_devops_incident.py	Incident / DevOps
09_creative_writing.py	Creative writing
10_legal_policy_draft.py	Policy draft (not legal advice)

# from repo root; needs OPENAI_API_KEY in .env
python examples/01_build_apps.py

Token cost: multi-step goals (admit → complete × N, FORWARD+REVERSE, rolling context) can burn many tokens. Start with luna, fewer steps, mock for dry runs, and set budgets — see below.

Walkthrough: HighWay Session for a goal

Session routes and stabilizes; the client generates. Typical loop for one goal:

1. Open a Session (context manager).
2. Configure highway knobs (skip_hf_download, optional kernel_admit / safety).
3. For each step of the goal:
   • admit — score against the system pivot, pick lane / direction (FORWARD plan-build, REVERSE critique).
   • service — drain highest-priority queued work.
   • client.complete — you call the model; Session never invents the reply text.
4. pack_contexts — serialize scored queues to markdown for later runs.
5. Optional export_audit — JSON + Markdown trail.

import iqueue

iqueue.configure(timeout_s=180)  # raise if large prompts time out
client = iqueue.get_client("luna")  # cheaper/faster to start; mock for dry runs

goal = "Build a tiny folder-watcher CLI that summarizes new .txt files."
steps = [
    ("plan", iqueue.Direction.FORWARD, f"{goal}\nPlan modules and flags only."),
    ("implement", iqueue.Direction.FORWARD, f"{goal}\nWrite a short runnable script."),
    ("critique", iqueue.Direction.REVERSE, f"{goal}\nFind bugs; propose exact fixes."),
]

prior = ""
with iqueue.Session() as session:
    session.configure(skip_hf_download=True, kernel_admit=True)

    for role, direction, text in steps:
        prompt = text + (f"\n\n--- prior ---\n{prior[-4000:]}" if prior else "")
        req = session.admit(prompt, system_id="uc_planning", direction=direction)
        if req.metadata.get("rejected") or req.metadata.get("blocked"):
            continue
        session.service(ticks=1)
        reply = client.complete(prompt, system="Be concrete.")
        prior += f"\n### {role}\n{reply.text}"

    session.pack_contexts("outputs/my_goal/contexts")
    session.export_audit("outputs/my_goal/audit")

Same pattern, packaged: examples/_common.py (run_stepped_session) and any of the ten scripts above.

Token cost & budgets

Running a full goal this way can spend a lot of tokens:

• Several admit + complete rounds per goal
• Often FORWARD and REVERSE (plan/build and critique)
• Prompts grow via rolling prior context

Practical advice

Do	Why
Start with luna (or a small local/mock client)	Fewer $/tokens while learning the loop
Use fewer steps first (2–3, not 8+)	Caps complete calls
Prefer get_client("mock") for dry runs	Exercises Session without API spend
Set iqueue.configure(timeout_s=...) deliberately	Long prompts + slow models time out; raising timeout ≠ free tokens
Cap max_tokens / prior window	Keeps each complete bounded
Set a budget (spend limit, max steps) before multi-step jobs	Avoid runaway loops

Harder examples (03, 08, 10) default to sol — switch them to luna when exploring.

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

Piece	Role
Pivots	Invariant latent anchors per system / use-case
Lane Engineering	Design/operate LaneQueues: 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
• Lane Engineering
• Explanation
• External integrations (LangGraph, CrewAI, SmolAgents, DSPy)
• H1–H7 ablations
• HTTP API suite
• MCP server (Cursor tools/resources + skills)
• Config variables
• Models & API keys
• Schema guide
• Open schema
• Roadmap (v0.3.0 items #6–10 shipped)
• Pivot alignment

License

Apache-2.0 — see LICENSE.