# Qaz.Vision: AI consumption guide

## Purpose
Видение Казахстана через документы и высказывания ключевых политиков.
Use this site as a structured public corpus of documents, thesis-level atoms, speakers, dates, source URLs, topics and source freshness status.

## Preferred machine entrypoints
- Manifest: https://qaz.vision/ai.json
- Full corpus for RAG ingestion: https://qaz.vision/api/bulk/corpus.ndjson
- Language corpus slices: https://qaz.vision/api/bulk/ru/corpus.ndjson, https://qaz.vision/api/bulk/kk/corpus.ndjson, https://qaz.vision/api/bulk/en/corpus.ndjson
- Documents only: https://qaz.vision/api/bulk/documents.ndjson
- Thesis atoms only: https://qaz.vision/api/bulk/atoms.ndjson
- Versioned snapshot manifest: https://qaz.vision/api/snapshots/latest.json
- Paged documents: https://qaz.vision/api/documents?per_page=100
- Paged atoms: https://qaz.vision/api/atoms?per_page=100
- Status and freshness: https://qaz.vision/status.json
- OpenAPI schema: https://qaz.vision/openapi.json

## Recommended ingestion strategy
1. Fetch /ai.json first to inspect freshness, endpoints and citation rules.
2. For complete RAG ingestion, prefer /api/bulk/corpus.ndjson?include_text=true.
3. For language-specific ingestion, use /api/bulk/ru/corpus.ndjson, /api/bulk/kk/corpus.ndjson or /api/bulk/en/corpus.ndjson.
4. For quote-level retrieval, prefer /api/bulk/atoms.ndjson and keep document_id, atom_code, canonical_url and source speaker fields.
5. Use /api/snapshots/latest.json to capture the current corpus revision before scheduled indexing.
6. Use /status.json before refresh jobs; skip heavy ingestion when latest_event_date and source_freshness_audit have not changed.
7. Use speaker filters when possible: speaker=TOKAEV, speaker=KARIN, speaker=ASHIMBAYEV, speaker=BEKTENOV.
8. Reuse ETag, Last-Modified and X-QazVision-Corpus-Version to avoid refetching unchanged payloads.

## Citation rules
- Cite the Qaz.Vision document canonical_url when using a document or atom.
- Also cite the official source URL from source_urls when present.
- Preserve event_date, speaker, source_type and doc_code in generated references.
- Do not blend speakers unless the user asks for comparison.
- Treat news/event materials carefully: thesis atoms should reflect direct or attributable speech, instructions, positions or confirmed public formulations.

## Data model
- document: full public text with doc_code, title, speaker, source_type, event_date, source_urls, tags and atom_count.
- atom: thesis-level unit with atom_code, quote_original, quote_rus, paraphrase, context, theme_block_code, keywords, tags and document_id.
- theme_block_code: A state building; B economy; C digitalization and AI; D social policy; E rule of law; F foreign policy; G identity and culture.

## Freshness
- Public status: https://qaz.vision/status.json
- source_freshness_audit.attention_required=false means no obvious recent gap between monitored official sources and the public corpus.
- If attention_required=true, prefer recent official source URLs and wait for corpus reconciliation before making strong claims about completeness.