ScholarMind

# KnowMind **KnowMind** is an **AI Native Private Knowledge Base Platform**: after users register and log in, they can create multiple knowledge bases, upload PDF documents, and complete automatic parsing and indexing. On the conversation page, based on the selected knowledge base, **Hybrid RAG Retrieval-Augmented Question Answering** can be performed, and the conversation can be refined into structured entries and reports generated. The project adopts a **React (Vite + Tailwind) + FastAPI** single-warehouse architecture. ## Interface Preview > In Cursor / VS Code, use **Markdown Preview** to view screenshots: `Ctrl+Shift+V` (Mac: `Cmd+Shift+V`), or click the preview icon in the top right corner. ### Intelligent Conversation RAG-based streaming question answering based on the selected knowledge base; supports session history, in-depth research / Internet search / arXiv / Semantic Scholar, conversation attachments, file read and write switches, and quick operations such as "Refine to Knowledge Base" and "Generate Report". The `[1]`, `[^2]` reference numbers in the answer text can be clicked to jump directly to the PDF page or knowledge entry.  ### Knowledge Base Create and manage multiple private knowledge bases, displaying the number of documents, storage, and update time; supports creation, renaming, and deletion.  ### Document Management · Document View Select the target knowledge base to upload PDFs (single file ≤ 50MB, up to 20 files at a time), view the parsing status (pending → processing → done / failed), and retry if failed; supports Celery asynchronous parsing or native background thread mode.  ### Document Management · Entry View In addition to the PDF original text, you can also manage **knowledge entries** from conversation refinement, URL collection, and other sources (draft / published / archived), supporting preview, editing, and deletion.  ### Report Generate a structured report with one click from the conversation, displaying the summary and the number of references; the footnotes in the text can be clicked to trace back, supporting export to **Markdown** and **PDF**.  ### Evaluation Dashboard RAGAS / simple metrics (fidelity, answer relevance, context recall / precision) trend and version comparison; can trigger the `knowmind-eval` pipeline through the API to write the report.  ### Tools and Integration Built-in MCP tool switch (Internet search, arXiv, Semantic Scholar, local file read and write, etc.), and supports importing external `mcp.json` configuration from Cursor / Claude and other environments.  ## Feature Overview | Dimension | Description | | --- | --- | | **Product Goal** | Problem → Private RAG (optional MCP extension) → Verifiable, structured answers and reports | | **Typical User** | Individuals or teams who need to manage documents / notes, hope to ask questions about "their own materials" and get answers with basis | | **Technology Stack** | FastAPI, Celery / background thread, Chroma vector + Whoosh BM25, MCP, MySQL multi-tenant isolation | ### Typical Workflow ```mermaid flowchart LR A[Register / Login] --> B[Create Knowledge Base] B --> C[Upload PDF / Collect URL] C --> D[Asynchronous parsing and dual indexing] D --> E[Select knowledge base on conversation page to ask questions] E --> F[Streaming RAG answer + clickable reference] F --> G[Refine entry / Generate report] G --> H[Entry published can be retrieved and cited] ``` 1. **入库**: After PDF upload, the worker extracts text, chunks, and embeddings, and writes to Chroma + Whoosh. 2. **问答**: On the conversation page, select the knowledge base, and the backend retrieves relevant fragments and injects them into the prompt, returning the SSE streaming; the text `[N]` and reference card numbers are consistent and can be clicked to jump to the original text. 3. **沉淀**: The conversation result can be refined into a knowledge entry, or a report with footnotes can be generated with one click. 4. **扩展**: In "Tools and Integration", enable Internet search, academic search, file read and write, or import external MCP. ## Repository Structure | Directory | Description | | --- | --- | | [`knowmind-server/`](knowmind-server/) | **FastAPI** backend: JWT authentication, knowledge base / document / entry / report API, PDF parsing, Chroma + Whoosh indexing, SSE streaming conversation, MCP tool | | [`knowmind-web/`](knowmind-web/) | **React + Vite + Tailwind** frontend: login, knowledge base, document and entry, conversation, report, evaluation, tool, setting and other pages | | [`knowmind-mcp/`](knowmind-mcp/) | Built-in MCP service (Internet search, arXiv, Semantic Scholar, file read and write, etc.) | | [`knowmind-eval/`](knowmind-eval/) | RAG evaluation pipeline (RAGAS + simple fallback metrics) | | [`docs/`](docs/) | Engineering documentation | | [`assets/`](assets/) | README interface screenshot | ## Implemented Features ### Backend (`knowmind-server`) | Module | Capability | | --- | --- | | **Authentication** | Email registration / login; JWT access token + Refresh renewal | | **Knowledge Base** | Create, list, rename, delete (multi-tenant isolated by `user_id`) | | **Document** | Multi-format upload, list, preview, delete, failed retry; local storage | | **Parsing Pipeline** | Text extraction → chunking → embedding (`bge` / `http` / `hash`) → Chroma + Whoosh | | **Knowledge Entry** | Conversation refinement, URL collection, draft / publish / archive lifecycle | | **Conversation** | `POST /api/v1/chat` and `/chat/stream` (SSE); RAG retrieval + `rag_sources` event; in-depth research multi-step prefetch; conversation attachment upload; multi-turn session memory | | **Expert** | Domain expert persona + streaming conversation, supporting academic search switch | | **Report** | Generate structured report from conversation; export Markdown / PDF | | **Evaluation** | Read `knowmind-eval/reports`; `POST /evaluation/run` trigger pipeline | | **MCP** | Built-in Internet search, academic search, file read and write and other tool configuration and switch | | **Task Execution** | Celery + Redis, or `INGEST_BACKGROUND_THREAD=true` native background mode | ### Frontend (`knowmind-web`) | Route | Page | | --- | --- | | `/login` | Login / Register | | `/chat` | Intelligent Conversation (session list, knowledge base switching, streaming Markdown, clickable `[N]` reference) | | `/knowledge-bases` | Knowledge Base Management | | `/documents` | Document View + Entry View | | `/documents/items/:kbId/:itemId` | Entry details and editing | | `/reports`, `/reports/:id` | Report list and details (footnotes can be clicked, PDF export) | | `/evaluation` | RAG Evaluation Dashboard | | `/experts` | Domain Expert List and Conversation | | `/tools` | MCP Tool and Integration | | `/settings` | Account, password and other settings | The conversation and report text use **[Streamdown](https://streamdown.ai/)** + Shiki code highlighting and CJK typesetting; all API requests are encapsulated by `apiFetch`, and **401 automatic Refresh retry**. ## Quick Start ### Environment Requirements | Dependency | Description | | --- | --- | | **MySQL 8.x** | Need to create database and user in advance | | **Redis** | Required when using Celery Worker, default `redis://127.0.0.1:6379/0`; can be started with Docker (see below) | | **EdgeFN (or OpenAI compatible gateway)** | Conversation and (optional) cloud embeddings | | **Node.js + pnpm** | Frontend development | | **Python 3.11+ + uv** | Backend development (recommended) | ### 1. Start Redis (optional, required for Celery mode) ```bash cd knowmind-server docker compose -f docker-compose.redis.yml up -d ``` ### 2. Start Backend ```bash cd knowmind-server cp env.example .env # Edit .env: DATABASE_URL, JWT_SECRET, EDGEFN_API_KEY, etc. uv sync uv run alembic upgrade head uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` - API documentation: <http://127.0.0.1:8000/docs> - Health check: <http://127.0.0.1:8000/api/v1/health> **Two parsing task modes (choose one):** | Mode | Configuration | Description | | --- | --- | --- | | Background Thread (development recommended) | `.env` set `INGEST_BACKGROUND_THREAD=true` | No Celery, parsing executed asynchronously in API process | | Celery Worker | Keep default, **open another terminal** | Share the same `knowmind-server/.env` with API | **Start Celery Worker (production or when not using background thread):** ```bash cd knowmind-server uv run python -m celery -A app.workers.celery_app.celery_app worker -l info ``` Windows PowerShell is the same; Redis needs to be started, and `.env` `INGEST_BACKGROUND_THREAD=false`. ### 3. Start Frontend ```bash cd knowmind-web pnpm install # or npm install pnpm dev # default http://localhost:5173 ``` In the development environment, `/api` is proxied to `http://127.0.0.1:8000` through `vite.config.ts`. ### 4. First Use 1. Open <http://localhost:5173/login> to register and log in 2. Create a knowledge base in "Knowledge Base", and go to "Document Management" to upload PDF 3. Wait for parsing to complete, and then select the knowledge base in "Intelligent Conversation" to start asking questions 4. If the answer appears `[1]` and other numbers, click to jump to the corresponding PDF page or entry ## Main Environment Variables (Backend) Complete description see [`knowmind-server/env.example`](knowmind-server/env.example). | Variable | Effect | | --- | --- | | `DATABASE_URL` | MySQL asynchronous connection (`mysql+asyncmy://...`) | | `JWT_SECRET` | JWT issuance key | | `REFRESH_TOKEN_EXPIRE_DAYS` | Refresh token validity period (days) | | `STORAGE_LOCAL_ROOT` | Upload file local root path | | `CHROMA_DATA_PATH` / `WHOOSH_INDEX_ROOT` | Vector and full-text index directory | | `EDGEFN_API_KEY` / `EDGEFN_API_BASE_URL` / `EDGEFN_CHAT_MODEL` | Conversation model gateway | | `EMBEDDING_MODE` | `bge` \| `http` \| `hash` | | `ARXIV_ENABLED` / `SEMANTIC_SCHOLAR_ENABLED` | Academic search MCP | | `CHAT_ATTACHMENT_ROOT` | Conversation attachment temporary directory | | `EVAL_REPORTS_DIR` | Evaluation report JSON directory | | `INGEST_BACKGROUND_THREAD` | `true` when asynchronous parsing in this process | | `REDIS_URL` / `CELERY_TASK_ALWAYS_EAGER` | Celery task queue | **Do not** submit the real `.env` or key to the repository. ## Test ```bash # Backend cd knowmind-server uv sync --dev uv run pytest tests/ -q # Frontend build cd knowmind-web pnpm run build ``` ## Related Documentation - [**Design and Technical Solution**](docs/KnowMind_设计技术方案.md) · [**Architecture Solution**](docs/KnowMind_架构方案.md) - [knowmind-server README](knowmind-server/README.md)