axiom — a research knowledge engine for your Zotero library.

axiom turns the research documents you already manage in Zotero into a searchable, citable knowledge base. It speaks to Zotero's API, processes your library, and exposes a query API for your research clients — retrieve the right passage in the right book, and cite it with a locator that points at the exact page.

Table of contents

• How to get it up
• Documentation
• Big picture
• Contributing
• License

How to get it up

Running 0.2.0? Start with the Operator Migration Guide — the role-based runtime (axiom serve all|api|library|store), the name mapping, and the clean-machine walkthrough. The minimal 0.1.x-style setup below keeps working through the compatibility aliases.

A minimal local setup is two processes on loopback plus two stores:

axiom dispatcher  ──HTTP contract──▶  axiom runner
owns state, queue, search index        does conversion, chunking, ML

1. Run the axiom compute worker (no GPU needed for a first test):

   python3.11 -m venv .venv        # Python 3.11+ required (pyproject floor)
   # installing the project itself ships BOTH packages (canonical +
   # axiom_ng_runner alias) and the axiom-compute-worker console script —
   # requirements alone do not put the module on the path (F10 layout)
   .venv/bin/pip install -r axiom-compute-worker/requirements.txt ./axiom-compute-worker
   export AXIOM_PROCESSOR_COMPUTE=reference
   export AXIOM_PROCESSOR_ALLOWED_SOURCE_ROOTS=<path-to-zotero-storage>  # the `storage` folder of your Zotero data dir
   .venv/bin/python -m axiom_compute_worker   # listens on :8537

2. Run the axiom dispatcher:

   export AXIOM_ZOTERO_BASE=http://localhost:23119/api
   export AXIOM_STORE_DATABASE_URL=postgres://<user>:<pass>@localhost:5432/<db>
   export AXIOM_OPENSEARCH_URL=http://localhost:9200
   export AXIOM_COMPUTE_WORKER_URL=http://127.0.0.1:8537
   export AXIOM_DISPATCHER_ENABLED=true
   cd axiom && go run ./cmd/axiom      # API on :8011

3. Sync Zotero, then watch the pipeline:

   curl -X POST http://127.0.0.1:8011/api/v1/zotero/sync
   curl     http://127.0.0.1:8011/api/v1/ingest/jobs

Requirements: Zotero desktop (Local API enabled), PostgreSQL with pgvector, and OpenSearch. A GPU is optional — everything runs on CPU/Apple MPS for a first test.

Documentation

• Full Documentation — Welcome, Concept Tour, User Guide, Developer Guide, Operations, References.
• Operator Guide: Migrating to 0.2.0 — the 0.2.0 architecture map, name mapping, CLI/config migration, deployment per topology, troubleshooting, and a clean-machine walkthrough.
• Deprecation Schedule — alias policy and counter-based removal criteria.
• Quick Start — get up and running in minutes, with every env var.
• Installation / Deployment — platform-specific setup, including the split-role multi-runner setup (a local retrieval runner plus a remote GPU processing runner).
• Configuration — every AXIOM_* variable in one table.
• User Guide — sync, ingest, retrieval.
• Troubleshooting — common issues and their fixes.

Big picture

axiom is a research RAG: retrieve the right passage in the right book, and cite it with a locator that points at the exact page.

• Zotero is your document and source management. axiom talks to Zotero through its API, mirrors what it needs, and processes the documents — Zotero stays the source of truth, and axiom never replaces it.
• A query API for your research clients. Ask questions that land on the exact book, section, and page — semantic, cross-lingual search with exact source locations.
• A modular runner model. Compute happens in discrete runners that can be placed where it makes sense: ranking and retrieval on a local runner for low latency, chunking and full processing on a strong remote GPU runner.

What a researcher can do

• Turn a Zotero library into a searchable knowledge base without reorganizing it — axiom works with your existing collections, tags, and items.
• Ask a research question and get the right passages from the right books, across languages, with page/line locators for every result.
• Cite with confidence: every result carries its source locator, so you can open the original and verify rather than trust a snippet.

Contributing

The documentation site (MkDocs Material) and the docs in this repository are the guided entry points for contributing. See the Developer Guide for the architecture, contracts, configuration, and testing — and the docs those chapters link to. Reports of issues and pull requests are welcome.

License

Apache License 2.0