{"id":50614606,"url":"https://github.com/zuowen7/scholar-assistant-agent","last_synced_at":"2026-06-06T07:02:41.278Z","repository":{"id":362619424,"uuid":"1217529392","full_name":"zuowen7/scholar-assistant-agent","owner":"zuowen7","description":"Open-source Claude Code for academic papers — translate, write, review, and export research papers locally","archived":false,"fork":false,"pushed_at":"2026-06-05T04:28:30.000Z","size":49650,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T07:16:43.445Z","etag":null,"topics":["academic-writing","ai-writing-assistant","desktop-app","fastapi","latex","llm-agent","local-first","machine-translation","monaco-editor","ollama","paper-writing","pdf-translator","peer-review","research-tool","scholar","tauri","thesis","vue3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zuowen7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T01:23:32.000Z","updated_at":"2026-06-05T04:28:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zuowen7/scholar-assistant-agent","commit_stats":null,"previous_names":["zuowen7/scholar-assistant-agent"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/zuowen7/scholar-assistant-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuowen7%2Fscholar-assistant-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuowen7%2Fscholar-assistant-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuowen7%2Fscholar-assistant-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuowen7%2Fscholar-assistant-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zuowen7","download_url":"https://codeload.github.com/zuowen7/scholar-assistant-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuowen7%2Fscholar-assistant-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33972398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["academic-writing","ai-writing-assistant","desktop-app","fastapi","latex","llm-agent","local-first","machine-translation","monaco-editor","ollama","paper-writing","pdf-translator","peer-review","research-tool","scholar","tauri","thesis","vue3"],"created_at":"2026-06-06T07:02:40.588Z","updated_at":"2026-06-06T07:02:41.268Z","avatar_url":"https://github.com/zuowen7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scholar Assistant\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![CI](https://github.com/zuowen7/scholar-assistant-agent/actions/workflows/release.yml/badge.svg)](https://github.com/zuowen7/scholar-assistant-agent/actions)\n[![Version](https://img.shields.io/badge/version-0.4.1-brightgreen)](https://github.com/zuowen7/scholar-assistant-agent/releases)\n\n**English** | [中文](./README_zh.md)\n\n\u003e An open-source AI workstation for academic writing and submission. Write, review, think, and publish — all in one place.\n\n- **Write** — AI companion editor with polish / expand / rewrite; Agent reads and writes project files directly (Claude Code for papers)\n- **Review** — Reviewer-2 adversarial peer review + Claim Ledger to pressure-test logic before you submit\n- **Think** — Mind map + Toulmin argument map to structure ideas and reasoning\n- **Publish** — One-click export to IEEE / ACM / NeurIPS LaTeX templates and Word\n\nPDF translation \u0026 close reading included as an on-ramp — translate a paper in minutes, then work on it. Voice assistant with Siri-style wake word and dictation. Runs locally offline or connects to 21 cloud LLM providers. **Bilingual UI** (zh-CN / en-US).\n\nv0.4.1 — Latest: Agent V2 runtime (9 claw-code modules ported: bash validation, git context, LSP, policy engine, prompt cache, recovery, sandbox, session control, trident compaction), real streaming, skills/hooks/plugins, session fork, 1700+ tests. MIT license.\n\n## Demo\n\n| Review — Adversarial Peer Review | Review — Claim Ledger |\n|----------------------------------|------------------------|\n| ![Reviewer-2 Demo](docs/demo/review.gif) | ![Ledger Demo](docs/demo/precheck.gif) |\n\n| Write — AI Editor + Agent |\n|---------------------------|\n| ![Agent Demo](docs/demo/demo1.gif) |\n\n| Think — Mind Map | Think — Argument Map |\n|-------------------|----------------------|\n| ![Mind Map Demo](docs/demo/mindmap.gif) | ![Argument Map Demo](docs/demo/argument.gif) |\n\n| Voice — Wake Word + Dictation |\n|------------------------------|\n| ![Voice Assistant Demo](docs/demo/voice.gif) |\n\n| More Features |\n|---------------|\n| ![More](docs/demo/demo2.gif) |\n\n\u003e All GIFs are real screen recordings from the v0.3.6 release.\n\n## Download\n\nPre-built installers: [Releases](https://github.com/zuowen7/scholar-assistant-agent/releases) — Windows installer, macOS DMG, Linux AppImage/DEB.\n\n\u003e **Note**: [Ollama](https://ollama.com) is optional — only needed for local/offline translation. Cloud translation works out of the box with an API key.\n\n## Core Features\n\n### AI Editor (Agent V2 as Backbone)\n\n\u003e **Positioning: Claude Code for Papers.** Treat your research project as a workspace; the Agent reads/writes PDFs, drafts, bib files, and data directly — just like Claude Code edits source code. Agent V2 architecture inspired by [ultraworkers/claw-code](https://github.com/ultraworkers/claw-code).\n\n- **Agent V2 Runtime** — ConversationRuntime unified loop, real-time SSE streaming token-by-token; 3-retry error recovery; planning detection + auto-retry; 9 claw-code runtime modules ported (bash_validation, git_context, lsp_client, policy_engine, prompt_cache, recovery, sandbox, session_control, trident)\n- **17 Built-in Tools** — `read_file / write_file / str_replace / grep_files / glob_files / list_dir / run_command / rag_search / web_search / web_fetch / translate_document / export_document / arxiv_search / run_sub_agent` (4 presets: audit/explain/implement/translate); `run_command` protected by bash validation pipeline (read-only mode, destructive command warnings, path validation, command classification)\n- **5-Tier Permission System** — ReadOnly / WorkspaceWrite / DangerFullAccess / Prompt / Allow with allow/deny/ask rule engine; all file ops locked to workspace boundary; sudo wrapping and sed -i blocked in read-only mode\n- **Real-time File Refresh** — Checkpoint SSE events after Agent writes; file tree and editor tabs update instantly\n- **Approval Flow with Pause** — SSE stream pauses on write_file/str_replace; editor shows diff preview (red/green highlights) with Accept/Reject\n- **Skills System** — 6 built-in academic skills + custom `.md` skills from `data/agent_v2/skills/` with YAML frontmatter\n- **Hooks System** — 5 lifecycle hook points (PreToolUse/PostToolUse/PostToolUseFailure/Init/Shutdown), Python callable + Shell command; HookAbortSignal for async cancellation; HookRunResult with updated_input + permission_override support; shell hook JSON stdout parsing with exit code conventions (0=allow, 2=deny, 3=ask)\n- **Plugin System** — YAML manifest plugins bundling skills + hooks + tools, one-click registration\n- **Sub-agent System** — Delegation to specialized sub-agents (audit/explain/implement/translate) sharing the parent Provider\n- **Session Fork** — Branch sessions from any checkpoint, preserving message history and fork metadata\n- **Context Compaction** — Trident 3-stage pipeline (supersede obsolete file ops → collapse chatty exchanges → cluster similar messages), auto-triggered at 950K tokens\n- **Automatic Recovery** — 7 failure scenarios with known recovery recipes, one automatic attempt before escalation\n- **Provider Auto-detection** — Anthropic/OpenAI/DeepSeek/Ollama auto-detect; model aliases (haiku/sonnet/opus/ds/4o); provider quirks auto-adapt\n- **Cost Tracking** — Per-model pricing (Claude/GPT/DeepSeek/Ollama), real-time token and cost statistics\n- **Library (RAG)** — `rag_search` tool queries local vector DB; post-translation auto-ingest\n- **AI Polish / Expand / Coherence / Compliance** — Operate on selected text via the AI Panel\n- **Inline Ghost Text** — Monaco Editor auto-requests completions 1.5s after typing; Tab to accept\n\n### Argument Companion (v3) \u0026 Argument Mapping (v2)\n\n\u003e **Your pre-submission pressure test.** AI proactively finds problems in your logic; you just respond.\n\n- **Claim Ledger** — Auto-extract every promise from abstract/intro; track whether the body delivers (paid / partial / unpaid / mismatch), each anchored to exact character offsets; fuzzy relocation on edits (anchored → drifted → lost 3-state), like `git blame` for arguments\n- **Reviewer‑2 Adversary** — 7 conference-calibrated simulated reviews (NeurIPS / ICML / ICLR / ACL / CVPR / KDD / CHI); each critique anchored to a specific sentence; author drafts rebuttal point-by-point; reviewer can be persuaded; 3-angle parallel review (method/experiment/writing) with auto dedup\n- **Real Review Import** — Paste actual reviewer comments; AI structures them into rebuttal-ready items\n- **Experiment Gap Suggestions** — For each unpaid/partial promise, AI proposes a concrete experiment design\n- **Rebuttal Package Export** — One-click download of all critique points + rebuttal drafts as Markdown\n- **Toulmin Argument Map** — Nodes (Claim / Grounds / Warrant / Backing / Qualifier / Rebuttal) + Relations on a Vue Flow canvas; AI auto-extraction, critique, and suggestions; flatten to structured Markdown/LaTeX paper draft (SSE streaming)\n\n**Status**: Phase 0–5 complete, shipped. 1700+ pytest passed (700+ agent + 1000+ non-agent) + 482 vitest passed.\n\n### Mind Map\n- **Vue Flow Canvas** — Custom node cards + edges (tree/association), drag, zoom, minimap\n- **Node Body Editing** — Each node has an expandable body textarea (▸ button); collapsed view shows first-line preview\n- **Editor Bidirectional Sync** — Editor → mind map auto-parses heading + body; mind map → editor preserves all content (no data loss)\n- **AI Smart Expand** — Generate subtopics based on selected node content\n- **AI Logic Check** — Detect logic chain issues\n- **Undo/Redo** — 100-step history stack, Ctrl+Z / Ctrl+Shift+Z\n- **Auto Layout** — dagre algorithm, one-click organize\n- **Keyboard Shortcuts** — Tab add child, Enter add sibling, F2 edit, Delete remove hovered edge, arrows navigate\n\n### Translation Pipeline\n\n\u003e DeepL-quality PDF translation as an on-ramp — get papers into your workflow in minutes.\n\n- **Smart PDF Parsing** — 16 format parsers, auto-detect single/dual-column layout\n- **Text Cleaning** — 17-stage pipeline: fix line breaks, remove watermarks/headers/footers, handle hyphenation\n- **Reference Skip** — Auto-detect REFERENCES/BIBLIOGRAPHY sections, preserve as-is\n- **DeepL-like Experience** — Side-by-side bilingual view + sentence-level hover highlighting with precise alignment\n- **Real-time Progress** — SSE streaming 5-step pipeline progress, live paragraph preview\n- **Failed Block Retry** — Retry individual failed blocks without re-translating the entire document\n- **Multi-format Export** — Bilingual/translation-only × Markdown/Word (4 formats) + PPTX\n\n### Translation Engines\n- **Local** — Ollama + Qwen3, fully offline, no API key needed\n- **Cloud** — OpenAI / Anthropic / DeepSeek / Moonshot / Zhipu / Qwen / Gemini / SiliconFlow / OpenRouter / Groq / Together / Mistral / xAI / Fireworks / DeepInfra / Perplexity / Novita / Volcengine / Baidu Qianfan / Azure / Custom (21 providers)\n- **Enhanced Prompts** — Strict paragraph structure preservation, reduced alignment failures\n- **Glossary Auto-extraction** — Extract `Chinese(English)` term pairs from translated text, inject into subsequent chunks\n- **Sliding Context Window** — Each chunk carries summaries and terminology from preceding chunks\n\n### Voice Assistant\n\n\u003e **Siri for academic writing** — Say the wake word or press Alt+Shift+V, the Siri overlay appears, speak a command to jump directly to features.\n\n- **Voice Command Router** — Keyword-classified 20+ commands across 5 tiers: navigation (translate/editor/argument/mindmap/theme), file ops (save/new/open), editor (export/polish/expand/review/translate/compliance/citations), translation pipeline (new/retry/export Word/PPTX), mind map (add/delete node/AI expand/layout/zoom); unmatched text falls back to Agent chat\n- **Wake Word** — Web Speech API continuous recognition with homophone variant matching; 5-second cooldown; customizable in settings\n- **Global Hotkey** — `Alt+Shift+V` system-wide (Tauri plugin); works even when window is minimized\n- **Siri-style Voice UI** — fullscreen glass-morphism overlay with pulsing orb + ripple rings + live transcript; 2-second silence auto-submit; shows matched command feedback\n- **Voice Dictation** — mic buttons in editor toolbar, Agent panel, and AI panel; accepts Ghost Text (Tab) mid-speech without losing context\n- **Conflict-free Design** — wake word detection auto-pauses during dictation; no microphone contention\n\n### Editor\n- **Monaco Editor** — Full-featured code editor with Markdown syntax highlighting\n- **AI Panel** — Chat-style UI with message history; polish/expand results shown as diff view, one-click apply/undo\n- **File Tree** — Multi-file management with left sidebar navigation\n- **Template Export** — Pandoc compilation with IEEE / ACM / NeurIPS / LNCS / Elsevier / Generic LaTeX templates\n- **Project Management** — Create projects from templates (Research Paper / Literature Review / Thesis / NeurIPS); auto-generates Markdown outline in `draft/main.md` and switches to mindmap view; recent projects with LRU cache; Git init support\n- **File Tree Actions** — Create files and folders from toolbar or right-click context menu; cut/copy/paste/rename/delete\n\n### Debugging \u0026 Observability\n- **File Logging** — Backend logs written to `RUNTIME_DIR/logs/app.log` (10 MB × 5 rotating backups, each line carries trace_id)\n- **Access Logging** — Every HTTP request logged with method / path / status / duration\n- **Debug Panel** — Top-bar Terminal icon button; shows frontend error history (timestamp + level) and backend logs; red badge when unread errors exist\n\n### Deployment\n- **Desktop** — Tauri 2 packaged; auto-manages Python backend and Ollama processes\n- **Offline Ready** — Release installer bundles Pandoc / Tectonic (with pre-warmed LaTeX cache) / all-MiniLM-L6-v2 embedding model; first-launch seeds to user cache; PDF export and library work offline; default translation engine is cloud (user provides API key)\n- **Docker** — Multi-stage build, one-command containerized deployment\n- **Python CLI** — `python main.py paper.pdf -o paper.md`\n\n## Project Structure\n\n```\n├── src-tauri/                    # Rust + Tauri desktop\n│   ├── src/main.rs               #   Process management (Python API + Ollama, auto-clear proxy env vars)\n│   └── capabilities/             #   Tauri v2 permission configuration\n├── src/                          # Vue 3 frontend\n│   ├── App.vue                   #   Main shell (~684 lines, global state management)\n│   ├── styles/tokens.css         #   Design Tokens (dark/light themes)\n│   ├── composables/\n│   │   ├── useTranslate.ts       #   SSE translation pipeline state (singleton)\n│   │   ├── useAgentChat.ts       #   Agent SSE chat state (singleton)\n│   │   ├── useEditor.ts          #   Monaco Editor + AI Panel (singleton)\n│   │   ├── useFileTree.ts        #   File tree navigation (singleton, create file/folder)\n│   │   ├── useProject.ts         #   Project management (singleton, create/open/close/recent)\n│   │   ├── useMindMap.ts         #   Mind map data + undo/redo (singleton)\n│   │   ├── useArgumentMap.ts     #   Toulmin v2 graph state (singleton)\n│   │   ├── useArgumentCompanion.ts # Argument Companion ledger state (singleton)\n│   │   ├── useSpeechRecognition.ts # Web Speech API (accumulation, dedup, punctuation merge)\n│   │   ├── useSpeechBusy.ts      #   Shared busy flag (wake word ↔ dictation conflict prevention)\n│   │   ├── useWakeWord.ts        #   Wake word detection (continuous SR, homophone matching, cooldown)\n│   │   ├── useGlobalHotkey.ts    #   System hotkey registration (Tauri plugin, Alt+Shift+V)\n│   │   ├── useVoiceCommand.ts    #   Voice command state machine + auto-submit\n│   │   ├── useVoiceRouter.ts     #   Siri-like intent router (keyword classification + command dispatch)\n│   │   ├── useAppMode.ts         #   Global mode/panel state (singleton)\n│   │   └── voiceCommands/        #   Declarative command registry (5 tiers, 20+ commands)\n│   ├── components/\n│   │   ├── AppTopBar.vue         #   Top bar (brand / mode switch / settings / voice settings / window controls)\n│   │   ├── TranslateView.vue     #   Translation mode (upload / progress / result views)\n│   │   ├── AgentPanel.vue        #   Agent side panel (chat / library / templates / sessions)\n│   │   ├── EditorLayout.vue      #   Editor layout (~657 lines, Monaco + AiPanel + FileTree)\n│   │   ├── VoiceAssistantView.vue #   Siri-style fullscreen voice UI (glass morphism, pulse/ripple animation)\n│   │   ├── mindmap/              #   Mind map (Vue Flow canvas + custom nodes/edges)\n│   │   ├── ui/                   #   UI primitives (Button/Input/Panel/Tooltip…)\n│   │   └── …                     #   MonacoEditor, AiPanel, ArgumentMap, etc.\n│   ├── i18n/                     #   Internationalization (vue-i18n v11, zh-CN + en-US ~790 keys each)\n│   ├── utils/\n│   │   ├── api.ts                #   API base URL (auto-detect Tauri vs web)\n│   │   └── streamReader.ts       #   Unified SSE stream parser (6 call sites)\n│   └── types/index.ts            #   Shared TypeScript types\n├── python/                       # Python backend\n│   ├── api_factory.py            #   FastAPI app factory (core logic only)\n│   ├── routers/                  #   Route modules (split by function)\n│   │   ├── translate.py          #   Translation / config / health check routes\n│   │   ├── agent_v2/             #   Agent V2 (ConversationRuntime, claw-code inspired)\n│   │   ├── editor.py             #   Edit / export / Vision / Citation routes\n│   │   ├── argument.py           #   Argument map + Companion v3 routes\n│   │   ├── mindmap.py            #   Mind map persistence + AI analysis/expand\n│   │   └── project.py            #   Project management (create/detect/load/recent/templates)\n│   ├── src/\n│   │   ├── parser/               #   16 format parsers\n│   │   ├── cleaner/              #   17-stage cleaning pipeline\n│   │   ├── chunker/              #   3 chunking strategies (sentence/paragraph/fixed)\n│   │   ├── translator/           #   Ollama + Cloud dual-client (21 providers)\n│   │   ├── formatter/            #   3 output modes + Pandoc export\n│   │   ├── agent_v2/             #   Agent V2 runtime (ConversationRuntime, PermissionPolicy, Skills, Hooks, Plugins, 9 claw-code runtime modules)\n│   │   ├── argument/             #   Argument Map v2 + Companion v3\n│   │   ├── plugin/               #   MCP-style plugin registry\n│   │   ├── citation/             #   Citation indexer\n│   │   ├── zotero/               #   Zotero API integration\n│   │   └── mcp/                  #   Vision client (multi-modal image analysis)\n│   ├── prompts/                  #   Academic writing prompt system (6-layer skeleton + YAML frontmatter)\n│   ├── data/paper_assets/        #   Paper templates (IEEE/ACM/NeurIPS/LNCS/Generic)\n│   └── tests/                    #   Unit + integration tests (incl. E2E companion + adversarial), pytest 1700+ passed\n├── config/default.yaml           #   Source-of-truth default configuration\n├── Dockerfile\n├── docker-compose.yml\n└── package.json\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.12+\n- [Ollama](https://ollama.ai) + Qwen3 model (`ollama pull qwen3:8b`)\n- Node.js 18+, Rust 1.80+ (for desktop development)\n\n### Desktop App (Tauri)\n\n```bash\nnpm install\n\n# Dev mode (auto-clears proxy env vars to prevent httpx import hang)\nstart_dev.bat\n# Or manually clear proxy and run\nnpx tauri dev\n\n# Production build\nnpx tauri build\n```\n\nThe app auto-starts the Python API service and cleans up all subprocesses on window close.\n\n### Python Backend Only\n\n```bash\ncd python\npip install -r requirements.txt\nollama serve                                    # Start Ollama\npython api.py --port 18088                      # Start API server\n# Or use CLI\npython main.py paper.pdf -o paper.md\n```\n\n### Docker\n\n```bash\ndocker compose --project-name scholar-assistant build\n\nOLLAMA_HOST=0.0.0.0:11434 ollama serve\n\n# Windows (Git Bash)\nMSYS_NO_PATHCONV=1 docker run --rm \\\n  -v \"$(pwd)/python/data/input:/data/input:ro\" \\\n  -v \"$(pwd)/python/data/output:/data/output\" \\\n  --add-host=host.docker.internal:host-gateway \\\n  scholar-assistant-app:latest \\\n  /data/input/paper.pdf -o /data/output/paper.md\n```\n\n## API Reference\n\nTranslation SSE event order: `progress` → `parsed` → `cleaned` → `chunked` → `chunk_done`(×N) → `complete`\n\n### Translation\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/translate` | Upload document, returns task_id |\n| `POST` | `/api/translate/path` | Translate from file path |\n| `GET` | `/api/translate/{id}/stream` | SSE translation progress stream |\n| `GET` | `/api/download/{id}` | Download translation result |\n\n### Engine Status\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/health` | Health check |\n| `GET` | `/api/ollama/status` | Ollama status |\n| `GET` | `/api/cloud/status` | Cloud API status |\n| `GET` | `/api/cloud/providers` | List available providers |\n\n### Configuration\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/config` | Read config |\n| `PUT` | `/api/config` | Write config |\n\n### Agent \u0026 Editor\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/agent/v2/chat` | Agent V2 SSE chat (ConversationRuntime) |\n| `POST` | `/api/agent/v2/chat` | Agent V2 SSE chat (session management) |\n| `GET` | `/api/agent/v2/sessions` | List session history |\n| `POST` | `/api/agent/v2/resume/{session_id}` | Resume session |\n| `POST` | `/api/agent/v2/approve/{session_id}/{event_id}` | Approve tool call |\n| `POST` | `/api/agent/v2/abort/{session_id}` | Abort session |\n| `POST` | `/api/agent/v2/undo/{session_id}` | Undo last step |\n| `POST` | `/api/agent/v2/tool` | Direct tool call |\n| `POST` | `/api/edit` | AI-powered SSE streaming edit |\n| `POST` | `/api/complete` | Non-streaming inline completion |\n| `GET` | `/api/agent/stats` | Agent statistics |\n\n### RAG Library\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/rag/documents` | List RAG documents |\n| `POST` | `/api/rag/upload` | Upload file to RAG |\n| `POST` | `/api/rag/ingest` | Ingest text into RAG |\n| `DELETE` | `/api/rag/documents/{doc_id}` | Delete RAG document |\n\n### Argument Map (v2)\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/argument/graph` | Create argument graph |\n| `GET` | `/api/argument/graph/{gid}` | Get argument graph |\n| `GET` | `/api/argument/graphs` | List all argument graphs |\n| `DELETE` | `/api/argument/graph/{gid}` | Delete argument graph |\n| `PUT` | `/api/argument/graph/{gid}/node` | Create/update node |\n| `DELETE` | `/api/argument/graph/{gid}/node/{nid}` | Delete node |\n| `PUT` | `/api/argument/graph/{gid}/edge` | Create/update edge |\n| `DELETE` | `/api/argument/graph/{gid}/edge/{eid}` | Delete edge |\n| `PUT` | `/api/argument/graph/{gid}/span` | Create source text binding |\n| `DELETE` | `/api/argument/graph/{gid}/span/{sid}` | Delete source text binding |\n| `POST` | `/api/argument/graph/{gid}/extract` | SSE extract Toulmin argument graph |\n| `POST` | `/api/argument/graph/{gid}/critique` | AI critique |\n| `POST` | `/api/argument/graph/{gid}/suggest` | AI suggest next element |\n| `POST` | `/api/argument/graph/{gid}/flatten` | SSE flatten to paper draft |\n\n### Writing\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/paper-assets/templates` | List paper templates |\n| `POST` | `/api/paper-assets/ingest` | Index template assets |\n| `POST` | `/api/paper-scaffold` | Generate paper outline |\n| `POST` | `/api/paper-style-transfer` | Style transfer |\n| `POST` | `/api/compliance` | Compliance check |\n\n### Export\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/export/templates` | List export templates |\n| `POST` | `/api/export` | Export document (LaTeX/PDF) |\n| `POST` | `/api/export/pdf` | Export as PDF |\n| `POST` | `/api/export/word` | Export as Word (.docx) |\n| `GET` | `/api/export/word/{filename}` | Download Word export |\n\n### Vision\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/vision/analyze` | General image analysis |\n| `POST` | `/api/vision/ocr` | OCR text extraction |\n| `POST` | `/api/vision/chart` | Chart analysis |\n| `POST` | `/api/vision/table` | Table structure extraction |\n\n### Argument Companion (v3)\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/companion/ledger/build` | SSE build claim ledger (anchor* → promise* → complete) |\n| `GET` | `/api/companion/ledger?doc_id=` | Get ledger |\n| `PUT` | `/api/companion/ledger/promise?doc_id=` | Add/update promise |\n| `DELETE` | `/api/companion/ledger/promise/{pid}?doc_id=` | Delete promise |\n| `POST` | `/api/companion/ledger/relocate?doc_id=` | Relocate all anchors after edits |\n| `POST` | `/api/companion/ledger/promise/{pid}/suggest-experiment?doc_id=` | Experiment gap suggestion |\n| `POST` | `/api/companion/review` | SSE simulated review (review_point* → complete); `mode: \"parallel\"` for 3-angle |\n| `GET` | `/api/companion/review/{session_id}` | Get review session |\n| `GET` | `/api/companion/reviews` | List document review history |\n| `PUT` | `/api/companion/review/{sid}/point/{pid}` | Update critique point status |\n| `POST` | `/api/companion/review/{sid}/point/{pid}/rebut` | SSE rebuttal (reviewer can be persuaded) |\n| `POST` | `/api/companion/review/import` | SSE import real review comments |\n| `GET` | `/api/companion/download/review/{session_id}` | Download rebuttal Markdown package |\n| `DELETE` | `/api/companion/review/{session_id}` | Delete review session |\n\n### Mind Map\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/mindmap/save` | Save mind map |\n| `GET` | `/api/mindmap/load` | Load mind map |\n| `DELETE` | `/api/mindmap` | Delete mind map |\n| `POST` | `/api/mindmap/analyze` | AI analyze mind map |\n| `POST` | `/api/mindmap/expand` | AI expand node |\n\n### Zotero\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/zotero/status` | Connection status |\n| `POST` | `/api/zotero/search` | Search Zotero library |\n| `GET` | `/api/zotero/item/{key}` | Get item metadata |\n| `GET` | `/api/zotero/item/{key}/bibtex` | Get BibTeX |\n| `POST` | `/api/zotero/export` | Export items to file |\n| `POST` | `/api/zotero/citations` | Extract citations |\n\n### Project Management\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/project/templates` | List project templates |\n| `POST` | `/api/project/create` | Create project (Markdown scaffold + Git init) |\n| `POST` | `/api/project/detect` | Detect if path is a project |\n| `GET` | `/api/project/recent` | List recent projects (LRU 20) |\n| `POST` | `/api/project/load` | Load project metadata |\n\n### Debugging\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/logs` | Return last N lines of backend log + log file path |\n\n### Other\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/plugins` | List registered plugin tools |\n| `GET` | `/api/tectonic/status` | LaTeX engine status |\n| `POST` | `/api/tectonic/install` | Install Tectonic |\n| `PUT` | `/api/citation/index` | Index citations |\n| `GET` | `/api/citation/extract` | Extract citations |\n| `POST` | `/api/upload/image` | Upload image |\n| `GET` | `/api/assets/{filename}` | Get asset file |\n\n## Configuration\n\nEdit `config/default.yaml`:\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `parser.engine` | pdfplumber | PDF parsing engine |\n| `chunker.max_tokens` | 800 | Max tokens per chunk (was 2048, too large caused alignment fallback) |\n| `chunker.strategy` | sentence | Chunking strategy |\n| `translator.engine` | cloud | Translation engine: ollama / cloud |\n| `translator.model` | qwen3:8b | Ollama model |\n| `translator.temperature` | 0.3 | Generation temperature |\n| `translator.timeout` | 300 | Translation timeout (seconds) |\n| `formatter.output_format` | bilingual | Output format |\n| `agent.enabled` | true | Whether Agent is enabled |\n| `rag.enabled` | true | Whether RAG is enabled (local only) |\n| `features.parallel_review` | false | 3-angle parallel review (enable in `default.local.yaml`) |\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────┐\n│  Vue 3 + TypeScript + Monaco Editor + Vue Flow           │\n│                   (Vite dev server)                       │\n├──────────────────────────────────────────────────────────┤\n│  Tauri 2 (Rust) — desktop shell, process mgmt            │\n├──────────────────────────────────────────────────────────┤\n│  Python FastAPI + SSE                                     │\n│  ┌──────────┬────────────────┬──────────┬─────────────┐  │\n│  │ Translate│   Agent V2     │ Argument │  Mind Map   │  │\n│  │ Pipeline │ConversationRt  │ Companion│  CRUD+AI    │  │\n│  └──────────┴────────────────┴──────────┴─────────────┘  │\n│  ┌──────────┬──────────┬──────────────────────────────┐  │\n│  │  Parser  │ Cleaner  │ Chunker │ Formatter (Pandoc) │  │\n│  │ (16 fmts)│(17 st.)  │(3 str.) │ LaTeX/Word Export  │  │\n│  └──────────┴──────────┴──────────────────────────────┘  │\n│  ┌──────────────────────────────────────────────────────┐ │\n│  │  Agent V2 Subsystems:                                │ │\n│  │  PermissionPolicy │ ToolRegistry │ Session │ McpMgr  │ │\n│  │  Skills │ Hooks │ Plugins │ UsageTracker │ SubAgent │ │\n│  └──────────────────────────────────────────────────────┘ │\n├──────────────────────────────────────────────────────────┤\n│  LLM Backends: Ollama (local) | Anthropic | OpenAI |     │\n│  DeepSeek | 21 cloud providers (auto-detect)             │\n└──────────────────────────────────────────────────────────┘\n```\n\n### Key Design Decisions\n\n- **Agent V2 (claw-code inspired)** — ConversationRuntime, not LangChain; 9 claw-code runtime modules ported; 700+ tests, 100% deterministic mock coverage\n- **SSE everywhere** — streaming UX for translation, agent chat, argument extraction\n- **Local-first** — all data stays on your machine; cloud LLMs are optional\n- **Workspace-scoped Agent** — file operations locked to project root, 5-tier permission system\n- **MCP + Plugin architecture** — extensible via MCP servers, YAML plugins, Skills, and Hooks\n\n## 21 Cloud LLM Providers\n\nOpenAI, Anthropic, DeepSeek, Moonshot, Zhipu (ChatGLM), Qwen (Tongyi), Gemini, SiliconFlow, OpenRouter, Groq, Together, Mistral, xAI, Fireworks, DeepInfra, Perplexity, Novita, Volcengine (Doubao), Baidu Qianfan, Azure OpenAI, and custom endpoints.\n\n## Argument Companion (Reviewer-2)\n\nA unique feature not found in any other academic tool:\n\n- **Claim Ledger** — automatically extracts promises from abstract/intro and tracks whether the body delivers on each one (paid / partial / unpaid), anchored to exact character offsets with fuzzy relocation on edits\n- **Reviewer-2 Simulation** — calibrated reviews for 7 conferences (NeurIPS, ICML, ICLR, ACL, CVPR, KDD, CHI), with rebuttal mini-chat where the reviewer can be persuaded\n- **Parallel Perspectives** — method / experiment / writing angles reviewed concurrently via `asyncio.gather`\n- **Real Review Import** — paste actual reviewer comments, get structured rebuttal items\n\n## Testing\n\n```\nPython:  1700+ tests passed               (pytest — 700+ agent + 1000+ other)\nFrontend: 482 tests passed / 40 files     (vitest)\n```\n\n```bash\ncd python \u0026\u0026 pytest tests/ -v    # Backend tests\nnpx vitest                       # Frontend tests\n```\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Frontend | Vue 3, TypeScript, Vite, Monaco Editor, Vue Flow |\n| Desktop | Tauri 2 (Rust) |\n| Backend | Python 3.12, FastAPI, SSE |\n| Local LLM | Ollama + Qwen3:8b |\n| Cloud LLM | 21 providers via OpenAI-compatible API |\n| PDF | PyMuPDF, pdfplumber |\n| Vector DB | ChromaDB + all-MiniLM-L6-v2 |\n| Export | Pandoc + 6 LaTeX templates (IEEE/ACM/NeurIPS/LNCS/Generic) + Tectonic |\n\n## Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. Fork the repo and create a feature branch\n2. Make your changes — add tests for new functionality\n3. Run `pytest tests/ -v` and `npx vitest` to verify\n4. Submit a pull request\n\nGood first issues are tagged `good-first-issue`. The project structure is documented in [CLAUDE.md](./CLAUDE.md).\n\n## A Note on Maturity\n\nScholar Assistant is an active personal project under continuous improvement. While the core pipelines (translation, Agent, argument companion, mind map) are battle-tested with 2500+ tests, some features are still maturing — and that's reflected in the [subsystem grades](#subsystem-maturity) above.\n\nIf something breaks or behaves unexpectedly, please [open an issue](../../issues). Bug reports with reproduction steps are incredibly helpful. PRs are welcome too.\n\nThe best is yet to come.\n\n## License\n\n[MIT](./LICENSE)\n\n---\n\nBuilt with Tauri, FastAPI, and too many late nights. If this helps your research workflow, please star the repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuowen7%2Fscholar-assistant-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzuowen7%2Fscholar-assistant-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuowen7%2Fscholar-assistant-agent/lists"}