Butkhuzi Setup (SNIP Norms Source)

Preferred ingestion path is deterministic parser (xlsx -> JSON payload -> upsert). Use RAG/chunking only for semantic search and assistant UX, not as source-of-truth ingest.

Multilingual fields

butkhuzi_norms supports localized titles via title_i18n JSON map.

Upsert payload row can include:

{
  "title": "Основной заголовок",
  "titleI18n": {
    "ru": "Основной заголовок",
    "en": "Primary heading",
    "ka": "ძირითადი სათაური"
  }
}

Component rows can also include localized labels via components[].labelI18n.

1. Preconditions

• PostgreSQL running on 127.0.0.1:5432
• API services running (services/api and services/svc-tenders)
• Python 3 available (openpyxl is required for XLSX parser)
• Source file available:
  • /mnt/c/Users/User/Downloads/სახარჯთაღრიცხვო გაანგარიშება_ ტომი V-2.xlsx
  • or equivalent normalized workbook with the same structure

2. Apply DB migration

npm --prefix services/svc-tenders run migrate

This creates butkhuzi_norms table.

3. Build upsert payload from SNIP XLSX (recommended)

npm run butkhuzi:build-payload:xlsx -- \
  --inputXlsx "/mnt/c/Users/User/Downloads/სახარჯთაღრიცხვო გაანგარიშება_ ტომი V-2.xlsx" \
  --sourceVersion "SNIP-2026-Q1"

Outputs:

• tmp/outputs/butkhuzi_upsert_payload_xlsx.json (or custom --output)
• tmp/outputs/butkhuzi_build_report_xlsx.json (or custom --report)

Direct python invocation (WSL-safe):

python3 scripts/butkhuzi-build-payload-xlsx.py \
  --inputXlsx "/mnt/c/Users/User/Downloads/სახარჯთაღრიცხვო გაანგარიშება_ ტომი V-2.xlsx" \
  --sourceVersion "SNIP-2026-Q1" \
  --output "tmp/outputs/butkhuzi_upsert_payload_v2_xlsx.json" \
  --report "tmp/outputs/butkhuzi_build_report_v2_xlsx.json"

3.1 Build from SNIP HTML (legacy fallback)

npm run butkhuzi:build-payload -- --sourceVersion "SNIP-2026-02"

Optional (fast test on first files only):

npm run butkhuzi:build-payload -- --maxFiles 3

4. Upsert into Butkhuzi API

npm run butkhuzi:upsert

Upsert custom payload path (recommended after XLSX parse):

npm run butkhuzi:upsert -- --input tmp/outputs/butkhuzi_upsert_payload_v2_xlsx.json

Dry run:

npm run butkhuzi:upsert -- --dry-run

Default URL:

• http://localhost:4001/api/v1/butkhuzi/upsert

Notes:

• sourceVersion is strongly recommended per import batch (for example: SNIP-2026-Q1).
• If omitted, API stores rows with fallback version UNVERSIONED.

Direct svc-tenders URL:

npm run butkhuzi:upsert -- --url http://localhost:4020/butkhuzi/upsert

5. Verify data

curl "http://localhost:4001/api/v1/butkhuzi/norms?page=1&pageSize=20&sourceKey=SNIP&sourceVersion=SNIP-2026-Q1"
curl "http://localhost:4001/api/v1/butkhuzi/suggest?query=1-1&limit=10&sourceKey=SNIP&sourceVersion=SNIP-2026-Q1"

6. Run smoke check

npm run butkhuzi:smoke

7. Build retrieval chunks (RAG-ready layer)

After norms are upserted, rebuild chunk index:

curl -X POST "http://localhost:4001/api/v1/butkhuzi/chunks/rebuild" \
  -H "content-type: application/json" \
  -d '{"sourceKey":"SNIP","sourceVersion":"SNIP-2026-Q1"}'

Search chunks:

curl "http://localhost:4001/api/v1/butkhuzi/search?query=экскаваторы&sourceKey=SNIP&sourceVersion=SNIP-2026-Q1&page=1&pageSize=25"