{"id":51617577,"url":"https://github.com/iblameandrew/open-deepthink","last_synced_at":"2026-07-12T15:01:54.890Z","repository":{"id":309949667,"uuid":"1038151475","full_name":"iblameandrew/open-deepthink","owner":"iblameandrew","description":"Qualitative Neural Networks as a deep-think paradigm  ","archived":false,"fork":false,"pushed_at":"2026-07-05T21:53:16.000Z","size":1164,"stargazers_count":150,"open_issues_count":9,"forks_count":21,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-07-05T23:13:38.971Z","etag":null,"topics":["federated-learning","hierarchical-agents","machine-learning-algorithms","prompt-engineering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iblameandrew.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-14T17:48:08.000Z","updated_at":"2026-07-05T21:53:19.000Z","dependencies_parsed_at":"2026-06-05T22:03:18.060Z","dependency_job_id":null,"html_url":"https://github.com/iblameandrew/open-deepthink","commit_stats":null,"previous_names":["andres-ulloa-de-la-torre/noa","andres-ulloa-de-la-torre/local-deepthink","iblameandrew/local-deepthink","iblameandrew/open-deepthink"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/iblameandrew/open-deepthink","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iblameandrew%2Fopen-deepthink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iblameandrew%2Fopen-deepthink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iblameandrew%2Fopen-deepthink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iblameandrew%2Fopen-deepthink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iblameandrew","download_url":"https://codeload.github.com/iblameandrew/open-deepthink/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iblameandrew%2Fopen-deepthink/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35394859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["federated-learning","hierarchical-agents","machine-learning-algorithms","prompt-engineering"],"created_at":"2026-07-12T15:01:49.614Z","updated_at":"2026-07-12T15:01:54.884Z","avatar_url":"https://github.com/iblameandrew.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"1248\" height=\"832\" alt=\"open-deepthink QNN visualization\" src=\"https://github.com/user-attachments/assets/ffd223ee-a875-4213-a65f-23c2f7a7807c\" /\u003e\n\n# open-deepthink: Evolvable Agent Networks for Deep, Structured Reasoning\n\n**Not another flat panel of 16 agents brainstorming once.**  \nA **Qualitative Neural Network (QNN)** that runs layered forward passes, reflects on its own performance, mutates its agents' cognitive identities, raises the difficulty of the problem, and records the entire developmental history as high-signal training data.\n\nMost agentic systems give you breadth through parallelism. open-deepthink gives you **depth through structured iteration and self-modification**.\n\n---\n\n## The Core Problem with \"Just Add More Agents\"\n\nTypical multi-agent setups (including many \"16 expert\" or \"army of agents\" brainstorming interfaces) work like this:\n\n- Spawn N agents with static or lightly templated personas.\n- Run them in parallel or loose conversation.\n- Synthesize once (or a few turns).\n- Done.\n\nYou get diversity of perspective, but the agents themselves do not become meaningfully better at the *specific* problem over time. There is no topology, no persistent specialization, no mechanism that rewires *how* the system thinks, and almost never a reusable artifact of the reasoning process.\n\nopen-deepthink treats agents like **neurons in a network** whose \"weights\" are rich natural-language personas, and whose learning rule is **Mirror Descent** (qualitative backpropagation).\n\n---\n\n## What Makes a QNN Different\n\nA QNN is a directed, layered graph of LLM agents with three repeating phases per epoch:\n\n1. **Forward Pass** — Problem is decomposed across the topology. Layer 0 runs in parallel. Each subsequent layer receives context from the previous layer and builds deeper analysis. Information flows structurally, not just through a shared chat.\n\n2. **Reflection + Mirror Descent** — After synthesis, the system does not just \"critique the answer.\" It:\n   - Evaluates which agents struggled vs. succeeded on their specific sub-problems.\n   - Extracts attributes and \"hard requests\" from current personas.\n   - Uses a dense-spanner mechanism (or explicit mixing in Distillation) to **rewrite the system prompts, attributes, and skills** of agents for the next round.\n   - In Knowledge Distillation mode, literally **spawns evolved child agents** that inherit context memory and replace struggling parents in the live topology.\n\n3. **Problem Reframing** — A dedicated re-framer node looks at the current solution and formulates a *harder, more advanced version* of the problem. The network is then forced to solve the harder problem in the next epoch with its newly evolved agents.\n\nThis loop (decompose → structured forward → synthesize → reframe the goal → mutate the thinkers) is repeated for as many epochs as you allocate. The result is compounding depth rather than repeated breadth.\n\n---\n\n## Three Powerful Operating Modes\n\n### 1. ⚗️ Knowledge Distillation Mode (The Data Engine)\n\nThe most distinctive and high-leverage mode.\n\n- Fixed powerful topology: **1×2×2×2×2×2×1** (7 layers, 12 agents).\n- 12 distinct cognitive archetypes (The Initiator, Builder, Connector, Preserver, Performer, Analyst, Diplomat, Transformer, Explorer, Architect, Visionary, Dreamer) with hand-crafted system prompts, attributes, and skills.\n- **Task Master** decomposes the anchor question into 12 Socratically-linked sub-questions.\n- Full forward pass with layer-to-layer context.\n- **Mirror Descent** evaluates every agent-question pair. Hard agents trigger **live evolutionary replacement**: a Mixing Agent combines the struggling agent with the best resonant helper from the *current* grid. The child inherits the parent's 100k-token context memory and keeps the difficult question.\n- **Seed Creator** evolves the topic set itself each epoch, generating ontologically adjacent new topics.\n- Runs until your token budget is exhausted.\n\n**Primary output**: A structured JSON dataset of every (epoch, agent, archetype, question, answer) pair, plus a complete `topology_archive.json` containing the full evolutionary history (every system prompt mutation, every inheritance, every difficulty judgment).\n\nThis is not generic chat logs. This is **developmental trace data** explicitly designed for training the next generation of reasoning models — models that can internalize patterns of collaboration, critique, specialization, and progressive deepening.\n\n### 2. 🧠 Brainstorming Mode (Full QNN Expert Panel)\n\nA chat-first interface that runs the **same QNN deepthink algorithm** as the portable `/qnn` skill — not a flat static expert panel.\n\n**Step-by-step each run:**\n\n0. **Brief** — Impasse/enrich summary from prompt + attachments  \n1. **Topology** — Auto (complexity → L×W×E) or Manual/Massive  \n2. **Seeds** — Verbs + nouns from the problem space (related + far semantic fields), sampled into per-column word-vectors — same spanning DNA as Algorithm Mode  \n3. **Personas** — Input-span careers/attributes/skills from those guiding_words (layer 0 diverge; deeper layers converge/critique)  \n4. **Epoch loop** — Layered forward pass → epoch map → Mirror Descent → harder reframe  \n5. **Solution-Space Report** — Divergent strategies with falsifiers and first probes (handoff to edit→run→debug)\n\n- **Auto mode**: Complexity estimator recommends a small topology (skill-aligned score bands).\n- **Manual / Massive mode**: Any Layers × Width; spawn a genuine \"army\" when justified.\n- Intermediate epochs produce compact **epoch maps**; the final epoch polishes the full report.\n- Rich markdown chat interface for the report and logs for each QNN step.\n\nUse this when you want deeper insight than a single model or a flat expert panel can deliver.\n\n### 3. 🧬 Algorithm Design Mode (Maximum Control + Code Generation)\n\nThe original deep QNN mode for hard algorithmic and software problems.\n\n- Design arbitrary layer × width topologies.\n- Full hyperparameter control (prompt alignment, density, learning rate, vector word size, etc.).\n- Automatic problem decomposition into per-agent sub-problems.\n- Code-aware synthesis + real (restricted) Python sandbox execution.\n- Successful modules are documented as \"module cards\" and fed forward as context for future epochs.\n- Complete RAG (RAPTOR) indexing of every agent output across every epoch.\n- Post-run interactive chat directly into the network's memory (\"what did agent_2_1 think about X?\").\n- Final harvest produces structured research-style reports.\n- **Export / Import trained QNNs**: Save the entire evolved network (all layer prompts + state) as a compact JSON. Load it later and run new problems against the *already-evolved* specialists.\n\nThis is the mode for when you want to treat the QNN as a trainable, reusable reasoning artifact.\n\n---\n\n## The Outputs That Actually Matter\n\nA single deep open-deepthink run produces far more than an answer:\n\n- **Evolved QNN artifacts** — Portable, versionable \"trained\" multi-agent systems you can share and reuse.\n- **Full evolutionary traces** — Every prompt before/after Mirror Descent, every difficulty classification, every child/parent relationship, every reframed problem.\n- **Structured distillation datasets** — Purpose-built for fine-tuning or synthetic data pipelines targeting advanced reasoning and multi-agent behavior.\n- **Interpretable intermediate state** — Because everything is explicit natural-language personas and traceable sub-problems, you can diagnose *why* the system thought what it thought at any layer and epoch.\n- **Accumulated executable knowledge** (in code modes) — Real modules that survived sandbox validation and were re-used.\n\nThese artifacts are the real product. The final synthesized answer is a byproduct.\n\n---\n\n## Why This Matters for Agentic Coding and Reasoning Research\n\n- **Test-time compute, done right and observably.** Many frontier systems hide their long reasoning inside a single model. open-deepthink makes the structure, specialization, and adaptation explicit and archivable.\n- **A credible path to better base models.** The highest-leverage use of current powerful models may be generating traces of *how* hard problems should be decomposed, attacked by specialized perspectives, critiqued, and progressively deepened. open-deepthink is purpose-built to produce that class of data at scale on consumer hardware.\n- **Reusable specialized reasoners.** An exported QNN that has spent 10–20 epochs evolving on a domain is qualitatively different from prompting a base model with a long system prompt. The specialization is *baked into the network structure and the evolved personas*.\n- **Local and long-horizon by design.** Runs for hours or days on a 32 GB laptop or a modest rig. No requirement for frontier API spend to get compounding returns.\n\n---\n\n## Technical Strengths\n\n- Built on **LangGraph** with real cyclic graphs, conditional routing (epoch gateway), parallel layer execution, and proper state management — not a pile of sequential chains.\n- 195 passing tests across 11 phases, including regression tests for every bug fixed in the 0.0.3 quality release.\n- Clean provider model: only OpenRouter (cloud) and llama.cpp server (local). Per-agent and per-synthesis model selection supported.\n- Robust JSON handling, token tracking, streaming logs, RAPTOR hierarchical indexing, and safe(ish) code execution.\n- Real export/import of full QNN state.\n- Massive scale supported when you ask for it (Manual/Massive mode will happily run 50×50+ if your budget allows).\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/iblameandrew/open-deepthink\ncd open-deepthink\npython -m venv venv\n.\\venv\\Scripts\\activate          # Windows\n# source venv/bin/activate       # macOS/Linux\npip install -r requirements.txt\nlaunch.bat                       # or: python app.py\n```\n\nOpen http://127.0.0.1:8000.\n\n**Supported providers**: OpenRouter (bring your own key) and local llama.cpp server.\n\nSee the in-app UI for the three modes, topology visualization, token budgeting (especially important for Distillation), and export controls.\n\n---\n\n## Hyperparameters \u0026 Hardware Reality\n\n- **Layers / Width**: Control depth vs. breadth of the network. 3–6 layers with 3–8 width is already deep on most problems. Massive mode exists for when you want to go further.\n- **Epochs**: The number of full forward + reflection + reframing cycles. This is where the power law lives.\n- **Learning rate / Density / Prompt alignment**: Control how aggressively agents mutate and how strongly the original problem shapes their identities.\n- **Token budget** (Distillation): The real governor. Set it high if you want serious evolutionary runs.\n\n**Practical guidance**:\n- 32 GB RAM CPU laptop: 2×2 to 4×4 topologies, 2–4 epochs.\n- 64 GB + decent GPU: 6×6 to 10×10, more epochs, or serious Distillation runs.\n- The system is explicitly designed so that **more time and more epochs beats needing a bigger base model**.\n\n---\n\n## Vision\n\nEvery serious open-deepthink run is a small laboratory experiment in collective intelligence. The structured traces it produces — complete with evolutionary dynamics, difficulty signals, and topology mutations — are some of the richest open data currently being generated about *how* LLMs can be orchestrated to think harder.\n\nThe long-term bet is that collecting thousands of such runs will let us train models that no longer need elaborate hand-written system prompts or external scaffolding, because they have internalized the patterns of decomposition, specialization, critique, and progressive deepening directly.\n\nThis is why the distillation dataset + full topology archives are treated as first-class outputs.\n\n---\n\n## Portable `/qnn` Skill for Agentic Coders\n\nWhen a coding agent is **stuck** (deadlock, race, perf cliff, circular local fixes) or a **feature needs wider depth** (richer metrics, APIs, UX options), drop in the portable QNN skill instead of grinding more one-shot prompts.\n\n```\n/qnn explore this deadlock / performance regression\n/qnn richer metrics for the training dashboard\n```\n\nThe skill runs a structured Qualitative Neural Network procedure inside the host agent: guiding concepts → layered personas → multi-epoch forward passes → Mirror Descent persona evolution → harder reframes → a **Solution-Space Report**. The goal is not to ship the patch immediately — it is a map of divergent strategies with falsifiers and smallest first probes. You pick a direction and resume the grounded edit → run → debug loop.\n\n| Artifact | Location |\n|----------|----------|\n| Skill body | [`skills/qnn/SKILL.md`](./skills/qnn/SKILL.md) |\n| Install notes | [`skills/qnn/INSTALL.md`](./skills/qnn/INSTALL.md) |\n| Skills index | [`skills/README.md`](./skills/README.md) |\n| Release zip | `qnn-skill-\u003cversion\u003e.zip` on [GitHub Releases](https://github.com/iblameandrew/open-deepthink/releases) |\n\n**Install (Grok user skills):**\n\n```bash\nmkdir -p ~/.grok/skills/qnn\ncp skills/qnn/SKILL.md ~/.grok/skills/qnn/SKILL.md\n```\n\nOr download the release asset and unzip into `~/.grok/skills/`. Works with any agent that can follow a skill file — tool names adapt to the host.\n\nThe full open-deepthink server remains the place for long evolutionary runs, export/import of trained QNNs, and distillation datasets. The portable skill is the lightweight escape hatch for day-to-day agentic coding.\n\n---\n\n## Contributing \u0026 Benchmarking\n\nThis is research software with a stable core (195/195 tests, all core loops functional). The most valuable contributions right now are:\n\n- Deep, long runs on interesting problems (especially with local models) and sharing the exported QNNs + distillation datasets.\n- Bug reports that include the graph trace / logs.\n- Ideas for tightening the code execution loop, adding real tool use inside agents, or improving the Mirror Descent signal.\n- P2P/distributed ideas for running truly massive topologies across machines.\n\nOpen an issue with your traces and thoughts.\n\n---\n\n## License \u0026 Credits\n\nOpen-source research project. The goal is to push forward what small teams and individuals can do with structured, long-horizon agentic systems.\n\nIf open-deepthink helps you go deeper on hard problems or generates useful traces, star the repo and share what you built with the exported QNNs or distillation data.\n\n---\n\n**open-deepthink** — Turn time and structure into depth.  \nNot more agents. Better *becoming* agents.\n\n---\n\n*Version 0.1.7 — See [RELEASE_NOTES.md](./RELEASE_NOTES.md) for the full history.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiblameandrew%2Fopen-deepthink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiblameandrew%2Fopen-deepthink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiblameandrew%2Fopen-deepthink/lists"}