Incomex AI Portal
KB-2E32 rev 2

P3D — Vector Search Hybrid Boost — Implementation Prompt rev2

12 min read Revision 2
p3dvector-searchimplementationpromptrerankboostrev2gpt-patched

P3D — Vector Search Hybrid Path/Title Boost — Implementation Prompt rev2

Date: 2026-05-11 Status: PROMPT rev2 — GPT patched for production safety; READY_FOR_USER_APPROVAL_BEFORE_DISPATCH Mode: IMPLEMENTATION — agent may modify Agent Data search code only after preflight confirms safe runtime linkage Design ref: knowledge/dev/laws/dieu44-trien-khai/design/p3d-vector-search-hybrid-path-title-boost-design.md Audit ref: knowledge/dev/laws/dieu44-trien-khai/reports/p3d-vector-search-freshness-audit-report.md Hard boundary: NO Qdrant mutation, NO reindex, NO PG schema change, NO IU vector implementation

0. Objective

Add a minimal app-layer rerank step to Agent Data search so exact path/title/document-name queries rank the correct KB document first, while preserving semantic search quality.

Root cause to fix:

SEARCH_RANKING_NO_PATH_TITLE_BOOST_NOT_VECTOR_FRESHNESS

Do not reindex or mutate Qdrant. Recent documents are already vectorized. The defect is ranking.

1. Hard boundaries

  • No Qdrant collection replacement.
  • No Qdrant point delete/upsert.
  • No bulk reindex.
  • No auto-heal.
  • No /kb/reindex.
  • No /kb/reindex-missing.
  • No /kb/cleanup-orphans write mode.
  • No PG schema mutation.
  • No DB INSERT/UPDATE/DELETE.
  • No trigger/function/index/permission changes.
  • No TAC/IU migration.
  • No IU vector implementation.
  • No event_outbox change.
  • No Pack 1 DDL.
  • No docker-compose or .env edit in this first patch unless GPT/User explicitly approves later.
  • Do not deploy/restart until preflight, backup, and code diff are complete.

Allowed:

  • Read current source and runtime config.
  • Patch Agent Data search application code if runtime linkage is confirmed.
  • Restart only the Agent Data service after patch if needed and safe.
  • Upload implementation report to KB.

2. Preflight — mandatory before any code change

2.1 Discover runtime, do not assume names

set -uo pipefail
TS=$(date +%Y%m%d-%H%M%S)
LOG="/tmp/p3d-vector-search-boost-${TS}.log"
exec > >(tee -a "$LOG") 2>&1

echo "=== PREFLIGHT $TS ==="
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'

Identify:

AGENT_DATA_CONTAINER=<running Agent Data container, likely incomex-agent-data>
QDRANT_CONTAINER=<running Qdrant container, likely incomex-qdrant>
AGENT_DATA_REPO=<host repo path, likely /opt/incomex/docker/agent-data-repo>
DOCKER_COMPOSE_DIR=<compose dir, likely /opt/incomex/docker>

Do not hardcode qdrant container name.

2.2 Verify source path and runtime linkage

cd /opt/incomex/docker/agent-data-repo || exit 2
pwd
git status --short
ls -la agent_data/vector_store.py agent_data/server.py

# Inspect whether repo is mounted into running container or build-only.
docker inspect "$AGENT_DATA_CONTAINER" --format '{{json .Mounts}}' | python3 -m json.tool || true

docker exec "$AGENT_DATA_CONTAINER" sh -lc 'ls -la /app/agent_data/vector_store.py /app/agent_data/server.py 2>/dev/null || true'

If the running container does not use the host repo or if it is unclear whether restart will load the patched code, STOP and report BLOCKED_RUNTIME_LINKAGE_UNCLEAR. Do not improvise rebuild/deploy.

2.3 Baseline health and point count

curl -s http://localhost:8000/health || true

docker exec "$QDRANT_CONTAINER" sh -lc "curl -s http://localhost:6333/collections/production_documents" | tee /tmp/p3d-qdrant-before-${TS}.json

Record points_count from Qdrant before patch.

