apsimo 1.3.0__py3-none-any.whl

apsimo/vector/multimodal_provider.py

@@ -0,0 +1,417 @@
+"""Colony Vector — multimodal embedding providers.
+
+CUDA, CPU, and API-based providers for text+image embedding.
+All providers produce vectors in the same embedding space for a given model,
+enabling cross-modal search (text query → image result, and vice versa).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from apsimo.vector.config import EmbeddingConfig
+from apsimo.vector.multimodal_types import EmbedInput, EmbedResult, ImageInput, Modality
+
+logger = logging.getLogger(__name__)
+
+
+class MultimodalEmbeddingProvider(ABC):
+    """Base class for multimodal embedding providers."""
+
+    def __init__(self, config: EmbeddingConfig) -> None:
+        self._config = config
+        self._model = None
+
+    @property
+    def model_id(self) -> str:
+        return self._config.model_id
+
+    @property
+    def dimensions(self) -> int:
+        return self._config.dimensions
+
+    @property
+    def modalities(self) -> list[str]:
+        return ["text", "image"]
+
+    @abstractmethod
+    async def embed_text(self, text: str) -> list[float]:
+        """Embed a single text string."""
+
+    @abstractmethod
+    async def embed_image(self, image: ImageInput) -> list[float]:
+        """Embed a single image."""
+
+    async def embed_batch_text(self, texts: list[str]) -> list[list[float]]:
+        """Embed multiple texts. Default: sequential call."""
+        return [await self.embed_text(t) for t in texts]
+
+    async def embed_batch_image(self, images: list[ImageInput]) -> list[list[float]]:
+        """Embed multiple images. Default: sequential with small batches."""
+        results = []
+        # Images are memory-heavy — process in small batches
+        batch_size = 4
+        for i in range(0, len(images), batch_size):
+            batch = images[i : i + batch_size]
+            for img in batch:
+                vec = await self.embed_image(img)
+                results.append(vec)
+        return results
+
+    async def embed_mixed(self, items: list[EmbedInput]) -> list[list[float]]:
+        """Embed a mix of text and image inputs."""
+        results: list[Optional[list[float]]] = [None] * len(items)
+
+        # Process texts and images in parallel batches
+        text_indices = [i for i, item in enumerate(items) if item.modality == Modality.TEXT]
+        image_indices = [i for i, item in enumerate(items) if item.modality == Modality.IMAGE]
+
+        if text_indices:
+            texts = [items[i].content for i in text_indices]
+            text_vecs = await self.embed_batch_text(texts)
+            for idx, vec in zip(text_indices, text_vecs):
+                results[idx] = vec
+
+        if image_indices:
+            # Load images from content (path, URL, or base64)
+            image_inputs = []
+            for i in image_indices:
+                img_input = await self._load_image_input(items[i])
+                image_inputs.append(img_input)
+            image_vecs = await self.embed_batch_image(image_inputs)
+            for idx, vec in zip(image_indices, image_vecs):
+                results[idx] = vec
+
+        return [r for r in results if r is not None]
+
+    async def _load_image_input(self, item: EmbedInput) -> ImageInput:
+        """Convert an EmbedInput with image modality to ImageInput."""
+        from apsimo.vector.image_preprocess import (
+            compute_image_hash,
+            extract_exif,
+            load_image,
+            resize_image,
+            validate_image,
+        )
+
+        data, mime = await load_image(item.content, item.mime_type)
+
+        # Validate
+        errors = validate_image(data)
+        if errors:
+            raise ValueError(f"Invalid image: {'; '.join(errors)}")
+
+        # Resize if needed
+        data, width, height = resize_image(data)
+
+        # Extract EXIF
+        exif = extract_exif(data)
+
+        # Compute hash
+        img_hash = compute_image_hash(data)
+
+        return ImageInput(
+            data=data,
+            mime_type=mime or "image/jpeg",
+            width=width,
+            height=height,
+            original_path=item.content if not item.content.startswith("data:") else "",
+            image_hash=img_hash,
+            exif=exif,
+        )
+
+    async def warmup(self) -> None:
+        """Load model weights. Default: embed a test string."""
+        try:
+            _ = await self.embed_text("colony multimodal warmup")
+            logger.info("Multimodal provider warmed up: %s", self.model_id)
+        except Exception as exc:
+            logger.warning("Multimodal warmup failed for %s: %s", self.model_id, exc)
+
+    async def close(self) -> None:
+        """Release model resources."""
+        self._model = None
+
+    async def health_check(self) -> dict[str, Any]:
+        """Verify provider is producing valid output for both modalities."""
+        import math
+
+        result: dict[str, Any] = {
+            "provider": self._config.provider,
+            "model": self.model_id,
+            "dims": self.dimensions,
+            "modalities": self.modalities,
+            "status": "error",
+        }
+
+        try:
+            # Text embedding check
+            t0 = time.monotonic()
+            text_vec = await self.embed_text("colony health check")
+            text_ms = (time.monotonic() - t0) * 1000
+
+            if len(text_vec) != self.dimensions:
+                result["error"] = f"text dimension mismatch: expected {self.dimensions}, got {len(text_vec)}"
+                return result
+            if any(math.isnan(v) or math.isinf(v) for v in text_vec):
+                result["error"] = "text vector contains NaN or Inf"
+                return result
+
+            result["text_latency_ms"] = round(text_ms, 1)
+
+            # Create a minimal test image (1x1 white JPEG)
+            test_image = _test_image_jpeg()
+            from apsimo.vector.image_preprocess import compute_image_hash
+            test_input = ImageInput(
+                data=test_image,
+                mime_type="image/jpeg",
+                image_hash=compute_image_hash(test_image),
+            )
+
+            t0 = time.monotonic()
+            img_vec = await self.embed_image(test_input)
+            img_ms = (time.monotonic() - t0) * 1000
+
+            if len(img_vec) != self.dimensions:
+                result["error"] = f"image dimension mismatch: expected {self.dimensions}, got {len(img_vec)}"
+                return result
+            if any(math.isnan(v) or math.isinf(v) for v in img_vec):
+                result["error"] = "image vector contains NaN or Inf"
+                return result
+
+            result["image_latency_ms"] = round(img_ms, 1)
+            result["status"] = "ok"
+
+        except Exception as exc:
+            result["error"] = str(exc)
+
+        return result
+
+
+def _test_image_jpeg() -> bytes:
+    """Generate a minimal 1x1 white JPEG for health checks."""
+    # Smallest valid JPEG
+    return bytes([
+        0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01,
+        0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0xFF, 0xDB, 0x00, 0x43,
+        0x00, 0x08, 0x06, 0x06, 0x07, 0x06, 0x05, 0x08, 0x07, 0x07, 0x07, 0x09,
+        0x09, 0x08, 0x0A, 0x0C, 0x14, 0x0D, 0x0C, 0x0B, 0x0B, 0x0C, 0x19, 0x12,
+        0x13, 0x0F, 0x14, 0x1D, 0x1A, 0x1F, 0x1E, 0x1D, 0x1A, 0x1C, 0x1C, 0x20,
+        0x24, 0x2E, 0x27, 0x20, 0x22, 0x2C, 0x23, 0x1C, 0x1C, 0x28, 0x37, 0x29,
+        0x2C, 0x30, 0x31, 0x34, 0x34, 0x34, 0x1F, 0x27, 0x39, 0x3D, 0x38, 0x32,
+        0x3C, 0x2E, 0x33, 0x34, 0x32, 0xFF, 0xC0, 0x00, 0x0B, 0x08, 0x00, 0x01,
+        0x00, 0x01, 0x01, 0x01, 0x11, 0x00, 0xFF, 0xC4, 0x00, 0x1F, 0x00, 0x00,
+        0x01, 0x05, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
+        0x09, 0x0A, 0x0B, 0xFF, 0xC4, 0x00, 0xB5, 0x10, 0x00, 0x02, 0x01, 0x03,
+        0x03, 0x02, 0x04, 0x03, 0x05, 0x05, 0x04, 0x04, 0x00, 0x00, 0x01, 0x7D,
+        0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06,
+        0x13, 0x51, 0x61, 0x07, 0x22, 0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08,
+        0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0, 0x24, 0x33, 0x62, 0x72,
+        0x82, 0x09, 0x0A, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28,
+        0x29, 0x2A, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45,
+        0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59,
+        0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75,
+        0x76, 0x77, 0x78, 0x79, 0x7A, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89,
+        0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3,
+        0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6,
+        0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9,
+        0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2,
+        0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4,
+        0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA, 0xFF, 0xDA, 0x00, 0x08, 0x01, 0x01,
+        0x00, 0x00, 0x3F, 0x00, 0x7B, 0x94, 0x11, 0x00, 0x00, 0x00, 0x00, 0xFF,
+        0xD9,
+    ])
+
+
+# ---------------------------------------------------------------------------
+# CUDA Provider
+# ---------------------------------------------------------------------------
+
+
+class CUDAMultimodalProvider(MultimodalEmbeddingProvider):
+    """Multimodal embedding on NVIDIA GPU via sentence-transformers or transformers."""
+
+    async def embed_text(self, text: str) -> list[float]:
+        return await asyncio.to_thread(self._sync_embed_text, text)
+
+    async def embed_image(self, image: ImageInput) -> list[float]:
+        return await asyncio.to_thread(self._sync_embed_image, image)
+
+    def _ensure_model(self):
+        if self._model is not None:
+            return
+        from sentence_transformers import SentenceTransformer
+        self._model = SentenceTransformer(self._config.model_id, device="cuda")
+
+    def _sync_embed_text(self, text: str) -> list[float]:
+        self._ensure_model()
+        vec = self._model.encode(text, normalize_embeddings=True)
+        return vec.tolist()
+
+    def _sync_embed_image(self, image: ImageInput) -> list[float]:
+        self._ensure_model()
+        from PIL import Image as PILImage
+        img = PILImage.open(io.BytesIO(image.data))
+        try:
+            vec = self._model.encode(img, normalize_embeddings=True)
+        except (TypeError, AttributeError):
+            # Some models don't accept PIL Image directly — try with image_processor
+            try:
+                from transformers import AutoProcessor
+                processor = AutoProcessor.from_pretrained(self._config.model_id)
+                inputs = processor(images=img, return_tensors="pt").to("cuda")
+                import torch
+                with torch.no_grad():
+                    outputs = self._model.get_text_features(**inputs) if hasattr(self._model, "get_text_features") else self._model(**inputs)
+                    if hasattr(outputs, "image_embeds"):
+                        vec = outputs.image_embeds[0].cpu().numpy()
+                    elif hasattr(outputs, "last_hidden_state"):
+                        vec = outputs.last_hidden_state[0].mean(dim=0).cpu().numpy()
+                    else:
+                        vec = outputs[0].cpu().numpy() if isinstance(outputs, (list, tuple)) else outputs.cpu().numpy()
+                import numpy as np
+                norm = np.linalg.norm(vec)
+                if norm > 0:
+                    vec = vec / norm
+                vec = vec.tolist()
+            except Exception as exc:
+                raise ValueError(f"Model {self._config.model_id} does not support image embedding: {exc}") from exc
+        return vec if isinstance(vec, list) else vec.tolist()
+
+
+# ---------------------------------------------------------------------------
+# CPU Provider
+# ---------------------------------------------------------------------------
+
+
+class CPUMultimodalProvider(MultimodalEmbeddingProvider):
+    """Multimodal embedding on CPU. Slow but works everywhere."""
+
+    async def embed_text(self, text: str) -> list[float]:
+        return await asyncio.to_thread(self._sync_embed_text, text)
+
+    async def embed_image(self, image: ImageInput) -> list[float]:
+        return await asyncio.to_thread(self._sync_embed_image, image)
+
+    def _ensure_model(self):
+        if self._model is not None:
+            return
+        from sentence_transformers import SentenceTransformer
+        self._model = SentenceTransformer(self._config.model_id, device="cpu")
+
+    def _sync_embed_text(self, text: str) -> list[float]:
+        self._ensure_model()
+        vec = self._model.encode(text, normalize_embeddings=True)
+        return vec.tolist()
+
+    def _sync_embed_image(self, image: ImageInput) -> list[float]:
+        self._ensure_model()
+        from PIL import Image as PILImage
+        img = PILImage.open(io.BytesIO(image.data))
+        try:
+            vec = self._model.encode(img, normalize_embeddings=True)
+        except (TypeError, AttributeError):
+            # Some models don't accept PIL Image directly
+            try:
+                from transformers import AutoProcessor
+                processor = AutoProcessor.from_pretrained(self._config.model_id)
+                inputs = processor(images=img, return_tensors="pt")
+                import torch
+                with torch.no_grad():
+                    outputs = self._model.get_text_features(**inputs) if hasattr(self._model, "get_text_features") else self._model(**inputs)
+                    if hasattr(outputs, "image_embeds"):
+                        vec = outputs.image_embeds[0].cpu().numpy()
+                    elif hasattr(outputs, "last_hidden_state"):
+                        vec = outputs.last_hidden_state[0].mean(dim=0).cpu().numpy()
+                    else:
+                        vec = outputs[0].cpu().numpy() if isinstance(outputs, (list, tuple)) else outputs.cpu().numpy()
+                import numpy as np
+                norm = np.linalg.norm(vec)
+                if norm > 0:
+                    vec = vec / norm
+                vec = vec.tolist()
+            except Exception as exc:
+                raise ValueError(f"Model {self._config.model_id} does not support image embedding: {exc}") from exc
+        return vec if isinstance(vec, list) else vec.tolist()
+
+
+# ---------------------------------------------------------------------------
+# API Provider (Jina, or any OpenAI-compatible endpoint with image support)
+# ---------------------------------------------------------------------------
+
+
+class APIMultimodalProvider(MultimodalEmbeddingProvider):
+    """Multimodal embedding via API (Jina, or OpenAI-compatible with image support).
+
+    Inherits API key from host configuration.
+    """
+
+    def __init__(self, config: EmbeddingConfig) -> None:
+        super().__init__(config)
+        if not config.base_url:
+            raise ValueError("Multimodal API embeddings require an explicit endpoint")
+        self._base_url = config.base_url.rstrip("/")
+        if not self._base_url.endswith("/v1"):
+            self._base_url += "/v1"
+        self._api_key = config.api_key or ""
+
+    async def embed_text(self, text: str) -> list[float]:
+        import httpx
+
+        async with httpx.AsyncClient(timeout=60, trust_env=False, follow_redirects=False) as client:
+            resp = await client.post(
+                f"{self._base_url}/embeddings",
+                headers={"Authorization": f"Bearer {self._api_key}"},
+                json={
+                    "model": self._config.model_id,
+                    "input": [{"text": text}],
+                },
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            return data["data"][0]["embedding"]
+
+    async def embed_image(self, image: ImageInput) -> list[float]:
+        import base64
+        import httpx
+
+        b64 = base64.b64encode(image.data).decode()
+
+        async with httpx.AsyncClient(timeout=60, trust_env=False, follow_redirects=False) as client:
+            resp = await client.post(
+                f"{self._base_url}/embeddings",
+                headers={"Authorization": f"Bearer {self._api_key}"},
+                json={
+                    "model": self._config.model_id,
+                    "input": [{"image": b64}],
+                },
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            return data["data"][0]["embedding"]
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+
+def make_multimodal_provider(config: EmbeddingConfig) -> MultimodalEmbeddingProvider:
+    """Create a multimodal embedding provider based on config."""
+    provider = config.provider.lower()
+
+    if provider == "cuda":
+        return CUDAMultimodalProvider(config)
+    elif provider == "cpu":
+        return CPUMultimodalProvider(config)
+    elif provider in ("openai_api", "api", "jina"):
+        return APIMultimodalProvider(config)
+    else:
+        logger.warning("Unknown multimodal provider '%s', falling back to CPU", provider)
+        return CPUMultimodalProvider(config)

apsimo/vector/multimodal_types.py

@@ -0,0 +1,87 @@
+"""Colony Vector — multimodal embedding types and input definitions.
+
+Modality-agnostic design: supports text, image, and future modalities
+(audio, video) without hardcoding assumptions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Union
+
+
+class Modality(str, Enum):
+    """Supported input modalities for embedding."""
+
+    TEXT = "text"
+    IMAGE = "image"
+    # Future: AUDIO = "audio", VIDEO = "video"
+
+
+@dataclass
+class EmbedInput:
+    """A single embedding input — text, image, or future modalities.
+
+    The `content` field interpretation depends on `modality`:
+    - text: raw text string
+    - image: file path, URL, or base64-encoded string
+    """
+
+    modality: Modality = Modality.TEXT
+    content: str = ""
+    mime_type: str = ""  # e.g. "image/jpeg", "image/png" — auto-detected if empty
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "modality": self.modality.value,
+            "content": self.content[:200] + "..." if len(self.content) > 200 else self.content,
+            "mime_type": self.mime_type,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class ImageInput:
+    """Normalized image input for the embedding pipeline.
+
+    Constructed by image_preprocess from raw inputs (path, URL, bytes, base64).
+    """
+
+    data: bytes  # Raw image bytes (JPEG or PNG)
+    mime_type: str = "image/jpeg"
+    width: int = 0
+    height: int = 0
+    original_path: str = ""  # Source path/URL for reference
+    image_hash: str = ""     # SHA-256 of raw bytes
+    exif: dict[str, Any] = field(default_factory=dict)  # Extracted EXIF data
+    caption: str = ""        # User-provided or auto-generated caption
+
+
+@dataclass
+class EmbedResult:
+    """Result of embedding a single input."""
+
+    vector: list[float]
+    modality: Modality
+    model_id: str
+    dims: int
+    image_hash: str = ""     # Set for image inputs
+    caption: str = ""        # Set for image inputs
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MultimodalSearchResult:
+    """Search result with modality awareness."""
+
+    id: str
+    score: float
+    text: str
+    modality: Modality = Modality.TEXT
+    image_ref: str = ""
+    image_hash: str = ""
+    caption: str = ""
+    thumbnail_ref: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)

