API Reference, Client Libraries, and CLI

Installation

NeuronCite ships as a single binary for Windows, macOS, and Linux. No installer is required — place the binary in a directory included in your system PATH and it is ready to use.

• Download the binary for your platform from the distribution archive
• Place it in a directory on your PATH (e.g., /usr/local/bin on Linux/macOS)

Quick Start

Double-click the binary to launch the GUI. On first launch, a welcome dialog appears that shows the live status of all runtime dependencies on your system. Each component is listed with its current availability (present or missing). You have two options:

• Download and install everything — installs pdfium, Tesseract, ONNX Runtime, and the default embedding model (BAAI/bge-small-en-v1.5, ~130 MB) in one sequential run. Progress is shown per step.
• I will set it up myself — skips the automatic setup. You can install individual components later via the Settings → Dependencies panel in the GUI.

Nothing is downloaded without your explicit consent. All downloaded files are stored in the NeuronCite data directory under models\, runtime\, and indexes\. After the initial setup, NeuronCite runs fully offline. See the GUI Workflow page for a full walkthrough of the 7-tab interface.

Runtime Dependencies

NeuronCite requires several runtime libraries that are not bundled with the binary. The welcome dialog and the Settings → Dependencies panel (or /api/v1/health via REST) detect which are missing and let you install them individually:

• pdfium — PDF text and structure extraction. Installable via the GUI.
• ONNX Runtime — AI inference engine for embedding and reranker models. Installable via the GUI (CPU or GPU/CUDA variant).
• Embedding model — At least one model (e.g., BAAI/bge-small-en-v1.5, ~130 MB from HuggingFace). Downloaded during setup or on first indexing operation.

Optional:

• Tesseract OCR — Fallback text extraction for scanned PDF pages where pdfium returns no text. Installable via the GUI.
• Ollama — Local LLM server for autonomous citation verification. Install manually from ollama.com.
• poppler (pdftotext) — Alternative PDF extractor. Not required when pdfium is installed.

CLI Usage

For headless or scripted workflows, the following commands are also available:

# Start the GUI (opens browser)
neuroncite web

# Or start headless API server
neuroncite serve --port 3030

# Index a PDF directory from CLI
neuroncite index --directory /path/to/pdfs

# Search from CLI
neuroncite search --directory /path/to/pdfs --session-id 1 \
    --query "transformer architecture"

Configuration

NeuronCite reads configuration from a TOML file. The file is auto-detected from standard platform configuration directories. All settings have sensible defaults and can be overridden via CLI flags.

port = 3030
bind_address = "127.0.0.1"
log_level = "info"
default_model = "BAAI/bge-small-en-v1.5"
default_strategy = "token"
default_chunk_size = 256
default_overlap = 32

[defaults]
top_k = 10

Authentication

No authentication is required for local access from 127.0.0.1. For remote access, NeuronCite supports an optional bearer token generated with the --print-token flag when starting the server. Rate limiting is applied per IP address with automatic failure tracking.

• Local connections (127.0.0.1) bypass authentication
• Remote connections require a bearer token in the Authorization header
• Generate a token: neuroncite serve --print-token
• Rate limiting tracks failed authentication attempts per IP

Indexing Endpoints

Endpoints for creating indexing jobs and scanning directories for supported files.

Search Endpoints

Endpoints for hybrid vector and keyword search, multi-session search, and claim verification against indexed chunks.

Content Endpoints

Endpoints for retrieving page text from indexed documents and browsing chunks within a file.

Citation Endpoints

Endpoints for the full citation verification lifecycle: creating jobs, claiming batches, submitting verdicts, retrieving status, exporting results, retrying failures, and fetching source PDFs.

Annotation Endpoints

Endpoints for highlighting text passages in PDFs from inline data or a file path.

Session Endpoints

Endpoints for listing, deleting, optimizing, and rebuilding indexing sessions. Each session represents a distinct document corpus with its own vector and keyword indices.

System Endpoints

Endpoints for health checks, backend detection, job management, quality reports, file comparison, and server lifecycle.

Python Client Installation

The Python client wraps all REST API endpoints with typed methods. It requires Python 3.10 or later and requests >= 2.31.0.

# From PyPI (not yet published):
# pip install neuroncite

