Media Domain Entities

Domain Entities

Overview

This module defines the core data structures used throughout the application: image/video file references, thumbnails, and ChromaDB record metadata.

Vault File

A single file in the vault/ directory. Can be an image or video.

Attribute	Type	Description
full_path	Path	Absolute filesystem path
rel_path	str	Path relative to the vault root (used as ChromaDB ID)
suffix	str	File extension (e.g., .jpg, .mp4)
mtime	float	Last modification timestamp
is_video	bool	Whether the file is a video format

ChromaDB Record

When indexed, each file becomes a record in the images collection.

Attribute	Type	Description
id	str	Relative path to the file (e.g., vault/IMG.jpg)
embedding	List[float]	2048-dim vector from Qwen3-VL model
full_path	str	Absolute path to the original file
thumbnail_path	str	Path to the generated .webp thumbnail
filename	str	Original filename
mtime	float	Modification time at index time
file_type	str	"image" or "video"

Thumbnail

Generated by the indexer for every media file.

Attribute	Type	Description
path	Path	Location in .cache/thumbnails/
filename	str	MD5 hash of relative path + .webp
size	str	300x300 pixels
format	str	WEBP with quality 80

Image Embedding

The vector representation generated by Qwen3VLEmbedder.

Attribute	Type	Description
last_hidden_state	torch.FloatTensor	Hidden states from the model
attention_mask	torch.Tensor	Mask for valid tokens in the sequence

Search Result

Returned by the API /search endpoint.

{
  "id": "vault/IMG.jpg",
  "score": 0.92,
  "metadata": {
    "full_path": "D:\\...\\vault\\IMG.jpg",
    "thumbnail_path": ".cache/thumbnails/abc.webp",
    "filename": "IMG.jpg",
    "mtime": 1747228800.0,
    "file_type": "image"
  }
}

Qwen3VLForEmbeddingOutput

Custom Pydantic dataclass extending ModelOutput.

@dataclass
class Qwen3VLForEmbeddingOutput(ModelOutput):
    last_hidden_state: Optional[torch.FloatTensor] = None
    attention_mask: Optional[torch.Tensor] = None

Related Components

• Image Indexing Pipeline – Creates ChromaDB records
• Qwen3VL Embeddings – Generates embedding vectors
• REST API Endpoints – Returns search result objects

---

Last Updated: 2026-06-17