Skip to content

API.md

Latest commit

 

History

History
141 lines (111 loc) · 8.45 KB

API.md

File metadata and controls

141 lines (111 loc) · 8.45 KB

LC-0 VIC — API and contracts

This document defines stable JSON-oriented contracts for the Bridge (HTTP) and the CLI, and the internal QueryPlan shape. Field names are snake_case unless otherwise noted.

1. QueryPlan (Librarian output)

Produced by the Librarian from a user string. Consumed by the controller.

Field Type Required Description
intent string yes Short label, e.g. search, list, read_evidence.
l0_filters object no Metadata filters: extensions, path_glob, modified_after, modified_before, min_size, max_size, owner (OS-dependent).
l1_query_text string no Text used to build the query embedding (may differ from raw user text).
l1_threshold number no Default 0.0–1.0 similarity floor for L1 hits.
requires_l2 boolean no If true, controller may run L2 on top-k even if similarity is high (e.g. “show signature”).
l2_skills array of string no Skill names to invoke, e.g. ["pdf_layout", "ocr_image"].
l2_top_k integer no Max files/chunks to deep-parse.
privacy_mode string yes One of: local_only, cloud_reasoning_ok, cloud_embedding_ok (last is discouraged).
raw_user_text string yes Original query for logging/audit.
planner_model_id string no Identifier of the model/backend that produced the plan.

Example

{
  "intent": "read_evidence",
  "l0_filters": { "extensions": [".pdf"], "path_glob": "**/contracts/**" },
  "l1_query_text": "IDR contract signed by whom",
  "l1_threshold": 0.82,
  "requires_l2": true,
  "l2_skills": ["pdf_layout"],
  "l2_top_k": 3,
  "privacy_mode": "local_only",
  "raw_user_text": "Who signed the IDR contract?",
  "planner_model_id": "stub-v0"
}

2. SearchHit (controller output element)

Field Type Description
path string Filesystem path or URI relative to warehouse root.
score number Combined or L1 similarity score (definition logged per release).
tier string L0, L1, or L2.
layers array of string Tiers that contributed to this hit (e.g. ["L0","L1"]); may repeat tier or list merged stages.
excerpt string Short text excerpt or OCR snippet when available.
metadata object L0 fields and optional chunk ids.
reasoning string Short human-readable justification (no fabrication).

3. AskResponse

Field Type Description
query_plan object Echo or normalized QueryPlan.
hits array List of SearchHit.
answer_summary string Optional narrative summary (local or cloud).
warnings array of string e.g. skipped paths, missing optional deps.
stats object or null Aggregated run metadata (ResponseStats); see below.

3.1 ResponseStats

Present when the controller populates diagnostics (tiered and legacy paths).

Field Type Description
pipeline string tiered or legacy.
warehouse_root string Resolved warehouse directory.
db_path string LanceDB directory used for tiered runs (legacy still records configured path).
latency_ms number or null Request processing time (approximate).
embed_model string or null Embedding model id (tiered).
chunk_rows_indexed integer or null Chunk rows from index metadata (tiered).
unique_paths_in_index integer or null Distinct paths after L1 merge (tiered).
l1_candidates_merged integer or null Same as unique paths merged before top‑k cut (tiered).
hits_returned integer Number of hits in hits.
hits_by_tier object Counts keyed by tier label, e.g. {"L1": 2}.
filesystem_files_seen integer or null Files walked (legacy L0).

4. Bridge HTTP (reference)

