convez.ai
Agente
yongyong030

research-council

yongyong030/research-council

Ver no GitHub
InicialPluginScore · de 0 a 100

Multi-agent research deliberation for Claude Code — domain-neutral council engine + pluggable domain packs (reproducible runs, self-contained arXiv+RAG, cost-guarded)

Instalação

$npx convez-ai yongyong030/research-council

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Research Council

A multi-agent research deliberation system for Claude Code. Point it at a paper, an idea, or a research question and a council of expert subagents reviews it, stress-tests it, grounds claims in real computation, judges novelty against your own accumulated literature, and ends with an honest proceed / revise / hold recommendation — with every run recorded for reproducibility.

It is built in two layers so it works for any field:

  • core/ — the domain-neutral council engine: chair, skeptic, logic-auditor, external-reviewer, advisor, idea-generator, literature & document & numerical roles, plus the data plumbing (paper intake, RAG accumulation, provenance, vector-DB infra).
  • domains/<field>/ — a domain pack: the subject-matter experts and grounding tools for one field. domains/physics/ is the reference implementation (condensed-matter / orbitronics). Write your own pack for chemistry, biology, ML, economics… (see domains/_template/).

Why two layers: the hard, reusable engineering — reproducible runs, literature ingestion, novelty-vs-your-own-knowledge, multi-agent orchestration with cost guards — is field-independent. Only the experts and the "grounding" calculators change per field. Keep the engine; swap the pack.

What a run does

/council "<paper | arXiv id | research question | idea>"
   intake → filter → selector (fixed 3 + 4 domain experts)
          → base council in parallel  (independent opinions)
          → [grounding: domain tools turn claims into checked facts]
          → chair synthesis
          → [specialist call, only on a real gap]
          → external reviewer  → advisor
          → human approval (never auto-promoted)
          → provenance: every run recorded under runs/<id>/

/research ["<topic>"]   full autonomous cycle: discover → collect → accumulate(RAG) → council → report
/discover               surface emerging topics, flagged by what's NEW to *you* (vs your indexed corpus)

Design choices that make it usable, not just a demo:

  • Reproducible. Each run writes runs/<id>/manifest.json (models, inputs, arXiv snapshot date, RAG state, agents, verdicts) + a paper catalog.json linking papers↔runs. Re-running find dedups topics so an autonomous loop doesn't repeat itself.
  • Cost-guarded. Agents are model-tiered (opus for reasoning, sonnet/haiku for mechanical roles); each dispatched once; bounded tool use. A council fits one usage window.
  • Honest by construction. Separate roles for novelty-checking and over-claim review; the system is built to say "this is already known / this premise is broken" rather than inflate.
  • Grounded. Domain packs ship LLM-free tools (JSON stdout) so experts check facts instead of recollecting them — e.g. physics computes crystal-symmetry-allowed tensor components and fetches Materials Project structures.

Install

Requires Claude Code. From this repo:

# core only (domain-neutral)
./install.ps1 -Target "C:\path\to\my-research-project"

# core + physics reference pack
./install.ps1 -Target "C:\path\to\my-research-project" -Domains physics

This merges core/ + chosen packs into <target>/.claude/agents, .claude/commands, and scripts/. Then open Claude Code in the target project and run /council.

Setup (RAG + backends)

The literature/accumulation features are self-contained — core/scripts/backend/ bundles arXiv collection (arxiv.py) and the RAG store (rag_store.py). No external project needed. You provide a vector DB and config:

  1. Install deps: pip install requests pyyaml sentence-transformers qdrant-client fastmcp defusedxml (+ physics pack: pymatgen mp-api spglib numpy scipy sympy).
  2. Vector DB: run a Qdrant server (server mode — embedded single-locks under concurrent search+ingest). Start with scripts/qdrant_serve.ps1.
  3. Config: copy rc_config.yaml.example → rc_config.yaml at your project root; set qdrant_url, embedding/reranker models, collection.
  4. RAG MCP: register scripts/rag_mcp_server.py as the research_rag MCP server (search_papers / search_notes / search_all) so literature agents can query.

Optional env: RC_PAPERS_DIR (PDF download dir), RC_ARXIV_CATS (discovery categories), MP_API_KEY (physics pack, env only).

Pipeline: index_papers.py add <arxiv_id> → arxiv.to_markdown (.tex source) → rag_store.index_markdown (chunk+embed+Qdrant, incremental). intake.py / discover.py use the same backend.

📋 SETUP.md — a verified reference configuration (the author's actual setup) with the engineering lessons baked in: why server-mode Qdrant, model tiering and cost guards, orphaned-MCP cleanup, embedded→server migration. Point your Claude Code at it to reproduce a working environment.

Scope: arXiv-first. The bundled backend does NOT do non-arXiv PDF extraction, Zotero, or LLM equation cleanup (those were author-specific). arXiv coverage is high for physics/CS/math; add your own collector for other sources.

Writing a domain pack

Copy the shape of domains/physics/ and follow domains/_template/README.md:

  • 3–6 expert subagents on distinct judgment axes (mechanism / method / feasibility / prior-art …), model-tiered.
  • ≥1 grounding tool: LLM-free, JSON stdout, secrets from env.
  • Install with -Domains <yourpack>; combine packs with -Domains physics,<yourpack>.

Layout

core/
  agents/      15 domain-neutral council roles (council-*.md)
  commands/    /council /research /discover
  scripts/     provenance · intake · index_papers · discover · qdrant infra
domains/
  physics/     reference pack: 5 experts + symmetry.py + mp_fetch.py
  _template/   how to author a pack
install.ps1

Roadmap

  • More domain packs (chemistry, ML, bio) as reference implementations.
  • Robustness: network retry/backoff, graceful degradation for the autonomous loop.
  • Claude Code plugin packaging.
  • Additional collectors beyond arXiv (Semantic Scholar, DOI/PDF) as optional backends.

Notes

  • Single LLM = Claude (agents use tiered model: frontmatter). A provider-abstraction for local LLMs is future work.
  • runs/, catalog.json, fetched data, and secrets are git-ignored — they're per-user, not part of the framework.

License

MIT (see LICENSE).

Ver o original no GitHub

Bom para

Relacionados