CNRS·Université Côte d'Azur·Institut de Chimie de Nice·Centre Inria de l'Université Côte d'Azur·Interdisciplinary Institute for Artificial Intelligence (3iA) Côte d'Azur
HolobiomicsLab

From a bibliography to a first answer

Start with your papers

Install Perspicacité locally, choose a model provider, and build a knowledge base from a collection you already know.

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.

Explore alternative model and embedding presets ↗

Installation

Clone the project and install its dependencies.

Terminal
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.

Terminal
uv pip install -e ".[scilex]"

Configuration

Choose where inference happens.

Terminal
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.

YAML configuration
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.

Read the configuration reference ↗

Open the workspace

Start the interface and backend together.

Terminal
./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:

Terminal
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.

Terminal
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.

Follow the complete BibTeX import guide ↗

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:

Terminal
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.