From f8342856b61765e0d7e0bd5b60d32d739926ab7b Mon Sep 17 00:00:00 2001 From: Duck Quang Date: Fri, 17 Jul 2026 00:45:44 +0700 Subject: [PATCH] docs: bring README to launch quality (full workflow, stress-test, HIGH RISK, routing) - Add scannable top pitch, feature bullets, and a live-demo CTA - Document the full engine loop: generate -> Elo tournament -> multi-round evolution -> recurring self-critique -> stress-test the top 3 -> apply fixes + re-rank -> meta-review, and redraw the architecture diagram to match - Feature the adversarial stress-test stage (contradicting evidence, citation verification, feasibility, prototype-scale experiment) and HIGH RISK mode - Name the keyless literature sources (OpenAlex/PubMed/arXiv/Europe PMC) and per-citation verification; web_search only with Tavily/Brave key - Update routing: landing at /, chat composer at /chat via "Launch the demo" - Verify the Nature 2026 Gottweis citation (title via Crossref) Co-Authored-By: Claude Fable 5 --- README.md | 133 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 107 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 46d0d14..4d95353 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # 🧬 Co-Scientist -**A multi-agent research engine that turns a natural-language goal into tournament-ranked hypotheses.** +**A multi-agent research engine that turns a one-line research goal into tournament-ranked, stress-tested, citation-grounded hypotheses.** [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.11--3.13-blue.svg)](https://www.python.org/) @@ -10,24 +10,70 @@ *Created by **Quang Bui*** +### [β†’ Try the live demo](https://duckyquang.github.io/Co-Scientist/) β€” no account, no API key + +Type a research question. A team of specialised agents generate competing +hypotheses, debate and **Elo-rank** them, evolve the best across several rounds, +**adversarially stress-test the top 3**, then write a final proposal with inline +`[n]` citations grounded in real papers. Watch every step β€” including the agents' +reasoning β€” stream live in the chat. + +- **Elo tournament** of pairwise hypothesis debates +- **Recurring self-critique** β€” the engine re-questions its own leaderboard for flaws and weak citations +- **Stress-testing the top 3** β€” contradicting-evidence search, citation verification, feasibility + a prototype-scale experiment, then fixes and a re-rank +- **Multi-round evolution** of the leading ideas +- **HIGH RISK mode** β€” a toggle for bold, contrarian, non-derivative hypotheses +- **Real citations, no key** β€” OpenAlex / PubMed / arXiv / Europe PMC, each verified, with a numbered `## References` section +- Runs in the browser with **no setup**, or self-host for a server-side key + --- ## ✨ What it does -An open-source re-implementation of Google's **AI co-scientist** ([Gottweis et al., *Nature*, 2026](https://www.nature.com/articles/s41586-026-10644-y)) β€” six specialised agents collaborate through an Elo tournament to produce a ranked research overview. +An open-source re-implementation of Google's **AI co-scientist** +([Gottweis et al., *"Accelerating scientific discovery with Co-Scientist,"* **Nature**, 2026](https://www.nature.com/articles/s41586-026-10644-y)). +Six specialised agents collaborate through an Elo tournament, then an adversarial +stress-test stage pressure-tests the finalists, to turn a natural-language goal +into a ranked, citation-grounded research proposal. + +> Independent project β€” not affiliated with Google or the paper's authors. + +**A single run walks through these stages** β€” all of it streaming live in the chat, +including the agents' own reasoning: + +1. **Generate** competing hypotheses from a literature review and multi-agent debate. +2. **Reflect** β€” review each for novelty, correctness, and testability. +3. **Rank** in an **Elo tournament** of pairwise debates. +4. **Evolve** the leaderboard's best ideas across **multiple rounds** (combine, simplify, out-of-the-box) β€” shown as distinct steps. +5. **Self-critique**, recurring β€” the meta-review agent re-questions its own leaderboard: *are these really the best hypotheses? what are the flaws, the wrong conclusions, the suspect citations?* Its thinking shows in the feed. +6. **Stress-test the top 3** β€” *the headline stage.* Each finalist is adversarially probed: search for **contradicting evidence**, **verify every citation**, run a **feasibility check**, and design a **prototype-scale experiment**. Surviving weaknesses are **fixed**, then the finalists are **re-ranked** head-to-head. +7. **Meta-review** β€” synthesise the final proposal with inline `[n]` citations and a numbered `## References` section. + +Steps 3–5 repeat each round until the leaderboard is stable or the token budget is +spent; step 6 runs once, at finalize. + +### The six core agents | Agent | Role | |---|---| | **Generation** | Proposes hypotheses via literature review and debate | | **Reflection** | Reviews novelty, correctness, testability | | **Ranking** | Elo tournament with pairwise debates | -| **Evolution** | Combines and refines top hypotheses | +| **Evolution** | Combines and refines top hypotheses across rounds | | **Proximity** | Clusters hypotheses for dedup and matchmaking | -| **Meta-review** | Synthesises the final research overview | +| **Meta-review** | Recurring self-critique and the final research overview | -> Independent project β€” not affiliated with Google or the paper's authors. +A dedicated **stress-test** stage (config `[run] stress_test_top_k`, default 3) +runs the adversarial probe on the finalists at the end of a run. + +### ⚑ HIGH RISK mode + +Flip the **High risk** toggle on the composer to push every agent toward **bold, +contrarian, non-derivative** hypotheses instead of safe, incremental ones +(config `[run] high_risk`). Sessions run this way are badged so you can tell them +apart. ### 🎚️ Hypothesis modes @@ -71,32 +117,40 @@ To steer a session **while it's still running**, the feedback endpoint (`POST /api/sessions/{id}/feedback`) still accepts directives, preferences, and per-hypothesis pin/reject. -### πŸ“š Citations guaranteed +### πŸ“š Real citations, no key required -Every research proposal ends with a numbered `## References` section, with -inline `[n]` markers throughout the text. The real engine builds it only from -papers actually fetched during literature search (`CitedPaper` records) and -marks any entry the citation verifier couldn't confirm as `(unverified)`. -Browser-run proposals β€” simulated or generated by an in-browser LLM β€” include -well-formed references too. +Agents ground their claims in real literature through four **keyless** public +APIs that are always on: `openalex_search`, `pubmed_search`, `arxiv_search`, and +`europe_pmc_search` β€” giving real papers with resolving DOIs out of the box. +General `web_search` auto-activates only when you supply a `TAVILY_API_KEY` or +`BRAVE_API_KEY`. + +Every proposal ends with a numbered `## References` section, and inline `[n]` +markers throughout the text link to it. The real engine builds that list only +from papers actually fetched during literature search (`CitedPaper` records), +verifies each one, and marks any entry the citation verifier couldn't confirm as +`(unverified)`. Browser-run proposals β€” simulated or generated by an in-browser +LLM β€” include well-formed references too. --- ## πŸš€ Quick start β€” no setup required 1. **Visit the live site** β†’ [duckyquang.github.io/Co-Scientist](https://duckyquang.github.io/Co-Scientist/) - β€” you land straight on the chat composer + β€” it opens on a landing page; click **Launch the demo** to reach the chat + composer (`/chat`) 2. Pick an **Effort** β€” **Quick** (5), **Standard** (15, default), or **Deep** - (50 initial hypotheses) + (50 initial hypotheses) β€” and optionally flip **High risk** on 3. Type your research question and send -**No account. No API key. No configuration** β€” for the visitor. Type a prompt and six -agents generate, debate, and Elo-rank hypotheses, then write a final proposal β€” -Β§-numbered sections, inline `[n]` citations, and a `## References` list included, -rendered visually with Mermaid diagrams, KaTeX math, and charts. Every finished -proposal also has a shareable microsite view (**View as website**, `/s//site`) -with print-to-PDF export. When it's done, ask follow-up questions or request -changes right in the session thread. +**No account. No API key. No configuration** β€” for the visitor. Type a prompt and +the agents generate, debate, and Elo-rank hypotheses, evolve the best across +rounds, self-critique, and adversarially stress-test the top 3 β€” then write a +final proposal with Β§-numbered sections, inline `[n]` citations, and a +`## References` list, rendered visually with Mermaid diagrams, KaTeX math, and +charts. Every finished proposal also has a shareable microsite view +(**View as website**, `/s//site`) with print-to-PDF export. When it's done, +ask follow-up questions or request changes right in the session thread. The UI is an academic "graph-paper" design inspired by [GEML](https://saidlaboratory.github.io/GEML/): serif typography, mono @@ -231,13 +285,40 @@ Quick steps: β”‚ SQLite Β· SSE live stream Β· REST API β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Simulator / real engine β”‚ - β”‚ Generation β†’ Reflection β†’ Ranking β”‚ - β”‚ β†’ Evolution β†’ Proximity β†’ Meta-reviewβ”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό + ─── Simulator / real engine ─── + + Generate hypotheses (literature review + debate) + β”‚ + β–Ό + Reflect (novelty Β· correctness Β· testability) + β”‚ + β–Ό ┐ + Elo tournament β”‚ loop each round + β”‚ β”‚ until the board + β–Ό β”‚ is stable or the + Evolve top ideas β”‚ token budget is + (multi-round) β”‚ spent + β”‚ β”‚ + β–Ό β”‚ + Self-critique β”˜ + β”‚ + β–Ό + Stress-test the TOP 3 ◄── the headline stage + Β· search for contradicting evidence + Β· verify every citation + Β· feasibility + prototype-scale experiment + β”‚ + β–Ό + Apply fixes β†’ final head-to-head re-rank + β”‚ + β–Ό + Meta-review proposal + (inline [n] citations + numbered References) ``` +Proximity clustering runs throughout for dedup and matchmaking. + --- ## βš™οΈ Configuration