Base URL configurable (default http://127.0.0.1:8765). Prefix /v1.

Method Path Body Response
GET /health — { "status": "ok", "version": "...", "auth_enabled": bool, "index_ready": bool, "meta_present": bool, "chunk_rows_indexed": int or null, "embed_model": string or null, "vector_backend": string or null, "warehouse_root_indexed": string or null (when meta records it), ... } — same fields as describe_index() in index/readiness.py
POST /v1/ask { "query": "...", "privacy_mode": "local_only", "warehouse_root": "..." } AskResponse (optional warehouse_root; default resolution matches CLI — see warehouse/resolve.py). Rejects bodies larger than VIC_BRIDGE_MAX_BODY_BYTES (default 2 MiB) with 413.
POST /v1/index/start { "root": "...", "db_path": "...", "full": true, "max_files": 1000 } 202 — starts in-process async job and returns { "status":"accepted", "job_id":"..." }
GET /v1/index/status?job_id=... — 200 with job snapshot (running/completed/failed, timestamps, rows) or 404 for unknown id

Authentication: default none. If VIC_BRIDGE_API_KEY is set, all /v1/* routes require Authorization: Bearer <key>. Keep bridge behind TLS/reverse-proxy in production.

Rate limiting: /v1/* requests are counted per client IP in a sliding 60 s window. Default cap VIC_BRIDGE_RATE_LIMIT_PER_MIN = 120 requests/minute (set to 0 to disable). Excess returns 429.

5. Environment variables

Variable Purpose
VIC_DB_PATH Default index directory when CLI omits --db (Lance files and/or Milvus Lite DB under this path).
VIC_WAREHOUSE_ROOT Default warehouse root when vic ask omits --root and JSON omits warehouse_root.
VIC_PRIVACY_MODE Default privacy_mode for CLI and bridge.
VIC_LIBRARIAN_BACKEND stub (default) or ollama.
VIC_OLLAMA_BASE_URL Ollama HTTP API base. Local: http://127.0.0.1:11434. Remote (“cloud”): HTTPS base URL of your hosted Ollama-compatible API. Same code path; privacy rules differ (see librarian/ollama.py).
VIC_OLLAMA_MODEL Tag as returned by ollama list on that server (e.g. qwen2.5:4b, gemma2:2b; exact strings vary by image). Required when backend is ollama.
VIC_OLLAMA_EMBED_MODEL Embedding model for vic index --full and tiered vic ask (default embeddinggemma). Must match the model used at index time.
VIC_OLLAMA_VISION_MODEL Vision model for L2 image verification when enabled (default glm-ocr:q8_0 in vision_ollama; override per your ollama list).
VIC_OLLAMA_API_KEY Optional Authorization: Bearer for gated or proxied Ollama endpoints. Load via .env (gitignored); never commit.
VIC_LOG_LEVEL Python logging level for library logs (WARNING, INFO, DEBUG). CLI configures logging at startup.
VIC_L2_MAX_IMAGE_BYTES Max image file size for vision L2 / Ollama generate-with-images (default ~12 MiB).
VIC_BRIDGE_MAX_BODY_BYTES Max JSON body size for POST /v1/ask (default 2 MiB).
VIC_BRIDGE_API_KEY Optional bearer key for /v1/* bridge routes.
VIC_BRIDGE_RATE_LIMIT_PER_MIN Max /v1/* requests per client IP per rolling minute (default 120; 0 disables).
VIC_JOB_DB_PATH SQLite path for async bridge index jobs (default: vic_jobs.sqlite next to the parent of VIC_DB_PATH).
VIC_VECTOR_BACKEND lance (default) or milvus. Milvus requires pip install -e ".[milvus]" and writes Milvus Lite under VIC_DB_PATH unless overridden.
VIC_MILVUS_URI Optional Milvus Lite file path or server URI (default: <VIC_DB_PATH>/milvus_lite.db).
VIC_MILVUS_COLLECTION Collection name (default vic_chunks).
VIC_SYNTHETIC_JSONL Output path for vic-synthetic-plans (default: training/synthetic_plans.jsonl if ./training exists).

Provide .env.example in the repo root listing these keys without real secret values.

6. CLI mapping

CLI Maps to
vic ask "..." Librarian + controller; --format human or json (default); --root optional (uses env + data/mock_storage fallback).
vic index ... Warehouse walk + index write
vic demo Seed mock warehouse, optional --full ingest, sample asks (--quick skips ingest)
vic bridge Starts HTTP server

Exact flags are defined in src/lc0_vic/cli.py and --help output. Terminal walkthrough: docs/DEMO.md.