Descriptions (Tier 2)

Every describable entity (not a test, has source, not a one-liner) gets a one-sentence summary, stored in a dedicated summary named vector alongside the code vector so retrieval can target intent or literal code.

Two ways to get a description

• Template (no LLM). Doc-less, non-test Type aliases and Enums without methods get a deterministic templated sentence (e.g. Enumeration Status with members ACTIVE, INACTIVE.). Free and instant; a human docstring always wins over a template.
• LLM-generated. Everything else goes through the configured descriptor model with a trimmed prompt — entity type, qualified name, the extracted doc/leading comment, and a capped source excerpt. Measured ~21% faster per entity than the full-source prompt.

Caching

Descriptions are cached by source hash — unchanged source reuses its cached description on re-ingestion, so incremental ingests only pay the LLM for what changed.

Refreshing descriptions

POST /instances/{project}/describe re-runs only the describe pass — no cgr, no re-embedding of unchanged code. Useful when you switch descriptor models or want to fill gaps without a full re-ingest.

• The cache is still honored by default; pass {"force": true} to bypass it and regenerate every eligible description.
• Anti-drift guard: only chunks whose rebuilt source is byte-identical to what's stored are described. Entities whose source changed on disk are counted stale_source and skipped.
• A transient generation failure never overwrites a good stored description with an empty one — such entities are counted preserved.

Provider

The descriptor is routed through the same provider abstraction as chat: DESC_PROVIDER=ollama (default) | openai | anthropic, selected via environment variables only — there is no /config endpoint for it. See Configuration.