2.4 Baseline search tests

Run the six test queries through the real Agent Data search path. Prefer the same endpoint/tool that backs searchKnowledge. If MCP searchKnowledge is unavailable to the agent, use the Agent Data HTTP search/chat endpoint and record the request/response.

Test queries:

T1: GPT Review P3D Step 1 Re-authored Spec Pack 1 Directive
Expected target: knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-review-p3d-step1-reauthored-spec-and-pack1-directive-2026-05-10.md

T2: p3d-pack1-readonly-inventory-prompt revision 2
Expected target: knowledge/dev/laws/dieu44-trien-khai/prompts/p3d-pack1-readonly-inventory-prompt.md

T3: gpt-directive-agent-run-step1-checkpoint-and-pack1-inventory-readonly
Expected target: knowledge/dev/laws/dieu44-trien-khai/directives/gpt-directive-agent-run-step1-checkpoint-and-pack1-inventory-readonly-2026-05-10.md

T4: p3d-agent-vector-search-freshness-audit-readonly 2026-05-10
Expected target: knowledge/dev/laws/dieu44-trien-khai/prompts/p3d-agent-vector-search-freshness-audit-readonly-2026-05-10.md

T5: vector search freshness root cause
Expected: relevant vector/search audit documents in top 5.

T6: operating rules SSOT
Expected: relevant operating-rules/SSOT documents in top 5.

Record baseline rank for each expected target.

3. Backup before patch

Before editing any file:

cd /opt/incomex/docker/agent-data-repo
BACKUP_DIR="/tmp/p3d-vector-search-boost-backup-${TS}"
mkdir -p "$BACKUP_DIR"
cp agent_data/vector_store.py "$BACKUP_DIR/vector_store.py.before"
cp agent_data/server.py "$BACKUP_DIR/server.py.before"
git status --short

If repo is dirty before patch, record dirty files. Do not overwrite unrelated local changes. If target files are already dirty, STOP and report unless the diff is clearly from this task.

4. Implementation approach

Patch the smallest appropriate application-layer function.

Preferred patch point from audit:

agent_data/vector_store.py search logic after Qdrant result construction/dedup and before returning final top_k results.

If actual code differs, adapt minimally and report exact function/line changed.

4.1 Required behavior

Add a pure rerank function that:

  1. Takes query and candidate results.
  2. Does not call Qdrant or PG.
  3. Does not mutate persistent data.
  4. Computes boost using:
    • full document_id / path match;
    • basename/filename slug match;
    • metadata.title match;
    • metadata.tags match;
    • directory/path token match.
  5. Preserves original vector score as original_score or _original_score internally.
  6. Computes boost_score and final_score.
  7. Sorts by final_score descending.
  8. Returns only the requested top_k after rerank.

4.2 Feature flag

Use an environment variable in code:

SEARCH_RERANK_ENABLED

Default should be true in code. Do not edit docker-compose or .env in this first patch. If rollback by feature flag is needed later, that will be a separate approved config change.

4.3 Response schema caution

If current API response schema allows arbitrary dict fields, include debug fields:

_original_score
_boost
_boost_reasons

If response schema is strict, do not expose debug fields in the API response. Instead log/debug them during tests or keep them internal. Do not break API clients.

4.4 Suggested scoring

Use conservative boosts:

full_path_substring_match: +0.30
basename_token_overlap >= 0.50: +0.20
basename_token_overlap >= 0.30: +0.10
title_token_overlap >= 0.50: +0.15
title_token_overlap >= 0.30: +0.08
tag_hit: +0.05 each, max +0.15
directory_token_hit: +0.05 each, max +0.10

Use simple regex tokenization. No new Python dependencies.

4.5 Safer score handling

Internally use:

original_score = existing vector score
boost_score = computed boost
final_score = original_score + boost_score

If existing return field is named score, it is acceptable for final returned score to become final_score, but implementation report must explicitly state that score now means reranked score and original vector score is preserved in debug/internal evidence.

5. Post-patch validation before restart/deploy

After code patch:

