iqueue 0.2.0__tar.gz

iqueue-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 iQueue contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

iqueue-0.2.0/PKG-INFO

@@ -0,0 +1,242 @@
+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).

iqueue-0.2.0/README.md

@@ -0,0 +1,167 @@
+# 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).

iqueue-0.2.0/iqueue/__init__.py

@@ -0,0 +1,129 @@
+"""
+iQueue public package surface.
+
+    import iqueue
+    iqueue.configure(openai_api_key="sk-...", anthropic_api_key="sk-...")
+    iqueue.get_client("sol")    # GPT-5.6 Sol
+    iqueue.get_client("opus5")  # Claude Opus 5
+    iqueue.get_client("mock")   # auto-downloads HF Qwen offline
+"""
+
+from src.models import (
+    API_KEY_ENV,
+    DEFAULT_MODELS,
+    AnthropicClient,
+    BaseModelClient,
+    GoogleClient,
+    HuggingFaceLocalClient,
+    Message,
+    MockClient,
+    ModelConfig,
+    ModelResponse,
+    OllamaClient,
+    OpenAICompatibleClient,
+    ProviderKind,
+    QwenClient,
+    configure,
+    get_client,
+    get_config,
+    list_models,
+    list_providers,
+    resolve_client,
+)
+from src.models.catalog import MODEL_CATALOG, resolve_alias
+from src.models.offline import ensure_offline_qwen, last_offline_status
+from src.models.requests import ModelRequestResult, ModelRequestRouter, ModelRequestSpec
+from src.models.steering import LargeModelSteerer, SteerJudgment
+from src.models.tier_routing import LevelModelRouter, TierRoute
+from src.highway import HighWay, HighwayConfig, Direction, LaneKind
+from src.highway.context import HighwayContext
+from src.highway.types import MediaAttachment, Modality
+from src.config import IQueueConfig
+from src.hardware import assess_hardware, pick_qwen_model, recommend_execution
+from src.ranking import Embedder, HashEmbedder, get_embedder
+from src.runtime import build_highway, build_stack, apply_learn_road, embedder_from, tier_router_from
+from src.train import ClosedLoopLearner, learn_road_from_trace
+from src.trace_runner import run_trace
+from src.experiments.quality import evaluate_trace_quality
+from src.control_plane import ControlPlaneStore
+from src.models.multimodal import get_multimodal_client, run_multimodal
+from src.cloud import decide_local_or_cloud, get_cloud_provider
+from src.lane_engineering import (
+    EngineeredLanes,
+    ExpansionPolicy,
+    LaneBlueprint,
+    LaneEngineering,
+    LaneSpec,
+    apply as apply_lane_engineering,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "API_KEY_ENV",
+    "ClosedLoopLearner",
+    "ControlPlaneStore",
+    "DEFAULT_MODELS",
+    "Embedder",
+    "EngineeredLanes",
+    "ExpansionPolicy",
+    "HashEmbedder",
+    "HighwayContext",
+    "IQueueConfig",
+    "LaneBlueprint",
+    "LaneEngineering",
+    "LaneSpec",
+    "LevelModelRouter",
+    "MODEL_CATALOG",
+    "AnthropicClient",
+    "BaseModelClient",
+    "Direction",
+    "GoogleClient",
+    "HighWay",
+    "HighwayConfig",
+    "HuggingFaceLocalClient",
+    "LaneKind",
+    "LargeModelSteerer",
+    "MediaAttachment",
+    "Message",
+    "MockClient",
+    "Modality",
+    "ModelConfig",
+    "ModelRequestResult",
+    "ModelRequestRouter",
+    "ModelRequestSpec",
+    "ModelResponse",
+    "OllamaClient",
+    "OpenAICompatibleClient",
+    "ProviderKind",
+    "QwenClient",
+    "SteerJudgment",
+    "TierRoute",
+    "apply_lane_engineering",
+    "apply_learn_road",
+    "assess_hardware",
+    "build_highway",
+    "build_stack",
+    "configure",
+    "decide_local_or_cloud",
+    "embedder_from",
+    "ensure_offline_qwen",
+    "evaluate_trace_quality",
+    "get_client",
+    "get_cloud_provider",
+    "get_config",
+    "get_embedder",
+    "get_multimodal_client",
+    "last_offline_status",
+    "learn_road_from_trace",
+    "list_models",
+    "list_providers",
+    "pick_qwen_model",
+    "recommend_execution",
+    "resolve_alias",
+    "resolve_client",
+    "run_multimodal",
+    "run_trace",
+    "tier_router_from",
+    "__version__",
+]