apsimo/vector/openai_provider.py

@@ -0,0 +1,119 @@
+"""OpenAI-compatible API embedding provider.
+
+Calls an OpenAI-compatible ``/v1/embeddings`` endpoint using the
+host's API key.  This lets Colony inherit embeddings from whichever
+LLM provider the host is configured with — no separate API key needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import math
+from typing import Any
+
+from apsimo.vector.config import EmbeddingConfig
+from apsimo.vector.embedder import EmbeddingProvider
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAIAPIEmbeddingProvider(EmbeddingProvider):
+    """Embedding provider that calls an OpenAI-compatible API endpoint.
+
+    Uses ``httpx`` for async HTTP requests.  Inherits the API key and
+    base URL from the host configuration (same key used for LLM calls).
+    """
+
+    def __init__(self, config: EmbeddingConfig) -> None:
+        super().__init__(config)
+        self._base_url: str = ""
+        self._api_key: str = ""
+        self._served_model: str = ""
+
+    def configure(
+        self,
+        base_url: str,
+        api_key: str,
+    ) -> None:
+        """Set the API endpoint and key (called by the host plugin)."""
+        if self._served_model and (base_url.rstrip('/') != self._base_url or api_key != self._api_key):
+            raise ValueError('Create a new embedding provider before changing an active endpoint')
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+
+    @property
+    def dimensions(self) -> int:
+        return self._config.dimensions
+
+    async def warmup(self) -> None:
+        """Verify connectivity with a test embedding."""
+        if not self._base_url:
+            logger.warning("OpenAI API embedder not configured — set base_url")
+            return
+        result = await self.embed("warmup")
+        logger.info(
+            "OpenAI API embedder warmed up (dims=%d)", len(result),
+        )
+
+    async def embed(self, text: str) -> list[float]:
+        """Embed a single text via the API."""
+        results = await self.embed_batch([text])
+        return results[0]
+
+    async def close(self) -> None:
+        """No resources to release for API provider."""
+        pass
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of texts via the API."""
+        if not texts:
+            return []
+
+        import httpx
+
+        url = self._base_url + ('/embeddings' if self._base_url.endswith('/v1') else '/v1/embeddings')
+        headers = {
+            "Content-Type": "application/json",
+        }
+        if self._api_key:
+            headers['Authorization'] = f'Bearer {self._api_key}'
+        payload: dict[str, Any] = {
+            "model": self._config.model_id,
+            "input": texts,
+        }
+        # NOTE: do not send "dimensions" — non-matryoshka models (e.g.
+        # Qwen3-Embedding-8B, native 4096) reject it with HTTP 400 on vllm.
+
+        # Resilience (v0.21.1): the embedding endpoint is often remote (e.g. an
+        # SSH-tunnelled vLLM). Transient blips were silently failing memory writes
+        # AND recall (the agent then "loses" its memory). Retry with backoff.
+        last_exc: Exception | None = None
+        for attempt in range(3):
+            try:
+                async with httpx.AsyncClient(timeout=30, trust_env=False, follow_redirects=False) as client:
+                    response = await client.post(url, json=payload, headers=headers)
+                    response.raise_for_status()
+                    data = response.json()
+                rows = data.get('data', [])
+                if not isinstance(rows, list) or len(rows) != len(texts):
+                    raise ValueError('Embedding response count does not match its inputs')
+                if any('index' in row for row in rows):
+                    if sorted(row.get('index', -1) for row in rows) != list(range(len(texts))):
+                        raise ValueError('Embedding response indexes do not match its inputs')
+                    rows = sorted(rows, key=lambda row: row['index'])
+                vectors = [row['embedding'] for row in rows]
+                if any(len(vector) != self.dimensions or not all(math.isfinite(value) for value in vector)
+                       or not any(vector) for vector in vectors):
+                    raise ValueError('Embedding response contains an invalid vector or dimension')
+                served = str(data.get('model') or 'unknown')
+                if self._served_model and self._served_model != served:
+                    raise ValueError('Embedding endpoint changed its reported model; rebuild with a new provider snapshot')
+                self._served_model = served
+                return vectors
+            except (httpx.HTTPError, OSError) as exc:
+                last_exc = exc
+                if attempt < 2:
+                    await asyncio.sleep(0.5 * (attempt + 1))
+        logger.warning("Embedding failed after 3 attempts: %s", last_exc)
+        raise last_exc  # type: ignore[misc]

apsimo/vector/query.py

@@ -0,0 +1,49 @@
+"""Colony Vector Store — query and result types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class VectorResult:
+    """A single result from vector search."""
+
+    id: str
+    score: float  # cosine similarity in [0, 1]
+    text: str  # original embedded text
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VectorQuery:
+    """Parameters for a vector similarity search."""
+
+    vector: list[float]
+    limit: int = 10
+    filter: Optional[str] = None  # LanceDB SQL filter expression
+    min_score: float = 0.0
+
+
+@dataclass
+class VectorItem:
+    """An item to insert into the vector store."""
+
+    id: str
+    text: str
+    vector: list[float]
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HybridQuery:
+    """Combined dense + sparse (keyword) query — future use."""
+
+    vector: list[float]
+    text: str  # keyword query for BM25 sparse search
+    limit: int = 10
+    filter: Optional[str] = None
+    min_score: float = 0.0
+    dense_weight: float = 0.7
+    sparse_weight: float = 0.3