curu-memory 0.2.0__py3-none-any.whl

curu_memory/config.py

@@ -0,0 +1,308 @@
+"""The settings of curu-memory, read from the environment (contracts/cli.md)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from curu_memory.ports import (
+    DEFAULT_MIN_SIMILARITY,
+    Prompts,
+    min_audio_similarity_for,
+    min_audio_to_audio_similarity_for,
+    min_audio_to_text_similarity_for,
+    min_image_similarity_for,
+    min_image_to_image_similarity_for,
+    min_image_to_text_similarity_for,
+    min_similarity_for,
+    min_video_similarity_for,
+    min_video_to_text_similarity_for,
+    min_video_to_video_similarity_for,
+    parse_space,
+    prompts_for,
+)
+
+DEFAULT_EMBEDDER_TIMEOUT = 5.0
+#: The embedding model when CURU_MEMORY_EMBEDDER_URL is set with no model (ADR-003).
+DEFAULT_EMBEDDER_MODEL = "google/embeddinggemma-2"
+PREFIX = "CURU_MEMORY_"
+
+
+class ConfigError(ValueError):
+    """A setting is wrong. The message names the variable and the fix."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    data_dir: Path
+    concepts_dir: Path | None = None
+    embedder_url: str | None = None
+    embedder_model: str | None = None
+    embedder_timeout: float = DEFAULT_EMBEDDER_TIMEOUT
+    query_prompt: str | None = None
+    document_prompt: str | None = None
+    min_similarity_override: float | None = None
+    min_image_similarity_override: float | None = None
+    min_image_to_image_similarity_override: float | None = None
+    min_audio_similarity_override: float | None = None
+    min_video_similarity_override: float | None = None
+    min_video_to_video_similarity_override: float | None = None
+    min_video_to_text_similarity_override: float | None = None
+    min_audio_to_audio_similarity_override: float | None = None
+    min_audio_to_text_similarity_override: float | None = None
+    min_image_to_text_similarity_override: float | None = None
+    #: The handle of the person of serve, browse and search (ADR-016). None reads global only.
+    principal: str | None = None
+    #: The OIDC issuer of the HTTP transport. It turns on the OIDC mode (ADR-015).
+    oidc_issuer: str | None = None
+    #: The canonical URI of the server. None means the address of serve.
+    oidc_resource: str | None = None
+    #: The value that `aud` must hold. None means the resource (ADR-017).
+    oidc_audience: str | None = None
+    oidc_token_types: tuple[str, ...] = ("at+jwt",)
+    #: The client identifier of the Basic exchange. None turns the exchange off (ADR-018).
+    oidc_basic_client_id: str | None = None
+    # The tokens are secrets, so they never go into the repr (constitution, article IV).
+    embedder_token: str | None = field(default=None, repr=False)
+    http_token: str | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Settings:
+        env = os.environ if env is None else env
+
+        def get(name: str) -> str | None:
+            value = env.get(PREFIX + name, "").strip()
+            return value or None
+
+        url = get("EMBEDDER_URL")
+        model = get("EMBEDDER_MODEL")
+        if model and not url:
+            raise ConfigError(
+                "CURU_MEMORY_EMBEDDER_MODEL needs CURU_MEMORY_EMBEDDER_URL, "
+                "the base URL of an OpenAI-compatible embedder."
+            )
+
+        concepts = get("CONCEPTS_DIR")
+        data = get("DATA_DIR")
+        return cls(
+            data_dir=Path(data) if data else _default_data_dir(env),
+            concepts_dir=Path(concepts) if concepts else None,
+            embedder_url=url.rstrip("/") if url else None,
+            embedder_model=model or (DEFAULT_EMBEDDER_MODEL if url else None),
+            embedder_timeout=_timeout(get("EMBEDDER_TIMEOUT")),
+            query_prompt=_prompt("EMBEDDER_QUERY_PROMPT", get("EMBEDDER_QUERY_PROMPT")),
+            document_prompt=_prompt("EMBEDDER_DOCUMENT_PROMPT", get("EMBEDDER_DOCUMENT_PROMPT")),
+            min_similarity_override=_similarity(
+                "EMBEDDER_MIN_SIMILARITY", get("EMBEDDER_MIN_SIMILARITY")
+            ),
+            min_image_similarity_override=_similarity(
+                "EMBEDDER_MIN_IMAGE_SIMILARITY", get("EMBEDDER_MIN_IMAGE_SIMILARITY")
+            ),
+            min_audio_similarity_override=_similarity(
+                "EMBEDDER_MIN_AUDIO_SIMILARITY", get("EMBEDDER_MIN_AUDIO_SIMILARITY")
+            ),
+            min_video_similarity_override=_similarity(
+                "EMBEDDER_MIN_VIDEO_SIMILARITY", get("EMBEDDER_MIN_VIDEO_SIMILARITY")
+            ),
+            min_video_to_video_similarity_override=_similarity(
+                "EMBEDDER_MIN_VIDEO_TO_VIDEO_SIMILARITY",
+                get("EMBEDDER_MIN_VIDEO_TO_VIDEO_SIMILARITY"),
+            ),
+            min_video_to_text_similarity_override=_similarity(
+                "EMBEDDER_MIN_VIDEO_TO_TEXT_SIMILARITY",
+                get("EMBEDDER_MIN_VIDEO_TO_TEXT_SIMILARITY"),
+            ),
+            min_audio_to_audio_similarity_override=_similarity(
+                "EMBEDDER_MIN_AUDIO_TO_AUDIO_SIMILARITY",
+                get("EMBEDDER_MIN_AUDIO_TO_AUDIO_SIMILARITY"),
+            ),
+            min_audio_to_text_similarity_override=_similarity(
+                "EMBEDDER_MIN_AUDIO_TO_TEXT_SIMILARITY",
+                get("EMBEDDER_MIN_AUDIO_TO_TEXT_SIMILARITY"),
+            ),
+            min_image_to_image_similarity_override=_similarity(
+                "EMBEDDER_MIN_IMAGE_TO_IMAGE_SIMILARITY",
+                get("EMBEDDER_MIN_IMAGE_TO_IMAGE_SIMILARITY"),
+            ),
+            min_image_to_text_similarity_override=_similarity(
+                "EMBEDDER_MIN_IMAGE_TO_TEXT_SIMILARITY",
+                get("EMBEDDER_MIN_IMAGE_TO_TEXT_SIMILARITY"),
+            ),
+            principal=_handle("PRINCIPAL", get("PRINCIPAL")),
+            oidc_issuer=_url("OIDC_ISSUER", get("OIDC_ISSUER"), issuer=True),
+            oidc_resource=_url("OIDC_RESOURCE", get("OIDC_RESOURCE"), issuer=False),
+            oidc_audience=get("OIDC_AUDIENCE"),
+            oidc_token_types=_token_types(get("OIDC_TOKEN_TYPES")),
+            oidc_basic_client_id=get("OIDC_BASIC_CLIENT_ID"),
+            embedder_token=get("EMBEDDER_TOKEN"),
+            http_token=get("HTTP_TOKEN"),
+        )
+
+    def prompts(self) -> Prompts:
+        """The task prompts of the embedder: the overrides, or the defaults of the model."""
+        defaults = prompts_for(self.embedder_model) if self.embedder_model else Prompts()
+        return Prompts(
+            query=self.query_prompt or defaults.query,
+            document=self.document_prompt or defaults.document,
+        )
+
+    def min_similarity(self) -> float:
+        """The similarity limit: the override, or the default of the model (ADR-005)."""
+        if self.min_similarity_override is not None:
+            return self.min_similarity_override
+        if self.embedder_model is None:
+            return DEFAULT_MIN_SIMILARITY
+        return min_similarity_for(self.embedder_model)
+
+    def min_image_similarity(self) -> float:
+        """The similarity limit of an image unit: the override, or the default of the model."""
+        if self.min_image_similarity_override is not None:
+            return self.min_image_similarity_override
+        if self.embedder_model is None:
+            return DEFAULT_MIN_SIMILARITY
+        return min_image_similarity_for(self.embedder_model)
+
+    def min_audio_similarity(self) -> float:
+        """The limit when a question in words meets an audio unit (ADR-011)."""
+        return self._limit(self.min_audio_similarity_override, min_audio_similarity_for)
+
+    def min_video_similarity(self) -> float:
+        """The limit when a question in words meets a video unit (ADR-013)."""
+        return self._limit(self.min_video_similarity_override, min_video_similarity_for)
+
+    def min_video_to_video_similarity(self) -> float:
+        """The limit when a video question meets a video unit (ADR-014)."""
+        return self._limit(
+            self.min_video_to_video_similarity_override, min_video_to_video_similarity_for
+        )
+
+    def min_video_to_text_similarity(self) -> float:
+        """The limit when a video question meets a text unit (ADR-014)."""
+        return self._limit(
+            self.min_video_to_text_similarity_override, min_video_to_text_similarity_for
+        )
+
+    def min_audio_to_audio_similarity(self) -> float:
+        """The limit when a clip question meets an audio unit (ADR-012)."""
+        return self._limit(
+            self.min_audio_to_audio_similarity_override, min_audio_to_audio_similarity_for
+        )
+
+    def min_audio_to_text_similarity(self) -> float:
+        """The limit when a clip question meets a text unit (ADR-012)."""
+        return self._limit(
+            self.min_audio_to_text_similarity_override, min_audio_to_text_similarity_for
+        )
+
+    def min_image_to_image_similarity(self) -> float:
+        """The limit when an image question meets an image unit (ADR-010)."""
+        return self._limit(
+            self.min_image_to_image_similarity_override, min_image_to_image_similarity_for
+        )
+
+    def min_image_to_text_similarity(self) -> float:
+        """The limit when an image question meets a text unit (ADR-010)."""
+        return self._limit(
+            self.min_image_to_text_similarity_override, min_image_to_text_similarity_for
+        )
+
+    def _limit(self, override: float | None, default_for: Callable[[str], float]) -> float:
+        if override is not None:
+            return override
+        if self.embedder_model is None:
+            return DEFAULT_MIN_SIMILARITY
+        return default_for(self.embedder_model)
+
+    def index_path(self, tier_space: str) -> Path:
+        """The index file of one tier space (ADR-001)."""
+        return self.data_dir / f"{tier_space}.sqlite"
+
+
+_LOOPBACK = frozenset({"127.0.0.1", "localhost", "::1"})
+
+
+def _url(name: str, value: str | None, *, issuer: bool) -> str | None:
+    """An absolute URL with no fragment. An issuer on the network must use HTTPS (R-5)."""
+    if value is None:
+        return None
+    parts = urlsplit(value)
+    if parts.scheme not in ("http", "https") or not parts.hostname or parts.fragment:
+        raise ConfigError(
+            f"{PREFIX}{name} must be an absolute http or https URL with no fragment. "
+            f"It is {value!r}."
+        )
+    if issuer and parts.scheme == "http" and parts.hostname not in _LOOPBACK:
+        raise ConfigError(
+            f"{PREFIX}{name} must use https. Plain http is only for an issuer on "
+            f"127.0.0.1, ::1 or localhost. It is {value!r}."
+        )
+    return value
+
+
+def _token_types(value: str | None) -> tuple[str, ...]:
+    if value is None:
+        return ("at+jwt",)
+    types = tuple(part.strip() for part in value.split(",") if part.strip())
+    if not types:
+        raise ConfigError(
+            f"{PREFIX}OIDC_TOKEN_TYPES must list one or more token types, for example at+jwt,JWT."
+        )
+    return types
+
+
+def _handle(name: str, value: str | None) -> str | None:
+    """A handle: 1 to 40 characters from a to z, 0 to 9 and -, first a letter (ADR-016)."""
+    if value is None:
+        return None
+    try:
+        parse_space(f"personal/{value}")
+    except ValueError:
+        raise ConfigError(
+            f"{PREFIX}{name} must be the handle of a registered person: 1 to 40 characters "
+            f"from a to z, 0 to 9 and -, first a letter. It is {value!r}."
+        ) from None
+    return value
+
+
+def _default_data_dir(env: Mapping[str, str]) -> Path:
+    xdg = env.get("XDG_DATA_HOME", "").strip()
+    if xdg:
+        return Path(xdg) / "curu-memory"
+    home = env.get("HOME", "").strip()
+    base = Path(home) if home else Path.home()
+    return base / ".local" / "share" / "curu-memory"
+
+
+def _prompt(name: str, value: str | None) -> str | None:
+    if value is not None and "{text}" not in value:
+        raise ConfigError(f"{PREFIX}{name} must contain {{text}}, the place of the text.")
+    return value
+
+
+def _similarity(name: str, value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        limit = float(value)
+    except ValueError:
+        limit = 2.0
+    if not -1.0 <= limit <= 1.0:
+        raise ConfigError(f"{PREFIX}{name} must be a number from -1 to 1, not {value!r}.")
+    return limit
+
+
+def _timeout(value: str | None) -> float:
+    if value is None:
+        return DEFAULT_EMBEDDER_TIMEOUT
+    try:
+        seconds = float(value)
+    except ValueError:
+        seconds = 0.0
+    if seconds <= 0:
+        raise ConfigError(
+            f"CURU_MEMORY_EMBEDDER_TIMEOUT must be a number of seconds above 0, not {value!r}."
+        )
+    return seconds

curu_memory/embedders.py

@@ -0,0 +1,118 @@
+"""Adapters of the `Embedder` port. None of them loads model weights (ADR-001)."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import struct
+from collections.abc import Sequence
+
+import httpx2
+
+from curu_memory.media import MediaFile
+
+
+class FakeEmbedder:
+    """A deterministic vector from the SHA-256 of the text. It has no meaning.
+
+    The default test tier uses it, so that the tests need no model (constitution,
+    article VI). It proves the plumbing of the match of meaning, not its quality.
+    """
+
+    def __init__(self, dimension: int = 64) -> None:
+        self._dimension = dimension
+
+    @property
+    def model(self) -> str:
+        return f"fake-sha256-{self._dimension}"
+
+    @property
+    def dimension(self) -> int:
+        return self._dimension
+
+    def embed(self, texts: Sequence[str]) -> list[list[float]]:
+        return [self._vector(text) for text in texts]
+
+    def embed_media(self, files: Sequence[MediaFile]) -> list[list[float]]:
+        return [self._vector(f"{media.kind}:{media.sha256}") for media in files]
+
+    def _vector(self, text: str) -> list[float]:
+        values: list[float] = []
+        counter = 0
+        while len(values) < self._dimension:
+            digest = hashlib.sha256(f"{counter}:{text}".encode()).digest()
+            for (number,) in struct.iter_unpack(">I", digest):
+                values.append(number / 2**32 - 0.5)
+            counter += 1
+        values = values[: self._dimension]
+        norm = math.sqrt(sum(v * v for v in values)) or 1.0
+        return [v / norm for v in values]
+
+
+class OpenAICompatibleEmbedder:
+    """Calls `POST /v1/embeddings` of llama-server, Ollama, vLLM or another server.
+
+    The server holds the model. curu-memory sends only the texts and the model name.
+    The token never goes into a log or the repr (constitution, article IV).
+    """
+
+    def __init__(
+        self, base_url: str, model: str, *, token: str | None = None, timeout: float = 5.0
+    ) -> None:
+        base = base_url.rstrip("/")
+        self._url = f"{base}/embeddings" if base.endswith("/v1") else f"{base}/v1/embeddings"
+        self._model = model
+        self._token = token
+        self._timeout = timeout
+        self._dimension: int | None = None
+
+    def __repr__(self) -> str:
+        return f"OpenAICompatibleEmbedder(url={self._url!r}, model={self._model!r})"
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    @property
+    def dimension(self) -> int | None:
+        return self._dimension
+
+    def embed(self, texts: Sequence[str]) -> list[list[float]]:
+        return self._post(list(texts))
+
+    def embed_media(self, files: Sequence[MediaFile]) -> list[list[float]]:
+        """Send each file as an item `{"<kind>": "data:..."}`, as SGLang takes it.
+
+        The kind is `image` or `audio`, from the MIME type (ADR-007, ADR-011).
+        """
+        return self._post([{media.kind: media.data_uri()} for media in files])
+
+    def _post(self, items: list[str] | list[dict[str, str]]) -> list[list[float]]:
+        headers = {"Authorization": f"Bearer {self._token}"} if self._token else {}
+        try:
+            response = httpx2.post(
+                self._url,
+                json={"model": self._model, "input": items},
+                headers=headers,
+                timeout=self._timeout,
+            )
+        except httpx2.TimeoutException:
+            raise TimeoutError(
+                f"the embedder did not answer in {self._timeout:g} seconds"
+            ) from None
+        except httpx2.HTTPError as error:
+            raise RuntimeError(f"the embedder cannot be reached: {type(error).__name__}") from None
+        if response.status_code != 200:
+            raise RuntimeError(f"the embedder answered with HTTP {response.status_code}")
+        try:
+            data = sorted(response.json()["data"], key=lambda item: item["index"])
+            vectors = [[float(x) for x in item["embedding"]] for item in data]
+        except (ValueError, KeyError, TypeError):
+            raise RuntimeError(
+                "the embedder gave an answer that is not an embedding list"
+            ) from None
+        if len(vectors) != len(items):
+            raise RuntimeError(f"the embedder gave {len(vectors)} vectors for {len(items)} inputs")
+        if vectors:
+            self._dimension = len(vectors[0])
+        return vectors

curu_memory/errors.py

@@ -0,0 +1,96 @@
+"""Typed errors, and the one mapping from them to MCP tool results.
+
+The application raises these errors and knows no MCP. The server calls
+`tool_result_from` in one place, so that each failure reaches the agent as an error
+result whose one text block is a JSON object with `code`, `message` and `details`.
+
+The result is built here, not raised as a `ToolError`, because SDK 2.x puts
+"Error executing tool <name>: " before each `ToolError` message.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp_types import CallToolResult, TextContent
+
+
+class CuruMemoryError(Exception):
+    """A failure that the caller can act on. Each subclass has one code."""
+
+    code = "error"
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+
+class IndexMissing(CuruMemoryError):
+    code = "index_missing"
+
+    def __init__(self, tier_space: str) -> None:
+        super().__init__(
+            f"There is no index for the {tier_space} knowledge. "
+            "Ask the operator to run: curu-memory index",
+            {"tier_space": tier_space},
+        )
+
+
+class ConceptNotFound(CuruMemoryError):
+    code = "concept_not_found"
+
+    def __init__(self, concept_id: str) -> None:
+        super().__init__(
+            f"No concept has the identifier {concept_id!r}. "
+            "Use an identifier from search_knowledge.",
+            {"id": concept_id},
+        )
+
+
+class InvalidArgument(CuruMemoryError):
+    code = "invalid_argument"
+
+    def __init__(self, field: str, message: str) -> None:
+        super().__init__(message, {"field": field})
+
+
+class EmbedderFailed(CuruMemoryError):
+    code = "embedder_failed"
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(
+            f"The embedder failed: {reason}. The old index is unchanged. "
+            "Make sure that the embedder runs, then run the index command again.",
+            {"reason": reason},
+        )
+
+
+class NoReadableSpace(CuruMemoryError):
+    """The caller can read no space, for example a person that the operator removed."""
+
+    code = "access_refused"
+
+    def __init__(self) -> None:
+        super().__init__(
+            "The caller can read no space. Ask the operator to register the person "
+            "or to give it a role.",
+        )
+
+
+class IndexRefused(CuruMemoryError):
+    """The index command refuses a space, and no index changes."""
+
+    code = "index_refused"
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+def tool_result_from(error: CuruMemoryError) -> CallToolResult:
+    """Convert an application error to the error result that the agent gets."""
+    body: dict[str, Any] = {"code": error.code, "message": error.message}
+    if error.details is not None:
+        body["details"] = error.details
+    return CallToolResult(is_error=True, content=[TextContent(text=json.dumps(body))])