🌌 Multiverse Planner — Parallel Swarm Planning Engine

An advanced agentic planning runtime. Replaces linear reasoning with a Doctor Strange "one-in-a-million" timeline expansion and pruning pipeline—reverse-engineering the correct solution by exploring a combinatorial state-space.

Quick Start • The Paradigm Shift • Features & Latency • CLI Reference • Architecture • Subsystems • API Reference • Comparison Matrix • Roadmap

---

💡 The Paradigm Shift

Traditional LLM planning (like Chain-of-Thought or Tree-of-Thought) fails on high-stakes systems architecture or mathematical optimization. Agents running sequentially get stuck in local minima, hallucinate invalid API parameters, or follow single logical dead-ends because they try to guess the solution forward.

Multiverse Planner treats planning like a "poor man's quantum computing." Instead of guessing the correct solution immediately, it procedurally spawns thousands of parallel timelines (A, B, C / D, E, F / G, H, I), runs them through a deterministic guillotine (cut.py) to prune invalid states, collapses similar paths, and stress-tests the remaining archetypes. It reverse-engineers the correct solution by searching for the "only timeline in a million" that successfully achieves the target state without breaking.

---

✨ Features & Latency Bounds

Stage	Mechanism	Complexity	Windows Latency	Linux Latency
1. The Big Bang	Combinatorial state space permutation generation via gen.py	$O(N^K)$	< 250ms	< 110ms
2. The Guillotine	Static constraint rules & physical invariant pruning via cut.py	$O(N)$	< 18ms	< 9ms
3. Semantic Hashing	Cosine similarity clustering using Ollama embeddings	$O(M^2)$	< 120ms	< 45ms
4. Stress-Testing	Multi-threaded evaluation and scoring of representative archetypes	$O(T)$	< 1.8s	< 0.9s

---

⚡ Quick Start

Prerequisites

• Python 3.11+
• uv (recommended for rapid dependency syncing)
• Ollama running locally on your system

1. Clone & Setup

git clone https://github.com/axtontc/Multiverse-Planner.git
cd Multiverse-Planner

# Sync virtual environment using uv
uv sync

2. Verify with the Test Suite

Ensure the mathematical clustering and mocked API endpoints work out-of-the-box:

uv run python -m pytest tests/ -v

---

🛠️ CLI Reference

1. Initialize a Session

Generate the boilerplate logic files in your active workspace directory:

multiverse init

This generates:

• gen.py: Boilerplate code to procedurally generate decision branches.
• cut.py: Boilerplate code to filter out logically or physically invalid branches.

2. Customize Your Logic

• gen.py: Modify the generator logic to output a JSON array of state variables into permutations.json.
• cut.py: Modify the validator logic to filter permutations and write surviving branches to survivors.json.

3. Run the Multiverse Engine

multiverse run --gen gen.py --cut cut.py --prompt "The problem is to design a deadlock-free concurrent message broker that processes 1M events/sec."

The CLI will execute the pipeline: it spawns a multiverse of solution permutations, prunes invalid paths via cut.py, collapses duplicates, and uses the problem statement (--prompt) to find the single solution archetype that mathematically solves the problem.

---

🏗 Architecture

graph TD
    A[multiverse run] --> B(gen.py: The Big Bang)
    B -->|permutations.json| C(cut.py: The Guillotine)
    C -->|survivors.json| D[Semantic Hashing]
    D -->|Deduplicated Archetypes| E[Parallel Evaluation Swarm]
    E -->|Parallel Threads| F[critique_results.json]

    style A fill:#1a1a2e,stroke:#3776AB,color:#fff
    style B fill:#16213e,stroke:#3776AB,color:#fff
    style C fill:#0f3460,stroke:#2ea043,color:#fff
    style D fill:#0f3460,stroke:#2ea043,color:#fff
    style E fill:#1a1a2e,stroke:#F5A800,color:#fff

Loading

---

⚙️ Model Configuration

The Multiverse Planner dynamically checks your model preferences from C:\Users\axton\.gemini\config\models.json. Make sure the file exists with the following structure:

