An open-source, interactive research paper workspace powered by a multi-agent AI runtime.
Reading scientific papers traditionally involves a fragmented workflow: switching continuously between the PDF viewer, search engines, AI chatbots, external dictionaries, and reference lists.
ResearchMind eliminates this context-switching by keeping the PDF as the primary interface. Selecting text, formulas, citations, tables, or figures triggers a swarm of specialized AI agents that analyze the paper's structure and render contextual explanations inline.
Traditional Workflow: PDF ──► Google ──► ChatGPT ──► Wikipedia ──► Back to PDF
ResearchMind Workflow: PDF Selection ──► AI Agent Swarm ──► Contextual Inline Explanation
- Native PDF Workspace: PDF.js canvas and native text-layer rendering with continuous text selection.
- Interactive Element Selection: Instant selection handling for text blocks, formulas, figures, tables, and citations.
- Specialized Agent Swarms: Specialized agents for mathematical derivations, prerequisite concepts, ASCII block diagrams, figure analysis, and citation mapping.
- Multi-Stage Guardrails: Pre-LLM prompt injection defense, post-LLM citation verification against database metadata, and pre-UI schema validation.
- Adaptive Reading Levels: Toggle explanation depth dynamically between Beginner, Undergraduate, and Researcher.
- Progressive Streaming Engine: WebSocket streaming delivering Time-To-First-Token in
< 700ms. - Multi-Tier Caching: Sub-10ms Redis caching for paper structures, contexts, and pre-computed responses.
- Research Notebook & Timeline: Persistent annotation notebook and chronological reading session timeline.
ResearchMind uses a modular runtime architecture separating selection processing, intent routing, context retrieval, safety guardrails, agent orchestration, and streaming layout composition.
┌──────────────────┐
│ PDF Workspace │ (Native Canvas & Text Layer Selection)
└────────┬─────────┘
│ WebSocket Payload
▼
┌──────────────────┐
│ Guardrail Layer │ (Pre-LLM Prompt Injection Defense)
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Intent Router │ (Selective Agent Routing by Content Type)
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Context Builder │ (Single-Pass SharedContext Assembly)
└────────┬─────────┘
│
▼
┌──────────────────┐
│ AI Harness & │ (Concurrent Agent Execution, LLM Router &
│ Agent Swarm │ Token Budget / Cost Telemetry)
└────────┬─────────┘
│
▼
┌──────────────────┐
│Response Composer │ (Markdown Tab Layouts & Reading-Level Adaptation)
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Streaming UI │ (Progressive WebSocket Timeline & Collapsible Accordions)
└──────────────────┘
Detailed technical explanations are available in the Documentation directory.
ResearchMind/
├── backend/ # Python FastAPI Backend
│ ├── src/
│ │ ├── adapters/ # Database, Redis, LLM provider & Telemetry adapters
│ │ ├── domain/
│ │ │ ├── parser/ # PyMuPDF coordinate & layout extractor
│ │ │ ├── services/ # Task queues, cache & session services
│ │ │ └── swarm/ # Agent swarms, intent router & response composer
│ │ └── runtime/ # Core AI Runtime (Harness & Guardrails)
│ └── tests/ # Pytest unit and integration test suite
├── frontend/ # Next.js 15 App Router Frontend
│ └── src/
│ ├── components/ # Workspace panels, PDF viewer & Swarm Analyst UI
│ └── lib/ # Text selection engine & spatial index
├── deploy/ # Docker Compose & service definitions
└── docs/ # Technical architecture documentation
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 15 (App Router), TypeScript | Workspace UI, state management, and sidebars |
| PDF Rendering | PDF.js + HTML5 Canvas | Crisp PDF rendering and continuous text selection |
| Styling | Tailwind CSS v4, Outfit font | Dark-mode scholar workspace aesthetics |
| Backend API | FastAPI, Python 3.11+ | REST endpoints and WebSocket streaming gateways |
| AI Runtime | AIHarness & GuardrailEngine | LLM execution, token budgeting, cost tracking & safety guards |
| Agent Swarm | asyncio, Python threads | Selective concurrent agent execution |
| Vector DB | Qdrant | Cosine-similarity embeddings for paper chunks |
| Relational DB | PostgreSQL | Paper layout trees, notebooks, and reading timelines |
| Cache Layer | Redis | Sub-10ms response and context caching |
- Python 3.11+
- Node.js 18+
- Docker & Docker Compose
git clone https://github.com/Yuyutsu01/ResearchMind.git
cd ResearchMind
cp .env.example .envdocker-compose -f deploy/docker-compose.yml up -dcd backend
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
# source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn src.main:app --port 8001 --reloadcd frontend
npm install
npm run dev -- -p 3001Open http://localhost:3001 in your browser to start reading papers.
System settings and API keys are managed via environment variables defined in .env:
# LLM Providers
GROQ_API_KEY=your-groq-api-key
OPENAI_API_KEY=your-openai-api-key
# Infrastructure
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/researchmind
REDIS_HOST=localhost
REDIS_PORT=6379
QDRANT_HOST=localhost
QDRANT_PORT=6333Refer to .env.example for complete options.
Detailed technical documents are stored in the docs/ directory:
- AI Runtime Architecture — AI Harness, Guardrails, and safety policies.
- Swarm Performance Architecture — 10-phase performance pipeline and caching.
- Response Composer Architecture — Structured markdown rendering and reading levels.
- Background Task Queue — Redis task queue and offline resilience fallback.
- Native PDF text-layer selection engine
- Multi-agent swarm orchestration (
math,background,visual,citation) - Single-pass
SharedContextbuilder &IntentRouter - Multi-stage Guardrail Engine (Pre-LLM injection defense & citation verification)
- AI Harness with token budgeting and cost tracking
- Response Composer & Reading-Level Adaptor
- Redis response caching and progressive WebSocket section streaming
- Cross-paper Knowledge Graph visualization
- Multi-document comparative analysis
- Model Context Protocol (MCP) Tool Integration
- Plugin Agent Registry
Contributions are welcome! Please follow these steps to contribute:
- Fork the repository.
- Create a feature branch (
git checkout -b feature/amazing-feature). - Commit your changes (
git commit -m 'feat: add amazing feature'). - Push to the branch (
git push origin feature/amazing-feature). - Open a Pull Request.
Please ensure all tests pass (pytest and npm run build) before submitting your PR.
Distributed under the MIT License. See LICENSE for details.