Skip to main content
Module tools/asset_index/ là core của repo. Nó theo dõi raw_assets/, phân tích file mới bằng Gemini, embed mô tả qua OpenAI, và lưu vào SQLite + sqlite-vec để mọi skill query bằng ngôn ngữ tự nhiên.

​
Sơ đồ

Mục đích sơ đồ: cho bạn thấy đường đi đầy đủ của một file media khi được đưa vào raw_assets/, từ watcher phát hiện file đến khi asset có thể được tìm bằng semantic search. 
                    ┌────────────────────────────────────┐
                    │  raw_assets/                       │
                    │  ├── images/                       │
                    │  ├── videos/                       │
                    │  └── audio/                        │
                    └─────────────┬──────────────────────┘
                                  │ FSEvents (macOS) / ReadDirectoryChangesW (Windows)
                                  │ inotify (Linux) / Polling (fallback)
                                  ▼
                    ┌────────────────────────────────────┐
                    │  watcher.py                        │
                    │  - debounce 1.5s (mac) / 2.5s (win)│
                    │  - size-stable check               │
                    │  - single-instance lock            │
                    └─────────────┬──────────────────────┘
                                  │ process_file(path)
                                  ▼
                    ┌────────────────────────────────────┐
                    │  router.py                         │
                    │  - SHA-256 hash                    │
                    │  - skip if (hash, mtime) đã có     │
                    │  - classify ext → media_type       │
                    └─────────────┬──────────────────────┘
                                  │
                  ┌───────────────┼─────────────────┐
                  ▼               ▼                 ▼
        ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
        │ image_gemini │ │ video_gemini │ │ audio_gemini │
        │ Vision API   │ │ Probe + LLM  │ │ Whisper +    │
        │              │ │              │ │ classify     │
        └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
               └────────────────┼────────────────┘
                                ▼
                    ┌────────────────────────────────────┐
                    │  embed.py                          │
                    │  OpenAI text-embedding-3-small     │
                    │  → 1536-dim vector                 │
                    └─────────────┬──────────────────────┘
                                  ▼
                    ┌────────────────────────────────────┐
                    │  store.py → .asset_index/index.db  │
                    │  - assets (metadata + summary)     │
                    │  - assets_vec (sqlite-vec, 1536)   │
                    │  - process_log (audit trail)       │
                    └─────────────┬──────────────────────┘
                                  ▼
                    ┌────────────────────────────────────┐
                    │  search.py                         │
                    │  query → embed → vec0 nearest      │
                    │  → join assets → top-K             │
                    └────────────────────────────────────┘
Mô tả sơ đồ: Luồng bắt đầu khi watcher phát hiện file mới trong raw_assets/ bằng cơ chế theo OS hoặc polling fallback. router.py hash file, bỏ qua bản đã index, rồi chọn analyzer phù hợp cho ảnh, video hoặc audio. Kết quả mô tả được embed thành vector 1536 chiều, lưu cùng metadata vào .asset_index/index.db, và search.py dùng cùng embed model để tìm asset gần nghĩa nhất cho truy vấn hoặc scene intent.

​
Các module chính

FileVai trò
watcher.pyTheo dõi filesystem, debounce, dispatch path → router
router.pyHash, skip nếu trùng, gọi analyzer phù hợp, embed, upsert
analyzers/image_gemini.pySingle-frame Gemini Vision cho ảnh
analyzers/video_gemini.pyProbe ffprobe + Gemini multimodal cho video
analyzers/audio_gemini.pyWhisper transcript + Gemini classify cho audio
embed.pyOpenAI text-embedding-3-small (1536 chiều)
store.pySQLite + sqlite-vec virtual table CRUD
search.pyQuery → embedding → vec0 nearest → join assets
service.pyĐăng ký watcher dưới launchd / Task Scheduler / systemd
bootstrap.pySetup wizard cho auto installer
hashing.pySHA-256 streaming cho file lớn
gemini_client.pyGemini API wrapper với retry + rate-limit

​
Schema DB

3 bảng (xem schema.sql):
  • assets — metadata + summary do Gemini sinh.
  • assets_vec — virtual table sqlite-vec, embedding 1536 chiều, FTS K-NN.
  • process_log — audit trail mỗi lần process (status, error, ran_at).

​
Bước tiếp theo

CLI dev

Chạy module trực tiếp khi dev/debug.

File runtime

.asset_index/index.db, state.json, logs/.

Idempotency

Vì sao re-index file không tốn LLM call.

Mở rộng

Thêm format, đổi embed model.