FlockMind

English | 中文

FlockMind is a multi-agent research assistant for academic writing, literature-grounded drafting, thesis drafting, domain research workflows, skill management, and paper translation. The project started as an entry for the SJTU AI Application Innovation Contest, inspired by the coordinated behavior of pigeons around Siyuan Lake: specialized agents work together to plan, search, read, synthesize, draft, review, and export research artifacts.

The integrated release branch is main. It includes the MEM thesis workflow, research-paper workflow, LaTeX export/project packaging, compile/PDF preview, paper translation, domain workbench, and skills library.

Current Capabilities

• Research writing workflow through /research.
• First-class artifacts: paper_draft, research_paper, literature_review, and literature_brief.
• Research-paper mode with bounded agentic literature search, outline confirmation, LaTeX source export, LaTeX project ZIP export, compile check, and PDF preview when a TeX engine is installed.
• MEM thesis workflow through /thesis, including academic-integrity disclaimer, chapter review gate, GB/T 7714 reference rendering, and Markdown export.
• Paper translation workflow through /translation, including status polling and downloadable PDF/Markdown/ZIP outputs.
• Domain workbench, skills library, history, and settings pages.

Result Evidence Screenshots

The capabilities below are implemented and covered by release tests. These image slots are reserved for result evidence only: replace the placeholders before release with screenshots from traceable real runs, accepted pilot artifacts, or reproducible release artifacts. Use generated result screenshots, not process/setup screenshots or mocked output.

Capability	Reserved result screenshot	Replacement rule
Research paper generation		Show the completed research-paper result, LaTeX/PDF preview, or exported artifact summary from a traceable run.
MEM thesis generation		Show the completed thesis result, chapter-reviewed output, or Markdown export from a traceable run.
Paper translation		Show the completed translated output or downloadable result from a traceable run.

Research-paper evidence boundary:

• LiteratureAgent performs bounded agentic search for research_paper runs and keeps source lineage in the evidence payload.
• The workflow must fail closed on missing prerequisites, including a missing API key, unavailable search provider state, or raw-query fallback that cannot produce auditable source lineage.
• source_evidence_texts and at least two distinct supporting_titles are required before claims can proceed into the manuscript path.
• These gates prevent unsupported literature synthesis from entering outline/writing when the evidence boundary is not satisfied.

Integrated LaTeX project workflow:

• /api/research/runs/{run_id}/export/latex/compile provides compile preview status.
• /api/research/runs/{run_id}/export/latex/pdf returns the compiled PDF when a local TeX engine succeeds.
• /api/research/runs/{run_id}/export/latex/project exports the external-editor project ZIP.
• The project ZIP includes an author revision guide, submission checklist, evidence/citation/quality-review audit pack, and generic journal, ACM, IEEE, and NeurIPS-style venue readiness profiles.

Repository Layout

agents/      multi-agent orchestration, workers, LLM abstractions, tools
backend/     FastAPI runtime, policy contracts, exports, translation routes
frontend/    React + TypeScript + Vite UI
prompts/     prompt templates
skills/      filesystem-backed agent skills
tests/       backend pytest suite
docs/        architecture, plans, release notes, samples, evidence
scripts/     verification and pilot scripts

Prerequisites

• Python 3.10 or newer.
• uv for the Python environment.
• Node.js and npm for the frontend.
• Optional: latexmk, tectonic, or pdflatex for local research-paper PDF compile checks.

Configuration

Copy env.example to .env and fill only the providers you plan to use.

cp env.example .env

Important local defaults:

• Backend: API_HOST=0.0.0.0, API_PORT=8100
• Frontend: FRONTEND_PORT=3100
• Frontend dev proxy: /api, /translation_jobs, and /ws forward to the backend origin generated by scripts/sync_frontend_env.js.

If no model API key is configured, parts of the system may fall back to simulated responses, but provider-backed quality checks require real keys.

Provider API keys belong in .env; this is the intended local configuration path. Do not commit .env, generated frontend/.env.local, or command output that prints real key values.

Optional CNKI / Wanfang authenticated search uses formal runtime tools (cnki_search and wanfang_search) that read user-supplied cookies from the ignored secrets/ directory at execution time. See secrets/README.md before using those tools.

Backend Setup

uv sync --active
uv run python backend/main.py

Useful API surfaces:

• GET /api/health
• POST /api/research/outline
• POST /api/research/start
• GET /api/research/status/{task_id}
• GET /api/research/result/{task_id}
• GET /api/research/runs/{run_id}
• POST /api/research/runs/{run_id}/actions/{action_id}
• GET /api/research/runs/{run_id}/export/markdown
• GET /api/research/runs/{run_id}/export/latex
• POST /api/research/runs/{run_id}/export/latex/compile
• GET /api/research/runs/{run_id}/export/latex/pdf
• GET /api/research/runs/{run_id}/export/latex/project

Frontend Setup

cd frontend
npm install
npm run dev

Open http://127.0.0.1:3100/.

The frontend predev and prebuild scripts run scripts/sync_frontend_env.js to generate frontend/.env.local from the root .env.

Testing

Backend:

uv run pytest -q

Frontend:

cd frontend
npm run test:critical
npm run test:behavioral
npm run build
npm run test:e2e -- --reporter=line
npm audit --audit-level=high

In sandboxed environments, Playwright may need permission to access http://127.0.0.1:3100. The UI e2e project starts a local Vite webServer with backend fixtures and does not require a live backend.

Research-paper evidence verifiers:

uv run python scripts/verify_research_paper_latex_quality.py <path-to-main.tex>

Known Release Gates

Before publishing, verify:

• LICENSE exists and matches package metadata.
• README commands match the current repository.
• Backend full pytest passes.
• Frontend high/critical npm audit findings are resolved.
• Frontend build, critical tests, behavioral tests, and Playwright UI e2e pass.
• Secret and git-history scans have no publish-blocking findings.
• Release screenshots used as capability evidence are traceable to real runs or accepted artifacts; mocked screenshots, if any, are labeled as UI samples only.

License

MIT. See LICENSE.