科学AI助手

Requirements

• Python 3.12+
• uv (recommended) or pip

Or from a live literature search (requires SciLEx extra)

uv pip install -e ".[scilex]" uv run perspicacite -c config.yml search-to-kb --query "diamond magnetometry" --kb sensors --max-results 20 ```

Full walkthrough: docs/getting-started.md.

---

Install

git clone https://github.com/HolobiomicsLab/Perspicacite-AI.git
cd Perspicacite-AI
uv sync

Quick Start

Configure

```bash cp config.example.yml config.yml cp .env.example .env

Edit .env — add at least one LLM API key

```

Also set pdf_download.unpaywall_email in config.yml for open-access PDF discovery.

Optional Next.js frontend — :3000 (separate terminal)

cd frontend npm install # first time only npm run dev # http://localhost:3000

Configuration

Copy config.example.yml and edit. Key sections:

llm:
  default_provider: "deepseek"
  default_model: "deepseek-chat"

knowledge_base:
  embedding_model: "text-embedding-3-small"
  chunk_size: 1000

pdf_download:
  unpaywall_email: "your@email.com"

mcp:
  enabled: true

Full schema: docs/reference/config.md.

Alternative config presets: config.ollama.example.yml (local Ollama), config.claude_code.example.yml (Claude Code CLI), config.codex.example.yml, config.hermes.example.yml, config.openclaw.example.yml.

---

Backend — REST API on :8000, MCP at /mcp (loads ML models — ~1 min cold start)

uv run perspicacite -c config.yml serve

REST API

Full JSON API with SSE streaming. Key endpoints:

POST /api/chat · GET /api/kb · POST /api/kb/{name}/bibtex/async · POST /api/kb/{name}/dois/async · GET /api/jobs/{id}/events · GET /api/conversations/{id}/export

Full endpoint list: docs/reference/rest-api.md.

---

CLI Commands

perspicacite serve                  # Start server (web UI + MCP)
perspicacite create-kb NAME         # Create KB (from BibTeX with --from-bibtex)
perspicacite add-to-kb NAME         # Add papers to existing KB
perspicacite list-kb                # List all KBs
perspicacite query QUESTION         # Ask a question against a KB
perspicacite search-to-kb           # Build KB from a literature search
perspicacite expand-kb              # Grow KB via citation graph
perspicacite export-kb              # Export KB (BibTeX / Obsidian vault)
perspicacite screen-papers          # Score candidates by relevance (no server needed)
perspicacite pubmed-search          # Search PubMed to BibTeX (no server needed)
perspicacite import-browser-cookies # Export session cookies for institutional PDF access
perspicacite check-cookies          # Check cookie freshness
perspicacite build-capsule          # Build per-paper capsule (figures, SI, code)
perspicacite build-capsules         # Build capsules for all papers in a KB
perspicacite version                # Show installed version

Full flags and usage: docs/reference/cli.md.

---