FlowModus

Helix 生态 · CommonIntents 协议家族 · INTENT-7 · CAPABILITY-13 · INTENT-7-SECURE · BIND-19

许可证：Apache 2.0（2026-09-06 起，见 whitepaper v1.7.1 修订记录）

注意：Rust 确定性重构已完成并收口（rs 分支，83 测试全绿，CLI 可用）。 本分支为 Python v1.7 冻结维护版，新开发请切 rs 分支（git checkout rs）。

The Deterministic Protocol Layer for LLM API Scheduling
Decentralized. Vendor‑Neutral. Community‑Driven.

---

⚡ TL;DR

FlowModus is a cryptographically‑verified, deterministic routing layer between your Agents and LLM Providers. It replaces opaque, rent‑seeking gateways with a local‑first sidecar executing a mathematically rigorous 5‑layer pipeline.

• Problem: Legacy gateways route based on vendor profit, not user intent. Opaque billing, non‑deterministic latency, and compute waste.
• Solution: A zero‑waste sidecar that enforces user‑defined constraints, verifies every routing table via Ed25519, and derives all telemetry from real traffic — never active probing.
• Result: Verifiable per‑token cost attribution, full data sovereignty, and routing that obeys your rules, not the vendor's.

📖 Whitepaper v1.7 · 🛠 Engineering Manual v1.1.3

---

🧬 The 5‑Layer Deterministic Pipeline

Every request passes through five immutable layers. No step is optional, no decision is arbitrary.

1. Normalization (STE) – Converts vendor‑specific tokens to Standard Token Equivalents.
2. Raw Registry – Ed25519‑signed, IPFS/IPNS‑distributed supplier declarations.
3. Cost Inference – Real‑time price estimation factoring cache hints and claim deviations.
4. Hard Filter – Enforces budget, region, residency, and user‑defined bias locally.
5. Entropy‑Weighted Routing – Deterministic jitter via instance‑ID to prevent global herd effects.

---

🔀 Three Call Modes

FlowModus supports three routing modes, selected via the model parameter in the request body.

Mode	model value	Behavior
Manual	"deepseek-chat"	Route directly to the specified model. No pipeline overhead.
Group	"group:fast-lane"	Route within a user‑defined group using priority and weight.
Auto	"auto"	Full 5‑layer pipeline: cost estimation, hard filtering, entropy‑weighted sampling.

---

🪨 Engineering Iron Laws (from the Manual)

These are non‑negotiable. Code violating any of them will not be merged.

0. Principle of Least Action – Zero active polling. All telemetry is parasitic. No waste.
1. Determinism First – Same input → bit‑identical output, globally decorrelated by instance‑ID.
2. Pure Functions – All routing logic is side‑effect‑free.
3. Lock‑Free – Message passing over shared memory. No deadlocks.
4. No Blocking – Async I/O only. Control plane separated from data plane.
5. Schema Enforcement – Protobuf between modules. Never raw dict or JSON.
6. Minimal Dependencies – No web frameworks, no ORMs, no daemons.
7. Naming as Documentation – Google style. Self‑explanatory names.

---

🏗 Architecture

FlowModus runs as a local sidecar (localhost:8080). In a full Helix deployment, the call chain is:

Anaphase‑Helix → Callosum → Tuck → FlowModus → LLM API

Supplier registries are pulled from IPFS and verified with the Protocol Root Key. API keys are injected at the edge — they never leave memory, never appear in logs, and are never transmitted over the gossip network.

---

⚠️ Current Temporary Setup (Before Cellrix Integration)

Important: Until Cellrix integration provides a guided onboarding UI, the following temporary configuration methods are in use. DO NOT forget to replace these with the planned config.yaml and guided setup later.

🔧 Environment Variables (TEMPORARY)

Currently, you must manually export environment variables to start the sidecar:

export FLOWMODUS_LOCAL_REGISTRY=~/.flowmodus/local_registry.json
export FLOWMODUS_API_KEY_DEEPSEEK=sk-...
export FLOWMODUS_API_KEY_TUCK_LOCAL=sk-...
export FLOWMODUS_PROXY_PORT=8080
uv run flowmodus

Why this is temporary: It forces the user to memorize variable names and write long commands.
Planned replacement: A single config.yaml file (see below) and eventually a Cellrix onboarding form.

🔀 Model Name Replacement (TEMPORARY)

In Auto mode, the pipeline currently replaces the model field in the request body with the actual supplier model ID (e.g., Qwen2.5.1-Coder-7B-Instruct-Q4_K_M.gguf) inside proxy.py.
Why this is temporary: It modifies the user’s original request, violating immutability.
Planned replacement: Move this logic into lifecycle.py so that proxy.py receives a complete decision object and never alters the original request body.

🗺️ Next Steps After Cellrix Update

1. Migrate configuration to ~/.flowmodus/config.yaml – a structured, self‑documenting file that replaces scattered environment variables.
2. Fix model name replacement – relocate logic from proxy.py to lifecycle.py to preserve request immutability.
3. Verify Callosum → Tuck → FlowModus chain – ensure the full Helix stack works end‑to‑end.
4. Complete Group mode implementation – enable model="group:..." routing.
5. Add streaming response support – handle SSE streams properly.

---

🚀 Roadmap

Phase	Timeline	Focus
Phase 1	0–3 months	✅ Manual & Auto mode verified, passive telemetry, startup with local registry 🔜 Migrate env vars → config.yaml, fix model replacement, verify Callosum integration
Phase 2	3–6 months	Group mode, IPFS/IPNS distribution, Gossip health network, Tuck integration
Phase 3	6–12 months	Standard solidification, donation to LF AI & Data / CNCF sandbox
Phase 4	12+ months	Ubiquitous infrastructure, edge‑cloud unified scheduling

---

📄 Licenses

• Core Protocol & Sidecar Base: MIT — permanent public utility.
• Enterprise Extensions: Apache 2.0 — legal & patent protection for enterprise.
• Whitepaper: CC BY‑ND 4.0 — authoritative protocol specification.

---

⚠️ Disclaimer

Pre‑release software. Provided "as‑is" without warranty. Protocol subject to change until v1.0 stable. FlowModus is a neutral technical standard and does not constitute investment advice or service guarantees.

---

Built with mathematical rigor by the FlowModus Community.