redmine/docs/semantic_index_predeployment_validation.md

Semantic Index Pre-Deployment Validation

Validation date: 2026-04-25

This records the current LAN pre-deployment checks for the semantic index. It does not include secrets.

Deploy Unit

Semantic-index deployable files are documented in:

• dist/semantic-index-v1-predeployment-20260425T150000Z.MANIFEST.md
• docs/semantic_index_deployment_runbook.md

Current known unrelated worktree changes are outside the semantic-index deploy unit and should not be mixed into the semantic-index release package:

• redMCP/README.md
• redMCP/app/McpDispatcher.php
• redMCP/app/RedmineClient.php
• redMCP/composer.json
• redMCP/bin/test-redmine-structure.php
• TODO.md

Local Verification

Passed:

.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

Observed semantic test result:

Ran 65 tests in 1.041s
OK

LAN Redmine Preview

Passed:

.venv/bin/python -m semantic_index inspect preview-redmine \
  --project customer-service \
  --limit 5

Observed:

• Helpdesk issue chunks include contact id, name, email, and company metadata.
• Issue 39779 includes Callum Mackeonis and callum@safetagtracking.com.
• Journals are present as separate indexed documents.
• Contact documents are present as separate indexed documents.

Qdrant Audit

Passed:

.venv/bin/python -m semantic_index inspect audit --source redmine --limit 5000 --json

Observed:

total_documents=2947
doc_type contact=714
doc_type issue=1208
doc_type journal=1025
project business-development=66
project customer-service=1684
project dock-scheduling=63
project hiring=409
project prep-standardization=25
project sales-inbox=192
project todo-jason=508
contact_metadata=2232
helpdesk_contact_metadata=2232/2232
attachments=0

HTTP Validation

Passed:

curl -sS http://127.0.0.1:8787/health

Observed:

{"status":"ok"}

Unauthenticated /projects correctly returned unauthorized when SEMANTIC_INDEX_API_KEY was configured.

Authenticated /projects passed and returned the expected seven projects:

business-development
customer-service
dock-scheduling
hiring
prep-standardization
sales-inbox
todo-jason

HTTP search passed:

semantic_index/search.sh "goods return" customer-service 3

Observed:

• Top result was redmine:issue:39779:chunk:0.
• Citation included project customer-service.
• Citation included contact id 1890, contact name, contact email, and Redmine URL.

Refresh Validation

Passed safe dry-run smoke check:

SEMANTIC_INDEX_PROJECT_LIMITS='customer-service=5' semantic_index/refresh.sh

Observed:

mode=dry-run
issues=5
scanned_issues=5
detail_fetched_issues=0
skipped_issues=5
would_embed_documents=0
embedded_documents=0

This confirms the refresh state prefilter skips old issues before Redmine detail fetch and before embedding.

Qdrant Validation

Read-only collection check passed:

collection=redmine_semantic_sample
status=green
vector_size=1536
distance=Cosine
points_count=2947
update_queue.length=0

Read-only snapshot listing endpoint responded successfully:

/collections/redmine_semantic_sample/snapshots
result=[]

No snapshot was created during this validation.

Remaining Pre-Deployment Items

• Decide final target host paths for logs and refresh state.
• Decide service manager shape: manual uvicorn, systemd service, or another supervisor.
• Create or confirm a Qdrant snapshot immediately before production backfill.
• Package only the semantic-index deploy unit, keeping unrelated redMCP worktree changes out of the release.
• Keep scheduled refresh disabled until manual dry-run and --apply logs are reviewed on the target host.