feat: Phase 2-3 TKG-only architecture

Phase 2.1: build_face_trace_nodes_from_qdrant()
- Read trace_id, frame, bbox directly from Qdrant payload
- No dependency on face_detections table

Phase 2.3: Rule2 queries TKG nodes
- identity resolution from tkg_nodes.properties.identity_id
- TKG-only architecture (Phase 2.3)

Phase 3: Identity Agent updates TKG nodes
- match_faces_iterative() updates tkg_nodes.properties
- bind_identity_trace() syncs identity_id to TKG
- unbind_identity() removes identity_id from TKG

Test results:
- 23 face_trace nodes from Qdrant (Phase 2.1)
- 75 relationship chunks (Rule2)
- TKG rebuild: Phase0 → Phase1 → Phase2
This commit is contained in:
Accusys
2026-06-21 01:30:04 +08:00
parent 2f2ccc94f7
commit 23c440104b
5 changed files with 305 additions and 23 deletions

View File

@@ -0,0 +1,69 @@
---
title: TKG Phase 2-3 Progress Report
version: 1.0
date: 2026-06-21
author: OpenCode
status: In Progress
---
## Goal
- Complete TKG-only architecture migration: Phase 0-4 for Rule 2 relationship chunks and Identity Agent Qdrant integration
## Constraints & Preferences
- Rule 2 chunk_type: `"relationship"` (not `"visual"`)
- Rule 2 edge types match TKG storage: `SPEAKS_AS`, `MUTUAL_GAZE`, `CO_OCCURS_WITH`, `HAS_APPEARANCE`, `WEARS`
- Rule 2 each edge = one chunk (not aggregated)
- Qdrant face embeddings: dim=512, Cosine distance, collection `{schema}_face_embeddings`
- Phase approach: Phase 0 (populate), Phase 1 (Qdrant), Phase 2 (TKG-only), Phase 3 (Identity), Phase 4 (deprecate)
## Progress
### Done
- **Phase 0**: TKG builder populate face_detections from face.json via `store_traced_faces.py`
- **Phase 1.1**: Create `dev_face_embeddings` Qdrant collection (dim=512)
- **Phase 1.2**: `FaceEmbeddingDb` module with `init_collection`, `batch_upsert`, `search_similar`, `get_all_embeddings_for_file`
- **Phase 1.3**: TKG builder stores 1122 embeddings to Qdrant with pose metadata
- **Phase 1.4**: Identity Agent `match_faces_iterative()` queries Qdrant (fallback to PG)
- **Phase 2.1**: `build_face_trace_nodes_from_qdrant()` reads Qdrant payload (no face_detections dependency)
- **Phase 2.3**: Rule2 queries `tkg_nodes.properties.identity_id` (TKG-only)
- **Phase 3**: Identity Agent (Qdrant + PG) updates `tkg_nodes.properties` when binding
- **Rule 2**: 75 relationship chunks created + vectorized (tested)
- **Rule 2 API**: `POST /api/v1/file/:file_uuid/rule2` with auto-vectorize, triggers on TKG rebuild
- **Identity binding**: `bind_identity_trace()` and `unbind_identity()` update TKG nodes (Phase 2.3)
- **TKG builder**: `populate_face_detections_from_face_json()` and `populate_face_embeddings_to_qdrant()`
### Pending
- **Phase 4**: Deprecate face_detections table (await all Phase 2-3 verified in production)
## Key Decisions
- TKG builder fixed for `pose_angle` format (was expecting `pose` with `bbox` sub-object)
- Edge types corrected: TKG stores `CO_OCCURS_WITH` (not `co_occurs`), `SPEAKS_AS` (not `speaker_face`)
- Qdrant point IDs must be numeric or UUID (not string like `"file_uuid-frame"`)
- Identity Agent dual-source: Qdrant first, PostgreSQL fallback
- Phase 0 checks `trace_id IS NOT NULL` before calling `store_traced_faces.py`
- Phase 2.1: Qdrant payload contains `trace_id`, `frame`, `bbox_x/y/w/h`, `pose`, no PG query needed
- Phase 2.3: TKG nodes store `identity_id` and `identity_name` in properties JSON
- Phase 3: Identity Agent updates both `face_detections.identity_id` AND `tkg_nodes.properties`
## Test Results
- 1122 face embeddings in Qdrant (`dev_face_embeddings` collection)
- 75 relationship chunks from Rule2
- 23 face_trace_nodes built from Qdrant (Phase 2.1)
- Rule2 still works after TKG-only migration (Phase 2.3)
## Next Steps
- Phase 4: Verify all systems work without face_detections dependency
- Phase 4: Document face_detections deprecation plan
## Commits
- `2f2ccc94` (Phase 1.4)
- `3ad6f874` (Rule2 + Phase 0-1)
- (pending) Phase 2-3 changes
## Relevant Files
- `src/core/db/face_embedding_db.rs`: **New** — FaceEmbeddingDb, FaceEmbeddingPayload, FaceEmbeddingPoint
- `src/core/db/mod.rs`: updated — `pub mod face_embedding_db; pub use FaceEmbeddingDb;`
- `src/core/processor/tkg.rs`: updated — Phase 2.1 `build_face_trace_nodes_from_qdrant()`
- `src/core/chunk/rule2_ingest.rs`: updated — Phase 2.3 TKG-only identity query
- `src/api/identity_binding.rs`: updated — Phase 2.3 TKG node update on bind/unbind
- `src/api/identity_agent_api.rs`: updated — Phase 3 TKG node update on match
- `docs_v1.0/DESIGN/RULE2_TKG_RELATIONSHIP_V1.0.md`: Rule 2 design spec