mimvo 0.2.0__py3-none-any.whl

mimvo/__init__.py

@@ -0,0 +1,53 @@
+"""Scan agent memory for poisoned facts, hidden instructions, and leaked secrets.
+
+From the command line:
+
+    mimvo scan chroma --path ./chroma_db --collection agent_memory
+    mimvo scan jsonl export.jsonl --report report.html --json findings.json
+
+From Python, create a `Mimvo` and call `scan`. The scan reads records and
+returns a `ScanReport`. It does not change the store.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .client import AsyncMimvo, Mimvo
+from .config import Config
+from .exceptions import (
+    BackendError,
+    ConfigurationError,
+    MimvoError,
+)
+from .models import (
+    Action,
+    Category,
+    Finding,
+    MemoryCandidate,
+    MemoryRecord,
+    MemoryStatus,
+    Risk,
+    ScanError,
+    ScanReport,
+    Severity,
+)
+
+__all__ = [
+    "Action",
+    "AsyncMimvo",
+    "BackendError",
+    "Category",
+    "Config",
+    "ConfigurationError",
+    "Finding",
+    "MemoryCandidate",
+    "MemoryRecord",
+    "MemoryStatus",
+    "Mimvo",
+    "MimvoError",
+    "Risk",
+    "ScanError",
+    "ScanReport",
+    "Severity",
+    "__version__",
+]

mimvo/_coerce.py

@@ -0,0 +1,72 @@
+"""Turn loose caller input into `MemoryCandidate` and `MemoryRecord`.
+
+Callers can pass a string, a dict, or an existing model. These helpers
+accept all three so the common case stays short.
+"""
+
+from __future__ import annotations
+
+from .exceptions import ConfigurationError
+from .models.memory import MemoryCandidate, MemoryRecord
+
+
+def coerce_candidate(content: str | MemoryCandidate | dict) -> MemoryCandidate:
+    """Turn one input into a `MemoryCandidate`.
+
+    Args:
+        content: The memory to scan. A string becomes the `content` field.
+            A dict is validated as a `MemoryCandidate`. A `MemoryCandidate`
+            is returned unchanged.
+
+    Returns:
+        A `MemoryCandidate` the checks can read.
+
+    Raises:
+        ConfigurationError: `content` is not a string, a dict, or a
+            `MemoryCandidate`.
+    """
+    if isinstance(content, MemoryCandidate):
+        return content
+    if isinstance(content, dict):
+        return MemoryCandidate.model_validate(content)
+    if isinstance(content, str):
+        return MemoryCandidate(content=content)
+    raise ConfigurationError(f"Cannot interpret content: {content!r}")
+
+
+def coerce_record(item: object) -> MemoryRecord:
+    """Turn one input into a `MemoryRecord`.
+
+    Args:
+        item: A `MemoryRecord`, returned unchanged, or a dict with at least
+            an `id` and a `content` string.
+
+    Returns:
+        A `MemoryRecord` the scan engine can read.
+
+    Raises:
+        ConfigurationError: `item` is not a record or a dict.
+    """
+    if isinstance(item, MemoryRecord):
+        return item
+    if isinstance(item, dict):
+        return MemoryRecord.model_validate(item)
+    raise ConfigurationError(f"Cannot interpret record: {item!r}")
+
+
+def coerce_records(records: list) -> list[MemoryRecord]:
+    """Turn a list of records or dicts into `MemoryRecord` objects.
+
+    Args:
+        records: Each item is passed to `coerce_record`.
+
+    Returns:
+        One `MemoryRecord` per item, in the same order.
+
+    Raises:
+        ConfigurationError: Any item is not a record or a dict.
+    """
+    return [coerce_record(item) for item in records]
+
+
+__all__ = ["coerce_candidate", "coerce_record", "coerce_records"]

mimvo/_version.py

@@ -0,0 +1,11 @@
+"""The installed Mimvo version, in a module with no imports.
+
+Reports stamp this onto their output. Keeping it here lets the models
+import it without importing the whole package.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

