memtru 0.1.0__py3-none-any.whl

memtru/__init__.py

@@ -0,0 +1,7 @@
+"""Memtru: reproducible reliability and isolation tests for AI agent memory."""
+
+__version__ = "0.1.0"
+
+REPORT_SCHEMA_VERSION = "1.0"
+
+__all__ = ["REPORT_SCHEMA_VERSION", "__version__"]

memtru/adapters/__init__.py

@@ -0,0 +1,105 @@
+"""Adapter registry: builds the adapter described by the configuration."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from dataclasses import dataclass
+
+from memtru.adapters.base import AgentAdapter, MemoryAdapter
+from memtru.adapters.in_memory import InMemoryAdapter
+from memtru.core.config import (
+    Config,
+    CustomAdapterConfig,
+    HttpAdapterConfig,
+    InMemoryAdapterConfig,
+    Mem0AdapterConfig,
+)
+from memtru.errors import ConfigError
+
+__all__ = ["AgentAdapter", "MemoryAdapter", "build_adapter", "describe_builtin_adapters"]
+
+
+@dataclass(frozen=True)
+class AdapterInfo:
+    type: str
+    summary: str
+    verification: str
+
+
+BUILTIN_ADAPTERS = [
+    AdapterInfo(
+        "in_memory",
+        "Built-in reference store with tenant, user and session scoping. Supports fault injection.",
+        "Verified by the Memtru test suite.",
+    ),
+    AdapterInfo(
+        "http",
+        "Any service implementing the Memtru REST contract (docs/adapters.md).",
+        "Verified against the reference server in examples/provider-integration.",
+    ),
+    AdapterInfo(
+        "mem0",
+        "Mem0 OSS 2.2.1; explicit SDK factory, synthetic search-filter testing.",
+        "SDK contract tests and local Qdrant integration; hosted verification is separate.",
+    ),
+    AdapterInfo(
+        "custom",
+        "Your own Python class implementing memtru.adapters.base.MemoryAdapter.",
+        "Verified by you: Memtru only loads it.",
+    ),
+]
+
+
+def describe_builtin_adapters() -> list[AdapterInfo]:
+    return list(BUILTIN_ADAPTERS)
+
+
+def _load_custom(config: CustomAdapterConfig) -> MemoryAdapter:
+    module_name, _, attr = config.entrypoint.partition(":")
+    # Like pytest, resolve user modules relative to the directory the CLI runs in.
+    if os.getcwd() not in sys.path:
+        sys.path.insert(0, os.getcwd())
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as err:
+        raise ConfigError(
+            f"Cannot import adapter module {module_name!r}: {err}",
+            hint="Make sure the module is importable from the current directory or PYTHONPATH.",
+        ) from None
+    factory = getattr(module, attr, None)
+    if factory is None:
+        raise ConfigError(f"{module_name!r} has no attribute {attr!r}.")
+    adapter = factory(**config.options)
+    if not isinstance(adapter, MemoryAdapter):
+        raise ConfigError(f"{config.entrypoint} did not produce a MemoryAdapter instance.")
+    return adapter
+
+
+def build_adapter(config: Config) -> MemoryAdapter:
+    adapter_config = config.adapter
+    if isinstance(adapter_config, InMemoryAdapterConfig):
+        return InMemoryAdapter(adapter_config.faults, adapter_config.index_delay_ms)
+    if isinstance(adapter_config, HttpAdapterConfig):
+        from memtru.adapters.http import HttpAdapter
+
+        return HttpAdapter(adapter_config, environment=config.execution.environment)
+    if isinstance(adapter_config, CustomAdapterConfig):
+        return _load_custom(adapter_config)
+    if isinstance(adapter_config, Mem0AdapterConfig):
+        from memtru.adapters.mem0 import Mem0Adapter
+
+        # The optional SDK otherwise enables its own telemetry at import time.
+        os.environ["MEM0_TELEMETRY"] = "false"
+        module_name, _, attr = adapter_config.factory.partition(":")
+        if os.getcwd() not in sys.path:
+            sys.path.insert(0, os.getcwd())
+        try:
+            factory = getattr(importlib.import_module(module_name), attr)
+        except (ImportError, AttributeError):
+            raise ConfigError(
+                "Cannot load Mem0 factory. Check adapter.factory and install memtru[mem0]."
+            ) from None
+        return Mem0Adapter(factory())
+    raise ConfigError(f"Unknown adapter type {adapter_config!r}")  # pragma: no cover

memtru/adapters/base.py

@@ -0,0 +1,80 @@
+"""The adapter contract every memory provider integration implements.
+
+Adapters translate Memtru operations into calls on a real memory system.
+They must scope every operation to the given :class:`MemoryContext`; the
+scenarios then verify whether that scoping actually holds.
+
+Optional operations raise :class:`UnsupportedCapabilityError` by default.
+Declare what is supported in :meth:`MemoryAdapter.capabilities` so scenarios
+can be skipped, never silently passed, when a prerequisite is missing.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from memtru.core.models import Capability, MemoryContext, MemoryRecord, MemoryScope
+from memtru.errors import UnsupportedCapabilityError
+
+
+class MemoryAdapter(ABC):
+    name: ClassVar[str]
+    version: ClassVar[str] = "1.0"
+
+    @abstractmethod
+    def capabilities(self) -> frozenset[Capability]:
+        """Capabilities this adapter supports *and* boundaries it claims to enforce."""
+
+    def setup(self, namespace: str) -> None:  # noqa: B027 - optional hook
+        """Prepare an isolated test namespace. Called once per run."""
+
+    def teardown(self, namespace: str) -> None:  # noqa: B027 - optional hook
+        """Release the namespace created by :meth:`setup`. Must not touch other data."""
+
+    @abstractmethod
+    def add(
+        self,
+        ctx: MemoryContext,
+        content: str,
+        *,
+        metadata: dict[str, str] | None = None,
+        scope: MemoryScope = "user",
+    ) -> MemoryRecord: ...
+
+    @abstractmethod
+    def search(self, ctx: MemoryContext, query: str, *, limit: int = 10) -> list[MemoryRecord]: ...
+
+    def get(self, ctx: MemoryContext, memory_id: str) -> MemoryRecord | None:
+        raise UnsupportedCapabilityError(f"{self.name} does not support read by id")
+
+    def update(
+        self,
+        ctx: MemoryContext,
+        memory_id: str,
+        content: str,
+        *,
+        metadata: dict[str, str] | None = None,
+    ) -> MemoryRecord:
+        raise UnsupportedCapabilityError(f"{self.name} does not support updates")
+
+    def delete(self, ctx: MemoryContext, memory_id: str) -> None:
+        raise UnsupportedCapabilityError(f"{self.name} does not support deletion")
+
+    def describe(self) -> dict[str, str]:
+        """Safe, non-secret metadata included in reports."""
+        return {}
+
+    def close(self) -> None:  # noqa: B027 - optional hook
+        """Release connections."""
+
+
+class AgentAdapter(MemoryAdapter):
+    """An adapter that can also run the agent on top of the memory store.
+
+    Required for agent-mode scenarios (MT-POISON-007). ``respond`` must run the
+    real agent with the memory visible to ``ctx`` and return its final output.
+    """
+
+    @abstractmethod
+    def respond(self, ctx: MemoryContext, prompt: str) -> str: ...

