Quickstart

Build and Serve

cargo build -p prismdb-cli
./target/debug/prismdb serve --port 6340 --data-dir ./data

One binary, one data directory. Models download on first use; deterministic model outputs (embeddings, NLI verdicts) are cached globally in ~/.cache/prismdb, so only the first-ever run on a machine pays model cost.

On Apple Silicon, set embedding_backend: mlx / nli_backend: mlx in prismdb.yaml (or leave auto); the binary spawns a local sidecar that runs all inference on the GPU.

Create a Collection

Declare which fields are enumerated (exact) and which are free text (semantic):

curl -X POST localhost:6340/api/v1/collections -d '{
  "name": "products",
  "dimensions": [
    {"name": "category", "type": "exact"},
    {"name": "material", "type": "semantic"},
    {"name": "color",    "type": "semantic"},
    {"name": "style",    "type": "semantic"}
  ]
}'

Insert Records

curl -X POST localhost:6340/api/v1/collections/products/records -d '{
  "id": "SKU-001",
  "facts": {
    "category": "footwear",
    "material": "genuine Italian leather",
    "color": "midnight navy",
    "style": "minimalist low-top sneaker"
  }
}'

Records are searchable immediately: every semantic dimension is indexed BM25 sparse + dense on insert.

Learn (Vocabulary Expansion)

Run the cost ladder of write-time expansion tiers so "blue" finds "midnight navy":

curl -X POST localhost:6340/api/v1/collections/products/learn
curl -X POST localhost:6340/api/v1/collections/products/reindex

Learn judges corpus-derived candidates with the NLI cross-encoder and caches every verdict; a warm re-learn takes milliseconds. Reindex rebuilds the BM25 sparse vectors in place to include the learned expansions.

For continuous ingestion, POST /collections/products/graduate does seal → learn → reindex → open-next-segment as one lifecycle step (see Architecture).

Batch acceleration (Apple GPU): pre-fill the NLI pair cache before learn:

prismdb prefill --backend mlx --collection products --data-dir ./data
curl -X POST localhost:6340/api/v1/collections/products/search \
  -d '{"query": "blue leather shoes", "limit": 10}'
{
  "results": [{
    "id": "SKU-001",
    "score": 0.94,
    "facts": {
      "color": "midnight navy",
      "material": "genuine Italian leather",
      "style": "minimalist low-top sneaker"
    },
    "matched_dimensions": ["color", "material", "style"]
  }],
  "elapsed_ms": 5
}

"blue" routed to color and matched "midnight navy" through the learned expansion; "shoes" matched "sneaker". The cross-dimension filter guarantees the result held on every dimension the query touched.

Next Steps