feat: support auto embedding for image

[Mini256]

close #33

In this PR, we will support auto embedding for image with managed-embedding service (e.g. jina_ai/jina-embeddings-v4)

TODO:

• Support custom embedding model #138
• Support auto upload binary image #139

We can create a image_uri to store the url or filepath of the image, and add an vector field like image_vec via VectorField class.

Different to the auto embeeding for text, you need to specify the type of the source field as image via the parameter source_type="image".

class Pet(TableModel):
        __tablename__ = "pets"
        id: int = Field(primary_key=True)
        image_uri: Optional[str] = Field(default=None)
        image_vec: Optional[list[float]] = image_embed_fn.VectorField(
            distance_metric=DistanceMetric.COSINE,
            source_field="image_uri",
            source_type="image",  # 👈 Configure the source field as image.
        )

After inserted, we can using the table.search() API to perform vector search on image data.

Example: Search images with keywords

results = (
    pet_table.search(query="shiba inu dog").limit(1).to_list()
)

Example: Search images with Path object

pet_images_dir = Path("./tests/fixtures/pet_images")
query_image_path = pet_images_dir / "shiba_inu_15.jpg"
results = (
    pet_table.search(query=query_image_path).limit(1).to_list()
)

Example: Search images with PIL Image object

from PIL import Image

pet_images_dir = Path("./tests/fixtures/pet_images")
query_image = Image.open(pet_images_dir / "shiba_inu_15.jpg")
results = (
    pet_table.search(query=query_image).limit(1).to_list()
)

[Icemap]

LGTM

[cursor]

Bug: API Call in Constructor Causes Instantiation Failures

The BuiltInEmbeddingFunction constructor attempts to auto-detect embedding dimensions by calling self.get_query_embedding("test", "text") when dimensions is None. This external API call during initialization makes object instantiation unreliable, as it can fail due to network issues, invalid API credentials, or service unavailability. Additionally, the call itself is incorrect, passing "text" as a positional argument instead of a keyword argument for source_type, which results in a TypeError at runtime.

pytidb/embeddings/builtin.py#L90-L92

pytidb/pytidb/embeddings/builtin.py

Lines 90 to 92 in 3af724f

	)
	if dimensions is None:
	self.dimensions = len(self.get_query_embedding("test", "text"))

Fix in Cursor • Fix in Web

---

Bug: API Change Breaks Existing Code

The QueryBundle TypedDict field name was changed from query_text to query. This breaking API change causes existing code to fail silently, as SearchQuery.__init__ now expects the query field, resulting in None queries and unexpected search behavior. Existing code must be updated to use query instead of query_text.

pytidb/schema.py#L21-L25

pytidb/pytidb/schema.py

Lines 21 to 25 in 3af724f

	class QueryBundle(TypedDict):
	query: Optional[Any]
	query_vector: Optional[VectorDataType]

Fix in Cursor • Fix in Web

---

Was this report helpful? Give feedback by reacting with 👍 or 👎