memtru/adapters/http.py

@@ -0,0 +1,239 @@
+"""Adapter for any memory service that implements the Memtru REST contract.
+
+Contract (see docs/adapters.md for the full description)::
+
+    GET    /capabilities                 -> {"capabilities": ["MEMORY_WRITE", ...]}
+    POST   /memories                     body {content, metadata, scope} -> record
+    GET    /memories/search?q=..&limit=  -> {"results": [record, ...]}
+    GET    /memories/{id}                -> record | 404
+    PATCH  /memories/{id}                body {content, metadata} -> record
+    DELETE /memories/{id}                -> 204
+
+Every request carries the context as headers: X-Memtru-Tenant,
+X-Memtru-User, X-Memtru-Session (optional), X-Memtru-Namespace
+and X-Memtru-Run. A service under test maps those onto its own auth model;
+see docs/adapters.md for why that mapping is itself part of what is tested.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, ClassVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from memtru.adapters.base import MemoryAdapter
+from memtru.core.config import HttpAdapterConfig
+from memtru.core.models import Capability, MemoryContext, MemoryRecord, MemoryScope
+from memtru.errors import (
+    AdapterError,
+    ConfigError,
+    TransientAdapterError,
+    UnsafeTargetError,
+)
+from memtru.security.urls import UrlPolicy, check_url
+
+MAX_RESPONSE_BYTES = 1_000_000
+
+
+class _RecordModel(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    id: str = Field(min_length=1, max_length=256)
+    content: str = Field(max_length=100_000)
+    metadata: dict[str, str] = Field(default_factory=dict)
+    tenant_id: str | None = None
+    user_id: str | None = None
+    session_id: str | None = None
+    active: bool | None = None
+
+    def to_record(self) -> MemoryRecord:
+        return MemoryRecord(**self.model_dump())
+
+
+class HttpAdapter(MemoryAdapter):
+    name: ClassVar[str] = "http"
+    version: ClassVar[str] = "1.0"
+
+    def __init__(self, config: HttpAdapterConfig, *, environment: str) -> None:
+        policy = UrlPolicy(
+            allow_hosts=tuple(config.allow_hosts),
+            allow_loopback=config.allow_loopback,
+            allow_private_network=config.allow_private_network,
+        )
+        checked = check_url(config.base_url, policy)
+        if not checked.is_loopback and not config.authorization_confirmed:
+            raise UnsafeTargetError(
+                f"Remote target {checked.host} requires explicit authorization.",
+                hint=(
+                    "Set adapter.authorization_confirmed: true to confirm you are authorized "
+                    "to write and delete synthetic records on this system."
+                ),
+            )
+        if not checked.is_loopback and environment == "local":
+            raise ConfigError("execution.environment is 'local' but the target is remote.")
+        self._config = config
+        self._base = checked.url
+        self._host = checked.host
+        headers = {"User-Agent": "memtru", "Accept": "application/json"}
+        if config.token_env:
+            token = os.environ.get(config.token_env)
+            if not token:
+                raise ConfigError(
+                    f"Environment variable {config.token_env} is not set.",
+                    hint="adapter.token_env names the variable that holds the provider token.",
+                )
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(
+            base_url=self._base,
+            headers=headers,
+            timeout=config.timeout_seconds,
+            follow_redirects=False,
+        )
+        self._caps: frozenset[Capability] | None = None
+
+    # -- transport ---------------------------------------------------------------
+
+    @staticmethod
+    def _ctx_headers(ctx: MemoryContext) -> dict[str, str]:
+        headers = {
+            "X-Memtru-Tenant": ctx.tenant_id,
+            "X-Memtru-User": ctx.user_id,
+            "X-Memtru-Namespace": ctx.namespace,
+            "X-Memtru-Run": ctx.run_id,
+        }
+        if ctx.session_id:
+            headers["X-Memtru-Session"] = ctx.session_id
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        ctx: MemoryContext | None = None,
+        *,
+        params: dict[str, Any] | None = None,
+        payload: Any = None,
+        allow_404: bool = False,
+    ) -> Any:
+        headers = self._ctx_headers(ctx) if ctx else {}
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                with self._client.stream(
+                    method, path, params=params, json=payload, headers=headers
+                ) as response:
+                    body = b""
+                    for chunk in response.iter_bytes():
+                        body += chunk
+                        if len(body) > MAX_RESPONSE_BYTES:
+                            raise AdapterError(
+                                f"{method} {path}: response exceeded {MAX_RESPONSE_BYTES} bytes"
+                            )
+                    status = response.status_code
+                    content_type = response.headers.get("content-type", "")
+            except httpx.TimeoutException:
+                error: AdapterError = TransientAdapterError(f"{method} {path}: request timed out")
+            except httpx.TransportError as err:
+                error = TransientAdapterError(f"{method} {path}: {type(err).__name__}")
+            else:
+                if status in {429, 502, 503, 504}:
+                    error = TransientAdapterError(f"{method} {path}: HTTP {status}")
+                elif 300 <= status < 400:
+                    raise AdapterError(
+                        f"{method} {path}: unexpected redirect (HTTP {status}); redirects are "
+                        "not followed"
+                    )
+                elif status == 404 and allow_404:
+                    return None
+                elif status >= 400:
+                    raise AdapterError(f"{method} {path}: HTTP {status}")
+                elif status == 204 or not body:
+                    return None
+                elif "json" not in content_type:
+                    raise AdapterError(f"{method} {path}: expected JSON, got {content_type!r}")
+                else:
+                    try:
+                        return json.loads(body)
+                    except ValueError:
+                        raise AdapterError(f"{method} {path}: invalid JSON") from None
+            if attempt > self._config.max_retries:
+                raise error
+            time.sleep(min(0.25 * 2 ** (attempt - 1), 2.0))
+
+    @staticmethod
+    def _parse(data: Any, what: str) -> MemoryRecord:
+        try:
+            return _RecordModel.model_validate(data).to_record()
+        except ValidationError:
+            raise AdapterError(f"{what}: response is not a valid memory record") from None
+
+    # -- contract ----------------------------------------------------------------
+
+    def capabilities(self) -> frozenset[Capability]:
+        if self._caps is None:
+            names = self._config.capabilities
+            if names is None:
+                data = self._request("GET", "/capabilities")
+                if not isinstance(data, dict) or not isinstance(data.get("capabilities"), list):
+                    raise AdapterError("GET /capabilities: expected {'capabilities': [...]}")
+                names = [str(n) for n in data["capabilities"]]
+            known = {c.value for c in Capability}
+            self._caps = frozenset(Capability(n) for n in names if n in known)
+        return self._caps
+
+    def describe(self) -> dict[str, str]:
+        return {"host": self._host}
+
+    def add(
+        self,
+        ctx: MemoryContext,
+        content: str,
+        *,
+        metadata: dict[str, str] | None = None,
+        scope: MemoryScope = "user",
+    ) -> MemoryRecord:
+        data = self._request(
+            "POST",
+            "/memories",
+            ctx,
+            payload={"content": content, "metadata": metadata or {}, "scope": scope},
+        )
+        return self._parse(data, "POST /memories")
+
+    def search(self, ctx: MemoryContext, query: str, *, limit: int = 10) -> list[MemoryRecord]:
+        data = self._request("GET", "/memories/search", ctx, params={"q": query, "limit": limit})
+        if not isinstance(data, dict) or not isinstance(data.get("results"), list):
+            raise AdapterError("GET /memories/search: expected {'results': [...]}")
+        return [self._parse(item, "search result") for item in data["results"][:limit]]
+
+    def get(self, ctx: MemoryContext, memory_id: str) -> MemoryRecord | None:
+        data = self._request("GET", f"/memories/{quote(memory_id, safe='')}", ctx, allow_404=True)
+        return None if data is None else self._parse(data, "GET /memories/{id}")
+
+    def update(
+        self,
+        ctx: MemoryContext,
+        memory_id: str,
+        content: str,
+        *,
+        metadata: dict[str, str] | None = None,
+    ) -> MemoryRecord:
+        data = self._request(
+            "PATCH",
+            f"/memories/{quote(memory_id, safe='')}",
+            ctx,
+            payload={"content": content, "metadata": metadata or {}},
+        )
+        return self._parse(data, "PATCH /memories/{id}")
+
+    def delete(self, ctx: MemoryContext, memory_id: str) -> None:
+        self._request("DELETE", f"/memories/{quote(memory_id, safe='')}", ctx)
+
+    def close(self) -> None:
+        self._client.close()