mimvo/checks/__init__.py

@@ -0,0 +1,54 @@
+"""Built-in checks and `default_checks`.
+
+`default_checks()` returns the standard pipeline: secrets, injection, then
+poisoning. Each one uses an offline detector unless you pass your own.
+
+Pass a configured `InjectionCheck`, `PoisoningCheck`, or `SecretsCheck` in
+`Mimvo(checks=[...])` to replace the default check of the same name.
+A check with a new name is added alongside the defaults.
+"""
+
+from __future__ import annotations
+
+from .base import MemoryCheck, Phase
+from .security import (
+    BaseDetector,
+    Detection,
+    Detector,
+    InjectionCheck,
+    PoisoningCheck,
+    SecretsCheck,
+    SecurityCheck,
+)
+
+
+def default_checks() -> list[MemoryCheck]:
+    """Return the checks `Mimvo()` runs, in order.
+
+    The order is secrets, then injection, then poisoning. Each check uses
+    its offline detector, so this list needs no network and no model download.
+    The same input always produces the same findings.
+
+    Returns:
+        A new list of check instances. Call it again for a fresh list; do
+        not share one list across clients.
+    """
+    return [
+        SecretsCheck(),
+        InjectionCheck(),
+        PoisoningCheck(),
+    ]
+
+
+__all__ = [
+    "BaseDetector",
+    "Detection",
+    "Detector",
+    "InjectionCheck",
+    "MemoryCheck",
+    "Phase",
+    "PoisoningCheck",
+    "SecretsCheck",
+    "SecurityCheck",
+    "default_checks",
+]

mimvo/checks/base.py