# From source:
pip install ./clients/python

NeuronCiteClient

The NeuronCiteClient class provides methods for indexing, search, citation verification, session management, and document content retrieval. All methods communicate with the NeuronCite server over HTTP.

from neuroncite import NeuronCiteClient

client = NeuronCiteClient(
    base_url="http://127.0.0.1:3030",
    timeout=30.0,
    token=None  # bearer token for remote authentication
)

# Health check
health = client.health()

# Index a directory
job = client.index(
    directory="/path/to/pdfs",
    model_name="BAAI/bge-small-en-v1.5",
    chunk_strategy="word",
    chunk_size=300
)

# Wait for indexing to complete
client.wait_for_job(job.job_id)

# Search (hybrid vector + BM25 by default)
results = client.search(
    session_id=1,
    query="transformer architecture",
    top_k=10
)

# Citation verification
citation_job = client.citation_create(
    tex_path="/papers/paper.tex",
    bib_path="/papers/refs.bib",
    session_id=1
)

Indexing and Search

• index(directory, model_name, chunk_strategy, chunk_size) — Create an indexing job for a directory of documents
• discover(directory) — Scan a directory for supported files
• search(session_id, query, top_k, use_fts, rerank, refine) — Hybrid vector and keyword search within a session
• hybrid_search(session_id, query, top_k, ...) — Alias using the /search/hybrid endpoint
• multi_search(session_ids, query, top_k) — Search across multiple sessions
• verify(session_id, claim, chunk_ids) — Heuristic claim verification against specific chunks
• wait_for_job(job_id, poll_interval, timeout) — Poll until a background job completes

Sessions and Content

• list_sessions() — List all indexing sessions with metadata
• delete_session(session_id) — Delete a session and its indices
• delete_sessions_by_directory(directory) — Delete all sessions for a directory
• optimize_session(session_id) — Trigger FTS5 full-text index optimization
• rebuild_index(session_id) — Trigger HNSW vector index rebuild
• get_page(file_id, page_number) — Retrieve extracted text for a specific page
• list_chunks(session_id, file_id, page_number, offset, limit) — Browse document chunks with pagination
• quality_report(session_id) — Text extraction quality report for a session
• compare_files(file_path, file_name_pattern) — Compare a file across sessions

Citation Verification

• citation_create(tex_path, bib_path, session_id) — Create a citation verification job from LaTeX and BibTeX files
• citation_claim(job_id, batch_id) — Claim a batch for verification processing
• citation_submit(job_id, results) — Submit verification results for a batch
• citation_status(job_id) — Get citation job status and progress
• citation_rows(job_id, status, offset, limit) — Get citation rows with optional status filter
• citation_export(job_id, output_directory, source_directory) — Export citation verification results
• citation_auto_verify(job_id, model, ollama_url) — Start automatic LLM-driven verification
• citation_fetch_sources(bib_path, output_directory, delay_ms, email) — Download cited source documents (PDFs and HTML pages)
• citation_parse_bib(bib_path, output_directory) — Parse BibTeX file for preview
• citation_bib_report(bib_path, output_directory) — Generate bibliography report

Annotation and System

• annotate(source_directory, output_directory, input_data, default_color) — Highlight text passages in PDF files from inline data
• annotate_from_file(input_file, source_directory, output_directory) — Annotate PDFs from a file path
• health() — Server health check and build feature report
• backends() — List compiled-in embedding backends
• get_job(job_id) — Poll a single background job
• cancel_job(job_id) — Request cooperative cancellation of a job
• list_jobs() — List all tracked background jobs
• shutdown() — Gracefully stop the server

NeuronCiteServer

The NeuronCiteServer class manages the lifecycle of a NeuronCite server process. It starts the binary as a subprocess, waits for the HTTP endpoint to become available, and provides a clean shutdown method.

from neuroncite import NeuronCiteServer

server = NeuronCiteServer(
    binary_path="neuroncite",
    port=3030,
    bind_address="127.0.0.1",
    log_level="info"
)
server.start()  # blocks until health endpoint responds

# ... use NeuronCiteClient ...

server.stop()

Claude Code Integration

NeuronCite includes built-in commands for registering and managing the MCP server in Claude Code. The install command writes the configuration to ~/.claude/settings.json.

