Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

4.0 KB
Raw Blame
"""Embedding helper.

Centralizes the choice of embedding provider+model and the dimension
adjustment (since pgvector columns are fixed-dimension and we lock to
`AGENTS_EMBEDDING_DIM`).

Providers:
  - `native`: in-process via fastembed (default). Multilingual MiniLM
    by default. Lazy-imports fastembed on first use so users not on the
    agents feature pay zero memory/import cost.
  - `ollama`: external Ollama embedding model.
  - `openai`: OpenAI's text-embedding-* endpoints.
  - `openai_compatible`: any OpenAI-shaped /v1/embeddings endpoint.
"""
from __future__ import annotations

import asyncio
import functools
import logging
from typing import Any, Optional

from app.agents.config import get_agent_settings
from app.agents.providers.base import LLMNotSupportedError
from app.agents.providers.registry import build_provider

logger = logging.getLogger(__name__)


def _adjust_dim(vec: list[float], target: int) -> list[float]:
    """Pad with zeros or truncate to match the column dimension."""
    if len(vec) == target:
        return list(vec)
    if len(vec) > target:
        return list(vec[:target])
    out = list(vec)
    out.extend([0.0] * (target - len(vec)))
    return out


@functools.lru_cache(maxsize=4)
def _get_native_embedder(model_name: str, cache_dir: str) -> Any:
    """Lazy-import fastembed and instantiate the model exactly once per
    (model, cache_dir). The first call downloads the ONNX model to
    `cache_dir` (~120 MB for the default multilingual MiniLM); subsequent
    calls hit the in-memory instance.

    Importing fastembed is intentionally inside this function — modules
    using `app.agents.services.embedding` don't drag fastembed in unless
    they actually trigger embedding (i.e. only the agents feature does).
    """
    from fastembed import TextEmbedding  # heavy: onnxruntime + numpy

    logger.info("loading native embedder %s (cache=%s)", model_name, cache_dir)
    return TextEmbedding(model_name=model_name, cache_dir=cache_dir)


def _embed_native_sync(texts: list[str], model_name: str, cache_dir: str) -> list[list[float]]:
    """Synchronous embed call. Runs in a thread via run_in_executor so
    we don't block the event loop on what's effectively CPU + I/O work."""
    emb = _get_native_embedder(model_name, cache_dir)
    return [list(map(float, v)) for v in emb.embed(texts)]


async def _embed_native(texts: list[str]) -> tuple[list[list[float]], str]:
    s = get_agent_settings()
    loop = asyncio.get_running_loop()
    vectors = await loop.run_in_executor(
        None, _embed_native_sync, texts, s.embedding_model, s.embedding_native_cache_dir
    )
    return vectors, f"native:{s.embedding_model}"


def _build_remote_provider():
    s = get_agent_settings()
    name = s.embedding_provider
    if name == "ollama":
        return build_provider("ollama", base_url=s.embedding_ollama_base_url)
    if name == "openai":
        return build_provider("openai", api_key=s.embedding_openai_api_key, base_url=s.embedding_openai_base_url)
    if name == "openai_compatible":
        return build_provider("openai_compatible", api_key=s.embedding_openai_api_key, base_url=s.embedding_openai_base_url)
    raise LLMNotSupportedError(f"embedding provider '{name}' has no embedding endpoint")


async def embed_texts(texts: list[str]) -> tuple[list[list[float]], str]:
    """Returns (vectors, model_label). Vectors are dimension-adjusted to
    `AGENTS_EMBEDDING_DIM`."""
    if not texts:
        return [], get_agent_settings().embedding_model
    s = get_agent_settings()
    target = s.embedding_dim
    if s.embedding_provider == "native":
        raw, label = await _embed_native(texts)
    else:
        provider = _build_remote_provider()
        raw = await provider.embed(texts, model=s.embedding_model)
        label = f"{s.embedding_provider}:{s.embedding_model}"
    return ([_adjust_dim(v, target) for v in raw], label)


async def embed_one(text: str) -> Optional[list[float]]:
    vecs, _ = await embed_texts([text])
    return vecs[0] if vecs else None