atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/memory/types.py

@@ -0,0 +1,398 @@
+"""V3 memory types.
+
+Port of `atomicmemory-sdk/src/memory/types.ts`. Pydantic v2 models with
+snake_case field names; wire-format translation (e.g. core's `user_id`
+or `created_at`) lives in each provider's `mappers.py`.
+
+The discriminated union `IngestInput` is modeled with Pydantic's
+`discriminator="mode"` so callers can pass plain dicts and validation
+picks the right variant.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool
+
+from atomicmemory.memory.filters import FieldFilterOp, FilterExpr
+
+# ---------------------------------------------------------------------------
+# Identity / partition
+# ---------------------------------------------------------------------------
+
+
+MessageRole = Literal["user", "assistant", "system", "tool"]
+MemoryKind = Literal["fact", "episode", "summary", "procedure", "document"]
+MemoryVersionEvent = Literal["created", "updated", "superseded", "invalidated"]
+PackageFormat = Literal["flat", "tiered", "structured"]
+IngestMode = Literal["text", "messages", "verbatim"]
+
+
+class Scope(BaseModel):
+    """Identity and partition context for memory operations.
+
+    Providers declare which fields they require via
+    ``capabilities().required_scope``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    user: str | None = None
+    agent: str | None = None
+    namespace: str | None = None
+    thread: str | None = None
+
+
+class MemoryRef(BaseModel):
+    """Reference to a specific memory within a scope."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    scope: Scope
+
+
+class Provenance(BaseModel):
+    """Where a memory came from."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source: str | None = None
+    source_url: str | None = None
+    source_id: str | None = None
+    extractor: str | None = None
+
+
+class Memory(BaseModel):
+    """A single memory unit returned by get/list/search."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    content: str
+    scope: Scope
+    kind: MemoryKind | None = None
+    created_at: datetime
+    updated_at: datetime | None = None
+    provenance: Provenance | None = None
+    metadata: dict[str, Any] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Ingest
+# ---------------------------------------------------------------------------
+
+
+class IngestBase(BaseModel):
+    """Common ingest fields shared by every mode."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    scope: Scope
+    provenance: Provenance | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class TextIngest(IngestBase):
+    """Raw text: conversation transcript, document, note."""
+
+    mode: Literal["text"] = "text"
+    content: str
+
+
+class Message(BaseModel):
+    """One turn in a structured chat conversation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    role: MessageRole
+    content: str
+    name: str | None = None
+
+
+class MessageIngest(IngestBase):
+    """Structured chat messages."""
+
+    mode: Literal["messages"] = "messages"
+    messages: list[Message]
+
+
+class VerbatimIngest(IngestBase):
+    """Bypass LLM extraction; store the content as a single memory.
+
+    Capability-gated — only available when
+    ``capabilities().ingest_modes`` includes ``"verbatim"``.
+    """
+
+    mode: Literal["verbatim"] = "verbatim"
+    content: str
+    kind: MemoryKind | None = None
+
+
+IngestInput = Annotated[
+    TextIngest | MessageIngest | VerbatimIngest,
+    Field(discriminator="mode"),
+]
+
+
+class IngestResult(BaseModel):
+    """Per-id outcome of a single ingest call."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    created: list[str] = Field(default_factory=list)
+    updated: list[str] = Field(default_factory=list)
+    unchanged: list[str] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Search
+# ---------------------------------------------------------------------------
+
+
+class SearchRequest(BaseModel):
+    """Provider-agnostic search request."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    query: str
+    scope: Scope
+    limit: int | None = None
+    threshold: float | None = None
+    filter: FilterExpr | None = None
+    reranker: str | None = None
+
+
+class SearchResult(BaseModel):
+    """A single search hit.
+
+    ``score`` is the backward-compatible composite score (provider-
+    specific). Prefer the explicit ``similarity``, ``ranking_score``, and
+    ``relevance`` fields when the provider exposes them.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    memory: Memory
+    score: float
+    similarity: float | None = None
+    ranking_score: float | None = None
+    relevance: float | None = None
+
+
+class SearchResultPage(BaseModel):
+    """Paginated page of search results."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    results: list[SearchResult] = Field(default_factory=list)
+    cursor: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# List
+# ---------------------------------------------------------------------------
+
+
+class ListRequest(BaseModel):
+    """Paginated list request scoped to a single user/workspace."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    scope: Scope
+    limit: int | None = None
+    cursor: str | None = None
+    filter: FilterExpr | None = None
+
+
+class ListResultPage(BaseModel):
+    """Paginated page of memories."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    memories: list[Memory] = Field(default_factory=list)
+    cursor: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Context packaging
+# ---------------------------------------------------------------------------
+
+
+class PackageRequest(SearchRequest):
+    """Search request augmented with token-budget + format hints."""
+
+    token_budget: int | None = None
+    format: PackageFormat | None = None
+
+
+class ContextPackage(BaseModel):
+    """Injection-ready context for an AI assistant.
+
+    Attributes:
+        text: Formatted string for prompt injection.
+        results: Memories that contributed to ``text`` (debugging / attribution).
+        tokens: Estimated context tokens used by ``text``.
+        budget_constrained: True iff the requested token budget shaped the
+            package — eligible memories were omitted entirely or eligible
+            richer detail (L1/L2 tier, query-term-revealing upgrades) was
+            suppressed solely because the budget could not afford it.
+            Quota-driven demotion (e.g. fixed-cap policy) is NOT flagged.
+            Powers the v5 CLI envelope's ``meta.budget_constrained`` field.
+            Uses ``StrictBool`` so non-boolean wire values raise instead
+            of silently coercing.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    text: str
+    results: list[SearchResult] = Field(default_factory=list)
+    tokens: int = 0
+    budget_constrained: StrictBool
+
+
+# ---------------------------------------------------------------------------
+# Capabilities
+# ---------------------------------------------------------------------------
+
+
+class CapabilitiesRequiredScope(BaseModel):
+    """Per-operation required-scope manifest.
+
+    The ``list_`` field is named with a trailing underscore because
+    ``list`` is a Python builtin used inside the type annotation itself
+    (``list[str]``) and shadows it during forward-ref evaluation. The
+    JSON wire format still uses ``"list"`` via the alias.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    default: list[str]
+    ingest: list[str] | None = None
+    search: list[str] | None = None
+    get: list[str] | None = None
+    delete: list[str] | None = None
+    list_: list[str] | None = Field(default=None, alias="list")
+    update: list[str] | None = None
+    package: list[str] | None = None
+    temporal: list[str] | None = None
+    graph: list[str] | None = None
+    forget: list[str] | None = None
+    profile: list[str] | None = None
+    reflect: list[str] | None = None
+    versioning: list[str] | None = None
+    batch: list[str] | None = None
+
+
+class CapabilitiesExtensions(BaseModel):
+    """Boolean manifest of supported V3 extensions."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    update: bool = False
+    package: bool = False
+    temporal: bool = False
+    graph: bool = False
+    forget: bool = False
+    profile: bool = False
+    reflect: bool = False
+    versioning: bool = False
+    batch: bool = False
+    health: bool = False
+
+
+class CustomExtensionMeta(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    version: str | None = None
+    description: str | None = None
+
+
+class Capabilities(BaseModel):
+    """Provider capability surface returned by ``provider.capabilities()``."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    ingest_modes: list[IngestMode]
+    required_scope: CapabilitiesRequiredScope
+    extensions: CapabilitiesExtensions
+    custom_extensions: dict[str, CustomExtensionMeta] | None = None
+    supported_rerankers: list[str] | None = None
+    supported_filter_ops: list[FieldFilterOp] | None = None
+    max_token_budget: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# Extension-specific types
+# ---------------------------------------------------------------------------
+
+
+class GraphSearchRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    query: str
+    scope: Scope
+    limit: int | None = None
+    graph_scope: Literal["nodes", "edges", "episodes"] | None = None
+    reranker: str | None = None
+
+
+class GraphNode(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    id: str
+    label: str
+    summary: str | None = None
+    score: float | None = None
+
+
+class GraphEdge(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    id: str
+    fact: str
+    from_: str = Field(alias="from")
+    to: str
+    valid_at: datetime | None = None
+    invalid_at: datetime | None = None
+    score: float | None = None
+
+
+class GraphResult(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    nodes: list[GraphNode] = Field(default_factory=list)
+    edges: list[GraphEdge] = Field(default_factory=list)
+
+
+class Profile(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    summary: str
+    facts: list[str] | None = None
+    updated_at: datetime | None = None
+
+
+class Insight(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    content: str
+    confidence: float
+    supporting_memory_ids: list[str] = Field(default_factory=list)
+
+
+class MemoryVersion(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    id: str
+    content: str
+    created_at: datetime
+    parent_id: str | None = None
+    event: MemoryVersionEvent
+
+
+class HealthStatus(BaseModel):
+    """V3 capability-probe health response.
+
+    Distinct from AtomicMemory's `/memories/health` runtime snapshot.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    ok: bool
+    latency_ms: float | None = None
+    version: str | None = None

atomicmemory/providers/__init__.py

@@ -0,0 +1,5 @@
+"""Concrete memory providers.
+
+Each subpackage (`atomicmemory.providers.atomicmemory`, `mem0`) registers
+itself with the default registries on import.
+"""

atomicmemory/providers/atomicmemory/__init__.py

@@ -0,0 +1,43 @@
+"""AtomicMemory provider — HTTP client for atomicmemory-core.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/`. Importing
+this package registers the provider on
+`atomicmemory.memory.registry.default_registry` (and the async registry
+once Phase 4 lands).
+"""
+
+from atomicmemory.memory.registry import (
+    AsyncProviderRegistration,
+    ProviderRegistration,
+    default_async_registry,
+    default_registry,
+)
+from atomicmemory.providers.atomicmemory.async_provider import AsyncAtomicMemoryProvider
+from atomicmemory.providers.atomicmemory.config import AtomicMemoryProviderConfig
+from atomicmemory.providers.atomicmemory.provider import AtomicMemoryProvider
+
+
+def _coerce_config(config: object) -> AtomicMemoryProviderConfig:
+    if isinstance(config, AtomicMemoryProviderConfig):
+        return config
+    return AtomicMemoryProviderConfig.model_validate(config)
+
+
+def _factory(config: object) -> ProviderRegistration:
+    """Construct an AtomicMemoryProvider from a config dict or model."""
+    return ProviderRegistration(provider=AtomicMemoryProvider(_coerce_config(config)))
+
+
+def _async_factory(config: object) -> AsyncProviderRegistration:
+    return AsyncProviderRegistration(provider=AsyncAtomicMemoryProvider(_coerce_config(config)))
+
+
+default_registry.register("atomicmemory", _factory)
+default_async_registry.register("atomicmemory", _async_factory)
+
+
+__all__ = [
+    "AsyncAtomicMemoryProvider",
+    "AtomicMemoryProvider",
+    "AtomicMemoryProviderConfig",
+]

atomicmemory/providers/atomicmemory/agents.py

@@ -0,0 +1,156 @@
+"""AtomicMemoryAgents — agent trust + conflicts category.
+
+Port of the agents section of
+`atomicmemory-sdk/src/memory/atomicmemory-provider/handle-impl.ts:1110-1228`.
+
+These routes live under ``/agents/*`` (NOT ``/memories/*``).
+``set_trust`` / ``get_trust`` / ``conflicts`` / ``auto_resolve_conflicts``
+are user-scoped; ``resolve_conflict`` is keyed by conflict id directly
+(core resolves without a user context).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from atomicmemory.providers.atomicmemory.handle import (
+    AutoResolveConflictsResult,
+    ConflictResolution,
+    ConflictsListResult,
+    GetTrustResult,
+    ResolveConflictResult,
+    SetTrustResult,
+)
+from atomicmemory.providers.atomicmemory.http import HttpOptions, afetch_json, fetch_json
+
+Route = Callable[[str], str]
+
+
+class AtomicMemoryAgents:
+    """Agent trust + conflict resolution operations."""
+
+    def __init__(self, client: httpx.Client, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+
+    def set_trust(
+        self,
+        user_id: str,
+        agent_id: str,
+        trust_level: float,
+        display_name: str | None = None,
+    ) -> SetTrustResult:
+        body: dict[str, Any] = {
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "trust_level": trust_level,
+        }
+        if display_name is not None:
+            body["display_name"] = display_name
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/agents/trust"),
+            method="PUT",
+            json=body,
+        )
+        return SetTrustResult.model_validate(raw)
+
+    def get_trust(self, user_id: str, agent_id: str) -> GetTrustResult:
+        path = self._route(f"/agents/trust?user_id={quote(user_id, safe='')}&agent_id={quote(agent_id, safe='')}")
+        raw = fetch_json(self._client, self._http, path)
+        return GetTrustResult.model_validate(raw)
+
+    def conflicts(self, user_id: str) -> ConflictsListResult:
+        path = self._route(f"/agents/conflicts?user_id={quote(user_id, safe='')}")
+        raw = fetch_json(self._client, self._http, path)
+        return ConflictsListResult.model_validate(raw)
+
+    def resolve_conflict(self, conflict_id: str, resolution: ConflictResolution) -> ResolveConflictResult:
+        path = self._route(f"/agents/conflicts/{quote(conflict_id, safe='')}/resolve")
+        raw = fetch_json(
+            self._client,
+            self._http,
+            path,
+            method="PUT",
+            json={"resolution": resolution},
+        )
+        return ResolveConflictResult.model_validate(raw)
+
+    def auto_resolve_conflicts(self, user_id: str) -> AutoResolveConflictsResult:
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/agents/conflicts/auto-resolve"),
+            method="POST",
+            json={"user_id": user_id},
+        )
+        return AutoResolveConflictsResult.model_validate(raw)
+
+
+class AsyncAtomicMemoryAgents:
+    """Async counterpart of :class:`AtomicMemoryAgents`."""
+
+    def __init__(self, client: httpx.AsyncClient, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+
+    async def set_trust(
+        self,
+        user_id: str,
+        agent_id: str,
+        trust_level: float,
+        display_name: str | None = None,
+    ) -> SetTrustResult:
+        body: dict[str, Any] = {
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "trust_level": trust_level,
+        }
+        if display_name is not None:
+            body["display_name"] = display_name
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/agents/trust"),
+            method="PUT",
+            json=body,
+        )
+        return SetTrustResult.model_validate(raw)
+
+    async def get_trust(self, user_id: str, agent_id: str) -> GetTrustResult:
+        path = self._route(f"/agents/trust?user_id={quote(user_id, safe='')}&agent_id={quote(agent_id, safe='')}")
+        raw = await afetch_json(self._client, self._http, path)
+        return GetTrustResult.model_validate(raw)
+
+    async def conflicts(self, user_id: str) -> ConflictsListResult:
+        path = self._route(f"/agents/conflicts?user_id={quote(user_id, safe='')}")
+        raw = await afetch_json(self._client, self._http, path)
+        return ConflictsListResult.model_validate(raw)
+
+    async def resolve_conflict(self, conflict_id: str, resolution: ConflictResolution) -> ResolveConflictResult:
+        path = self._route(f"/agents/conflicts/{quote(conflict_id, safe='')}/resolve")
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            path,
+            method="PUT",
+            json={"resolution": resolution},
+        )
+        return ResolveConflictResult.model_validate(raw)
+
+    async def auto_resolve_conflicts(self, user_id: str) -> AutoResolveConflictsResult:
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/agents/conflicts/auto-resolve"),
+            method="POST",
+            json={"user_id": user_id},
+        )
+        return AutoResolveConflictsResult.model_validate(raw)