# Automatic registration
neuroncite mcp install

# Check status
neuroncite mcp status

# Manual removal
neuroncite mcp uninstall

MCP Configuration

The MCP server configuration is stored in the Claude Code settings file. The following JSON block shows the expected structure after running neuroncite mcp install.

{
  "mcpServers": {
    "neuroncite": {
      "command": "neuroncite",
      "args": ["mcp", "serve"]
    }
  }
}

• The MCP server communicates via JSON-RPC 2.0 over stdio
• 43 tools are registered automatically on connection
• See the MCP Integration page for the full tool reference

neuroncite web

Starts the browser-based GUI. Opens the default system browser and serves the SolidJS frontend via the embedded web server.

neuroncite web [--port 3030] [--bind 127.0.0.1]

• --port — HTTP port (default: 3030)
• --bind — Bind address (default: 127.0.0.1, use 0.0.0.0 for LAN access)

neuroncite serve

Starts the headless API server without opening a browser window. Suitable for server deployments and automated pipelines.

neuroncite serve [--port 3030] [--bind 127.0.0.1] [--print-token]

• --port — HTTP port (default: 3030)
• --bind — Bind address (default: 127.0.0.1)
• --print-token — Generate and print a bearer token for remote authentication

neuroncite index

Index documents from the command line. Scans the specified directory, extracts text, chunks it, computes embeddings, and stores the results in the session database.

neuroncite index --directory /path/to/pdfs \
    [--model BAAI/bge-small-en-v1.5] \
    [--strategy token] \
    [--chunk-size 256] \
    [--overlap 32]

• --directory — Path to the document directory (required)
• --model — Embedding model identifier (default: BAAI/bge-small-en-v1.5)
• --strategy — Chunking strategy: page, word, token, or sentence (default: token)
• --chunk-size — Number of units per chunk (default: 256)
• --overlap — Overlap between consecutive chunks (default: 32)
• --ocr-language — Tesseract language code for OCR fallback (default: eng)
• --quiet — Suppress progress output

neuroncite search

Execute search queries against indexed sessions. Supports single queries and batch mode from a JSONL file.

# Single query
neuroncite search --directory /path/to/pdfs --session-id 1 \
    --query "topic" [--top-k 10] [--hybrid] [--rerank]

# Batch mode from JSONL file
neuroncite search --directory /path/to/pdfs --session-id 1 \
    --batch queries.jsonl

• --directory — Path to the indexed document directory (required)
• --session-id — Target session identifier (required)
• --query — Search query string (mutually exclusive with --batch)
• --top-k — Number of results to return (default: 10)
• --hybrid — Enable hybrid vector + BM25 retrieval
• --rerank — Enable cross-encoder reranking
• --batch — Path to a JSONL file containing multiple queries

neuroncite mcp

MCP server management commands for starting the stdio server, registering in Claude Code, and checking registration status.

neuroncite mcp serve [--model BAAI/bge-small-en-v1.5]
neuroncite mcp install
neuroncite mcp uninstall
neuroncite mcp status

• serve — Start the MCP stdio server for AI agent communication
• install — Register the MCP server in Claude Code settings
• uninstall — Remove the MCP server registration
• status — Display the current registration status

neuroncite models

Embedding model management commands for listing available models, downloading model weights, and verifying integrity.

neuroncite models list
neuroncite models info BAAI/bge-small-en-v1.5
neuroncite models download BAAI/bge-small-en-v1.5
neuroncite models verify BAAI/bge-small-en-v1.5
neuroncite models system

• list — Show all available embedding models with dimensions and parameters
• info — Show detailed configuration for a specific model
• download — Download ONNX model weights for the specified model
• verify — Check model file integrity (SHA-256)
• system — Show system capabilities and GPU information

neuroncite doctor

System capabilities check. Reports GPU availability, CUDA runtime status, Tesseract OCR installation, and pdfium library presence.

neuroncite doctor

Other Commands

Additional CLI commands for export, annotation, session listing, and version information.

• neuroncite export — Export search results (markdown, bibtex, csl-json, ris, plain-text)
• neuroncite annotate — Annotate PDFs from CSV/JSON input file
• neuroncite sessions — List all sessions for a directory
• neuroncite version — Show version and build features