{
  "llm": "qwen2.5-coder:7b",
  "embedding": "nomic-embed-text"
}

If the configuration file is missing, it will automatically fall back to local OLLAMA_LLM and OLLAMA_EMBEDDING environment variables.

---

🏗️ Core Subsystems

Subsystem	Folder / File	Responsibility
CLI Dispatcher	multiverse/cli.py	Command line arguments parser and project boilerplate initializer
Model Loader	multiverse/core/models.py	Load configurations and models from environment or models.json
Pruning Engine	multiverse/core/pruner.py	Manages branch runs, cosine similarity calculations, and clustering
Evaluation Swarm	multiverse/core/critique.py	Thread-pool execution farm scoring and stress-testing archetypes against objective prompts
Pipeline Runner	multiverse/core/pipeline.py	Main orchestrating routine wiring generation, cuts, clusters, and evaluations

---

📖 API & Core Functions Reference

multiverse/core/pruner.py

These functions manage filtering logic and semantic clustering:

Function / Routine	Parameters	Description
cosine_similarity(a, b)	list[float], list[float]	Computes the dot product cosine similarity between two embeddings.
cluster_survivors(survivors, embed_model)	list[dict], str	Clusters surviving state trees semantically using Ollama embeddings.
run_gen_cut(gen_path, cut_path, target_dir)	str, str, Path	Runs custom gen.py and cut.py scripts inside the target workspace.

multiverse/core/critique.py

These routines stress-test and score plans using parallel threads:

Function / Routine	Parameters	Description
run_adversarial_farm(...)	list[dict], str, str	Spawns a parallel thread-pool evaluation farm scoring timeline clusters.
critique_archetype(archetype, prompt_template)	dict, str, str	Prompts a local Ollama instance to evaluate the archetype against the objective prompt template.

---

📊 Comparison Matrix

Planner Capability	Chain-of-Thought	Tree-of-Thought	ReAct Loop	Multiverse Planner
Combinatorial timeline expansion	❌	⚠️ Manual	❌	✅ Yes (Procedural generation)
Semantic timeline clustering	❌	❌	❌	✅ Yes (Cosine similarity)
Parallel stress-testing & scoring	❌	❌	❌	✅ Yes (Thread-pool farm)
Static validation invariants	❌	❌	⚠️ Code-based	✅ Yes (Fast static cuts)
Local Offline execution	⚠️ Configurable	⚠️ Configurable	⚠️ Configurable	✅ Yes (100% Ollama native)

---

🧰 Tech Stack

• Core Language: Python 3.11+
• LLM Engine: Ollama (Qwen2.5 Coder & Nomic Embeddings)
• Math utilities: standard library math, cosine vector structures
• Developer tools: pytest, pytest-mock, Ruff, mypy

---

🗺️ Roadmap

• Procedural state permutation generator
• Static rule pruning validator
• Semantic cosine-similarity timeline deduplication
• Parallel thread-pool stress-testing farm
• Graphical Dashboard — Real-time plan visualization tree showing nodes, scores, and pruning points
• Monte Carlo Tree Search (MCTS) — Dynamic timeline expansion guided by real-time agent rewards
• Distributed Critique Nodes — Split agent critiques across multiple network nodes running Ollama

---

🔗 Ecosystem Cross-Linking

Multiverse Planner belongs to a suite of interconnected AI agent utilities:

Project	Description
AUI	Zero-latency cross-process UI automation for Windows and Web
MemMCP	Deterministic memory server with SQLite WAL and FAISS RRF
The-Skillbrary	Low-latency registry and FastMCP execution server for agent swarms
The-Nexus	Monolithic API gateway and orchestrator for local LLMs
Fractal-Swarm-v2	Mathematically optimal state-machine agent swarm orchestration
AntiMem	Memory daemon and compactor for Antigravity swarms
OmniMem	PostgreSQL hybrid memory system for large enterprise swarms

---

📜 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details. Copyright (c) 2026 Axton Carroll.

---

⭐ If Multiverse Planner helps optimize your swarm timelines, consider giving it a star!



_{Built by Axton Carroll — "Nothing is impossible, we merely don't know how to do it yet."}