cd /opt/incomex/docker/agent-data-repo
git diff -- agent_data/vector_store.py agent_data/server.py
git diff --stat
python3 -m py_compile agent_data/vector_store.py agent_data/server.py

If syntax fails, restore backup and report FAIL. Do not restart.

6. Restart / load patched code

Only restart Agent Data if preflight confirmed the runtime will use the patched code.

cd /opt/incomex/docker
# Use actual compose command/path confirmed by preflight.
docker compose restart agent-data
sleep 10
curl -s http://localhost:8000/health

If service does not become healthy, rollback immediately.

7. Post-implementation tests

7.1 Qdrant point count unchanged

docker exec "$QDRANT_CONTAINER" sh -lc "curl -s http://localhost:6333/collections/production_documents" | tee /tmp/p3d-qdrant-after-${TS}.json

points_count must equal preflight count.

7.2 Search tests

Run T1–T6 again through the same path used in baseline.

Acceptance:

AC-1 T1 expected target rank <= 2; rank 1 preferred.
AC-2 T2 expected target rank = 1.
AC-3 T3 target remains rank 1.
AC-4 T4 target remains rank 1.
AC-5 T5 semantic query still returns relevant vector/search audit docs in top 5.
AC-6 T6 semantic query still returns relevant operating-rules/SSOT docs in top 5.
AC-7 Qdrant point count unchanged.
AC-8 health status healthy.
AC-9 no material latency regression; record before/after timing if available.

7.3 Optional feature flag code-path test

If feasible without config mutation, run a local/unit invocation of the rerank function with SEARCH_RERANK_ENABLED=false in process env to confirm it bypasses rerank. Do not edit compose env.

8. Rollback

Rollback if:

  • health fails;
  • syntax fails;
  • T3/T4 regress;
  • T5/T6 broad semantic results become bad;
  • Qdrant point count changes;
  • runtime linkage behaves unexpectedly.

Rollback commands:

cd /opt/incomex/docker/agent-data-repo
cp "$BACKUP_DIR/vector_store.py.before" agent_data/vector_store.py
cp "$BACKUP_DIR/server.py.before" agent_data/server.py
cd /opt/incomex/docker
docker compose restart agent-data
sleep 10
curl -s http://localhost:8000/health

If repo was clean and only one file changed, git checkout -- <file> is also acceptable, but backup restore is preferred.

9. Required implementation report

Upload report to:

knowledge/dev/laws/dieu44-trien-khai/reports/p3d-vector-search-hybrid-path-title-boost-implementation-report.md

Report must include:

phase_status=PASS|FAIL|ROLLED_BACK|BLOCKED
mode=IMPLEMENTATION
root_cause=SEARCH_RANKING_NO_PATH_TITLE_BOOST_NOT_VECTOR_FRESHNESS
runtime_linkage_confirmed=true|false
files_changed=<list>
qdrant_points_before=<n>
qdrant_points_after=<n>
qdrant_mutation_performed=false
pg_schema_mutation_performed=false
db_write_performed=false
health_after=healthy|unhealthy|unknown
rollback_performed=true|false
no_reindex_performed=true

Also include:

baseline_ranks=<T1..T6 table>
after_ranks=<T1..T6 table>
acceptance_results=<AC-1..AC-9>
code_diff_summary=<short>
log_path=<path>
boost_logic_summary=<short>
warnings=<list>

10. Final response expected from Agent

Return only:

vector_search_boost_status=PASS|FAIL|ROLLED_BACK|BLOCKED
report_path=knowledge/dev/laws/dieu44-trien-khai/reports/p3d-vector-search-hybrid-path-title-boost-implementation-report.md
files_changed=<list>
qdrant_points_before=<n>
qdrant_points_after=<n>
health_after=<status>
acceptance_summary=<short>
rollback_performed=true|false
no_qdrant_mutation=true
no_pg_schema_mutation=true

11. Dispatch status

This prompt is ready for GPT/User review. Do not dispatch until approved by GPT/User.

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/prompts/p3d-vector-search-hybrid-path-title-boost-implementation-prompt.md