@@ -0,0 +1,149 @@
+"""The `MemoryCheck` base class and the contract the engine runs it through.
+
+A check looks at one memory and returns findings. The simplest check sets
+`name` and implements `check`. Adding a check does not require editing the
+engine: the engine only uses the methods defined here.
+
+A scan reads the store once, as a stream, then runs a second pass over the
+packed corpus for work that compares records with each other. A check says
+which passes it needs (`phases`), records what it saw on each pass
+(`observe`), and turns those observations into findings once its last pass
+is done (`conclude`). The defaults wrap `check`, so a plain check never
+has to think about passes; `SecurityCheck` overrides them to split its
+detectors across the passes and vote over both.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from enum import StrEnum
+
+from ..context import CheckContext
+from ..models.finding import Finding
+from ..models.memory import MemoryCandidate
+
+
+class Phase(StrEnum):
+    """The two passes of a scan.
+
+    Attributes:
+        STREAM: While records are read, one at a time. Only the record
+            itself (and records already read) can be seen.
+        CORPUS: After every record has been read. `context.existing` and
+            the corpus hold the whole scan.
+    """
+
+    STREAM = "stream"
+    CORPUS = "corpus"
+
+
+class MemoryCheck:
+    """One named check over a single memory.
+
+    Set `name` and implement `check`. The built-in security checks subclass
+    `SecurityCheck`, which subclasses this.
+
+    Attributes:
+        name: Label stored on each finding this check emits. The client uses
+            it to replace a default check: a custom check named `"injection"`
+            takes the place of the built-in injection check.
+        needs_corpus: Whether `check` reads other records. `True` (or
+            unset) runs it once every record has been read, so
+            `context.existing` is the whole scan; `False` runs it while
+            records stream in.
+    """
+
+    name: str = "base"
+    needs_corpus: bool | None = None
+
+    def check(self, candidate: MemoryCandidate, context: CheckContext) -> list[Finding]:
+        """Inspect one memory and return every problem found.
+
+        Args:
+            candidate: The memory being scanned. Read `candidate.content`.
+            context: Scan settings, the clock, neighbouring records, and the
+                optional retrieval query.
+
+        Returns:
+            Findings for this memory. An empty list means this check found
+            nothing. Never return `None`.
+
+        Raises:
+            NotImplementedError: Always, unless a subclass implements this.
+        """
+        raise NotImplementedError
+
+    # -- engine contract ---------------------------------------------------------
+
+    def phases(self) -> frozenset[Phase]:
+        """Which passes this check runs in.
+
+        Returns:
+            `{CORPUS}` unless `needs_corpus` is `False`, then `{STREAM}`.
+            A check that returns both is observed on each pass and
+            concluded after the corpus pass.
+        """
+        return frozenset({Phase.STREAM if self.needs_corpus is False else Phase.CORPUS})
+
+    def observe(self, candidate: MemoryCandidate, context: CheckContext, phase: Phase) -> object:
+        """Look at one memory during one pass.
+
+        The engine keeps whatever this returns and hands every observation
+        for the record to `conclude` after the check's last pass.
+
+        Args:
+            candidate: The memory being scanned.
+            context: Scan context.
+            phase: The pass being run. Always one of `phases()`.
+
+        Returns:
+            An observation only this check needs to understand. The default
+            is the list of findings `check` returned. An empty (falsy)
+            observation means "nothing seen": the engine may drop it rather
+            than keep it until the corpus pass.
+        """
+        return self.check(candidate, context)
+
+    def observe_batch(
+        self,
+        candidates: Sequence[MemoryCandidate],
+        context: CheckContext,
+        phase: Phase,
+    ) -> list[object]:
+        """Look at several memories during one pass.
+
+        The engine hands each pass to checks in batches of
+        `Config.batch_size` records, so a check whose work batches well,
+        such as a model forward pass, can do it once per batch.
+
+        Args:
+            candidates: The memories, in scan order.
+            context: Scan context.
+            phase: The pass being run.
+
+        Returns:
+            One observation per candidate, in the same order. The default
+            calls `observe` on each.
+        """
+        return [self.observe(candidate, context, phase) for candidate in candidates]
+
+    def conclude(self, observations: Sequence[object]) -> list[Finding]:
+        """Turn one record's observations into findings.
+
+        Args:
+            observations: What `observe` returned for this record, one per
+                pass the check ran in, in pass order.
+
+        Returns:
+            The record's findings. The default joins the finding lists.
+            The engine stamps this check's `name` on any finding whose
+            `check` is unset.
+        """
+        findings: list[Finding] = []
+        for observation in observations:
+            if isinstance(observation, list):
+                findings.extend(f for f in observation if isinstance(f, Finding))
+        return findings
+
+
+__all__ = ["MemoryCheck", "Phase"]

mimvo/checks/security/__init__.py

@@ -0,0 +1,43 @@
+"""Security checks: injection, poisoning, and secrets.
+
+Layout:
+
+    security/
+      base.py       SecurityCheck, Detector, Detection
+      injection/    InjectionCheck and one detector per method
+      poisoning/    PoisoningCheck and one detector per method
+      secrets/      SecretsCheck and one detector per method
+
+Each check runs detectors and turns their hits into findings. The defaults
+are offline heuristics. Model and hosted detectors are optional.
+
+Example:
+    Replace the default injection check with heuristic plus Prompt Guard::
+
+        from mimvo import Mimvo
+        from mimvo.checks.security import InjectionCheck
+        from mimvo.checks.security.injection import (
+            HeuristicInjectionDetector, PromptGuardDetector,
+        )
+
+        guard = Mimvo(checks=[
+            InjectionCheck(detectors=[HeuristicInjectionDetector(), PromptGuardDetector()]),
+        ])
+"""
+
+from __future__ import annotations
+
+from .base import BaseDetector, Detection, Detector, SecurityCheck
+from .injection import InjectionCheck
+from .poisoning import PoisoningCheck
+from .secrets import SecretsCheck
+
+__all__ = [
+    "BaseDetector",
+    "Detection",
+    "Detector",
+    "InjectionCheck",
+    "PoisoningCheck",
+    "SecretsCheck",
+    "SecurityCheck",
+]