Before you begin
A local workspace, a model of your choice.
You need Python 3.12 or newer and uv. The web interface also needs Node.js with npm; the repository does not pin a Node version. You need at least one API key for a supported model provider: Anthropic, OpenAI or DeepSeek. The getting-started guide names DeepSeek as the cheapest way to start, while the shipped config.example.yml is an Anthropic preset with a local embedding model. Local Ollama and agent-CLI presets are available under configs/.
Have a small BibTeX file ready for your first collection. Installation downloads dependencies and model weights, and literature discovery needs access to the selected academic services.
Installation
Clone the project and install its dependencies.
git clone https://github.com/HolobiomicsLab/Perspicacite-AI.git
cd Perspicacite-AI
uv sync
For multi-database literature discovery, also install the optional SciLEx integration, which is installed from its GitHub repository. Tools that work on existing knowledge bases do not need it.
uv pip install -e ".[scilex]"
Configuration
Choose where inference happens.
cp config.example.yml config.yml
cp .env.example .env
Add the key for your selected provider to .env. The CLI loads this file at startup; an existing shell environment variable takes precedence. Key names are ANTHROPIC_API_KEY, OPENAI_API_KEY and DEEPSEEK_API_KEY. Keep the provider in config.yml consistent with the key you supply.
This example follows the supplied config.example.yml: an Anthropic model and a local embedding model. Replace the Unpaywall contact address with your own; it is used to discover open-access PDFs.
llm:
default_provider: "anthropic"
default_model: "claude-sonnet-4-5"
knowledge_base:
embedding_model: "all-MiniLM-L6-v2"
pdf_download:
unpaywall_email: "your@email.com"
mcp:
enabled: true
The embedding model determines how a knowledge base is indexed. Choose it before creating the collection: a knowledge base is tied to the embedding model that built it. Hosted embedding models send embedding inputs to their provider; the local model above computes them on your machine.
Open the workspace
Start the interface and backend together.
./dev.sh
Open http://localhost:3000 for the web interface. The backend, the REST API and the MCP server run on port 8000. The script installs frontend dependencies on the first run and stops both processes when you press Ctrl+C.
The backend loads machine-learning models at startup, which can take about a minute and longer on a first run. Give it time to finish before using the interface; initial connection errors can mean it is still loading.
For an API and MCP workflow, the backend can run on its own:
uv run perspicacite -c config.yml serve
Your first collection
Import a bibliography you can recognize.
Use your own refs.bib file in this command. Perspicacité retrieves available content, divides it into passages, computes embeddings and indexes the collection.
uv run perspicacite -c config.yml create-kb my-kb \
--from-bibtex refs.bib \
--description "My research literature"
You can also create a knowledge base in the web interface and upload the bibliography there. Full text depends on availability and your configured access; an abstract-only record is labelled as such.
Ask and inspect
Begin with a focused question.
Select your collection in the web interface and use Basic mode for a first question. An equivalent command-line example is:
uv run perspicacite -c config.yml query \
"Which methods are used in these papers, and what are their limitations?" \
--kb my-kb --mode basic --provider anthropic
Read the answer alongside its sources. Check whether the retrieved material covers your question and whether it comes from full text or an abstract. Try Advanced when the question needs broader retrieval, and expand the collection when relevant papers are missing.