Add semantic-index service, deployment assets, and tests

2026-05-04 09:50:03 -04:00
parent faad70872b
commit b305544f63
42 changed files with 5059 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Semantic Index V1 Pre-Deployment Manifest
+
+- Patch set: `semantic-index-v1-predeployment-20260425T150000Z`
+- Created: `2026-04-25T15:00:00Z`
+- Purpose: deployment manifest for the Redmine semantic index service and its
+  LAN/production preparation docs.
+
+## Files To Install
+
+```text
+semantic_index/
+tests/semantic_index/
+deploy/semantic-index/
+docs/semantic_index_deployment_runbook.md
+docs/semantic_index_production_notes.md
+docs/semantic_index_predeployment_validation.md
+docs/redmine_issue_api_helpdesk_include.md
+dist/semantic-index-v1-predeployment-20260425T150000Z.MANIFEST.md
+```
+
+## Files Not To Install
+
+```text
+semantic_index/.env
+.cache/
+.venv/
+__pycache__/
+*.pyc
+```
+
+Keep runtime secrets in `semantic_index/.env` or in the service manager
+environment on the target host. Do not commit or copy local secrets into a
+source bundle.
+
+## External Dependencies
+
+- Redmine Helpdesk API patch documented in
+  `docs/redmine_issue_api_helpdesk_include.md`
+- Qdrant reachable through `QDRANT_URL`
+- OpenAI API key for `text-embedding-3-small`
+- Python packages: `openai`, `qdrant-client`, `fastapi`, `uvicorn`
+
+## Validation Commands
+
+```sh
+deploy/semantic-index/install.sh
+.venv/bin/python -m py_compile semantic_index/*.py
+.venv/bin/python -m unittest discover -s tests/semantic_index
+bash -n semantic_index/refresh.sh
+SEMANTIC_INDEX_PROJECT_LIMITS='customer-service=5' semantic_index/refresh.sh
+```
+
+Before any production backfill, follow
+`docs/semantic_index_deployment_runbook.md` and confirm Qdrant snapshot or
+volume rollback is available.
+
+## Operational Rules
+
+- Run `semantic_index/refresh.sh` in dry-run mode before `--apply`.
+- Do not schedule `--force-rebuild`; keep it manual-only.
+- Review refresh logs for `detail_fetched_issues`, `would_embed_documents`, and
+  `embedded_documents`.
+- Bind HTTP to localhost unless LAN access is explicitly required and protected
+  with `SEMANTIC_INDEX_API_KEY`.