memuron 0.1.1__py3-none-any.whl

memuron/domain/schemas.py

@@ -0,0 +1,581 @@
+"""Pydantic schemas for Memuron API."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import AliasChoices, BaseModel, Field, field_validator, model_validator
+
+from memuron.domain.limits import MAX_ADD_MEMORY_CONTENT, MAX_MEMORY_CONTENT, MAX_SCOPE_ITEMS, MAX_SCOPE_TOKEN_LEN
+from memuron.domain.scope_filter import parse_comma_scope, validate_scope_pattern
+
+SOURCE_IDENTITY_METADATA_PATH = "metadata.system.source"
+SOURCE_IDENTITY_FIELDS = ("custom_id", "session_id", "thread_id", "source_id", "source_url")
+
+
+def _clean_optional_string(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+class SourceIdentity(BaseModel):
+    """Stable provenance keys shared by ingest, URL, session, and sync paths."""
+
+    custom_id: str | None = Field(None, max_length=512)
+    session_id: str | None = Field(None, max_length=512)
+    thread_id: str | None = Field(None, max_length=512)
+    source_id: str | None = Field(None, max_length=512)
+    source_url: str | None = Field(None, max_length=4096)
+
+    @field_validator("custom_id", "session_id", "thread_id", "source_id", "source_url", mode="before")
+    @classmethod
+    def _strip_blank_strings(cls, value: Any) -> str | None:
+        return _clean_optional_string(value)
+
+    def as_metadata(self) -> dict[str, str]:
+        return {
+            key: value
+            for key, value in self.model_dump().items()
+            if isinstance(value, str) and value
+        }
+
+
+def source_identity_from_metadata(metadata: dict[str, Any] | None) -> dict[str, str]:
+    if not isinstance(metadata, dict):
+        return {}
+    system = metadata.get("system")
+    if not isinstance(system, dict):
+        return {}
+    source = system.get("source")
+    if not isinstance(source, dict):
+        return {}
+    output: dict[str, str] = {}
+    for key in SOURCE_IDENTITY_FIELDS:
+        value = _clean_optional_string(source.get(key))
+        if value:
+            output[key] = value
+    return output
+
+
+def merge_source_identity_metadata(
+    metadata: dict[str, Any] | None = None,
+    *,
+    custom_id: str | None = None,
+    session_id: str | None = None,
+    thread_id: str | None = None,
+    source_id: str | None = None,
+    source_url: str | None = None,
+) -> dict[str, Any]:
+    output = dict(metadata or {})
+    identity = SourceIdentity(
+        custom_id=custom_id,
+        session_id=session_id,
+        thread_id=thread_id,
+        source_id=source_id,
+        source_url=source_url,
+    ).as_metadata()
+    if not identity:
+        return output
+    system = dict(output.get("system") or {})
+    existing_source = system.get("source")
+    source = dict(existing_source) if isinstance(existing_source, dict) else {}
+    source.update(identity)
+    system["source"] = source
+    output["system"] = system
+    return output
+
+
+MAX_EXTERNAL_ID_LEN = 512
+MAX_SOURCE_URL_LEN = 4096
+
+
+class AddMemoryRequest(BaseModel):
+    content: str = Field(..., max_length=MAX_ADD_MEMORY_CONTENT)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    space_ref: str | None = Field(
+        None,
+        validation_alias=AliasChoices("space_ref", "space_id"),
+        description=(
+            "Target space UUID, slug, space.* token, or /spaces/space.* path; "
+            "defaults to the session default"
+        ),
+    )
+    custom_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    session_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    thread_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    source_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    source_url: str | None = Field(None, max_length=MAX_SOURCE_URL_LEN)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _merge_tags_into_scope(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        tags = data.get("tags")
+        scope = data.get("scope")
+        if tags is None:
+            return data
+        if scope is None:
+            data["scope"] = tags
+        return data
+
+    @field_validator("scope")
+    @classmethod
+    def _scope_string_lengths(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return value
+        for token in value:
+            if len(token) > MAX_SCOPE_TOKEN_LEN:
+                raise ValueError(
+                    f"Each scope token must be at most {MAX_SCOPE_TOKEN_LEN} characters"
+                )
+        return value
+
+    @field_validator("custom_id", "session_id", "thread_id", "source_id", "source_url", mode="before")
+    @classmethod
+    def _source_identity_strings(cls, value: Any) -> str | None:
+        return _clean_optional_string(value)
+
+    def memory_metadata(self) -> dict[str, Any]:
+        return merge_source_identity_metadata(
+            self.metadata,
+            custom_id=self.custom_id,
+            session_id=self.session_id,
+            thread_id=self.thread_id,
+            source_id=self.source_id,
+            source_url=self.source_url,
+        )
+
+
+class GetMemoriesRequest(BaseModel):
+    memory_ids: list[str]
+
+
+class UpdateMemoryRequest(BaseModel):
+    content: str | None = Field(None, max_length=MAX_MEMORY_CONTENT)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+
+    @field_validator("scope")
+    @classmethod
+    def _update_scope_lengths(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return value
+        for token in value:
+            if len(token) > MAX_SCOPE_TOKEN_LEN:
+                raise ValueError(
+                    f"Each scope token must be at most {MAX_SCOPE_TOKEN_LEN} characters"
+                )
+        return value
+
+
+class UnlinkMemoriesRequest(BaseModel):
+    memory_id_1: str
+    memory_id_2: str
+
+
+class BulkDeleteRequest(BaseModel):
+    scope: str = Field(..., min_length=1, description="Comma-separated scope patterns (required)")
+    confirm: bool = Field(..., description="Must be true to execute bulk delete")
+
+    @model_validator(mode="after")
+    def _validate_bulk_delete(self) -> "BulkDeleteRequest":
+        if not self.confirm:
+            raise ValueError("confirm must be true for bulk delete")
+        parse_comma_scope(self.scope)
+        return self
+
+
+class MemoryResponse(BaseModel):
+    id: str
+    content: str
+    type: Literal["text", "image", "document", "collection"] = "text"
+    node_type: Literal["text", "image", "document", "collection"] = Field(
+        "text",
+        deprecated=True,
+        description="Deprecated alias for type. New clients should read type.",
+    )
+    payload: dict[str, Any] = Field(default_factory=dict)
+    perception: str | None = None
+    encoding: str = "memory"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    custom_id: str | None = None
+    session_id: str | None = None
+    thread_id: str | None = None
+    source_id: str | None = None
+    source_url: str | None = None
+    scope: list[str]
+    links: list[str]
+    evolution_history: list[dict[str, Any]]
+    retrieval_count: int
+    timestamp: str
+
+
+class CreateMemoryResponse(BaseModel):
+    status: str = "success"
+    memory_id: str
+    action: str = "created"
+    memory: MemoryResponse | None = None
+
+
+JobStatusType = Literal["queued", "processing", "completed", "failed"]
+
+
+class IngestJobAcceptedResponse(BaseModel):
+    status: str = "accepted"
+    job_id: str
+    job_status: JobStatusType
+    status_url: str
+    created_at: str
+
+
+class IngestJobErrorResponse(BaseModel):
+    code: str
+    message: str
+    retryable: bool = False
+
+
+class IngestJobStatusResponse(BaseModel):
+    job_id: str
+    status: JobStatusType
+    created_at: str
+    started_at: str | None = None
+    completed_at: str | None = None
+    result: CreateMemoryResponse | None = None
+    error: IngestJobErrorResponse | None = None
+
+
+class GetMemoryResponse(BaseModel):
+    status: str = "success"
+    memory: MemoryResponse
+
+
+class GetMemoryViewResponse(BaseModel):
+    status: str = "success"
+    memory: dict[str, Any]
+    truncated_fields: list[str] = Field(default_factory=list)
+
+
+class GetMemoriesResponse(BaseModel):
+    status: str = "success"
+    count: int
+    memories: list[MemoryResponse]
+
+
+class UpdateMemoryResponse(BaseModel):
+    status: str = "success"
+    memory: MemoryResponse
+
+
+class DeleteMemoryResponse(BaseModel):
+    status: str = "success"
+    message: str
+
+
+class UnlinkMemoriesResponse(BaseModel):
+    status: str = "success"
+    message: str
+
+
+class BulkDeleteResponse(BaseModel):
+    status: str = "success"
+    deleted_count: int
+    memory_ids: list[str]
+
+
+class CountMemoriesResponse(BaseModel):
+    status: str = "success"
+    count: int
+    filters: dict[str, Any]
+
+
+class ListMemoriesResponse(BaseModel):
+    status: str = "success"
+    count: int
+    memories: list[MemoryResponse]
+    filters: dict[str, Any] = Field(default_factory=dict)
+
+
+class SearchMemoriesRequest(BaseModel):
+    query: str = Field(..., max_length=10_000)
+    k: int = Field(5, ge=1, le=100)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+
+    @field_validator("scope")
+    @classmethod
+    def _search_scope_patterns(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return value
+        for token in value:
+            validate_scope_pattern(token)
+        return value
+
+
+class SearchResponse(BaseModel):
+    status: str = "success"
+    count: int
+    scope: list[str] | None = None
+    results: list[dict[str, Any]]
+
+
+class ContextProfileRequest(BaseModel):
+    profile_id: str | None = None
+    memory_ids: list[str] = Field(default_factory=list)
+    custom_id: str | None = Field(None, max_length=512)
+    session_id: str | None = Field(None, max_length=512)
+    thread_id: str | None = Field(None, max_length=512)
+    source_id: str | None = Field(None, max_length=512)
+
+
+class ContextProfileResponse(BaseModel):
+    status: str = "success"
+    profile_id: str
+    memories: list[MemoryResponse] = Field(default_factory=list)
+    source: SourceIdentity = Field(default_factory=SourceIdentity)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AssembleContextRequest(BaseModel):
+    query: str = Field(..., min_length=1, max_length=10_000)
+    k: int = Field(
+        8,
+        ge=1,
+        le=100,
+        validation_alias=AliasChoices("k", "limit"),
+        description="Maximum search hits to consider when assembling context.",
+    )
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+    space_ref: str | None = Field(
+        None,
+        validation_alias=AliasChoices("space_ref", "space_id"),
+        description="Optional space UUID, slug, space.* token, or /spaces/space.* path.",
+    )
+    token_budget: int | None = Field(None, ge=50, le=50_000)
+    char_budget: int | None = Field(None, ge=200, le=200_000)
+    include_links: bool = True
+    include_breadcrumbs: bool = True
+
+    @field_validator("scope")
+    @classmethod
+    def _context_scope_patterns(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return value
+        for token in value:
+            validate_scope_pattern(token)
+        return value
+
+
+class AssembleContextResponse(BaseModel):
+    status: str = "success"
+    query: str
+    count: int
+    scope: list[str] | None = None
+    budget: dict[str, Any]
+    prompt_text: str
+    citations: list[dict[str, Any]]
+    items: list[dict[str, Any]]
+    truncated: dict[str, Any]
+
+
+class SpaceProfileResponse(BaseModel):
+    status: str = "success"
+    space: dict[str, Any]
+    profile: dict[str, Any]
+    prompt_text: str
+
+
+class CollectionProfileResponse(BaseModel):
+    status: str = "success"
+    collection_id: str
+    profile: dict[str, Any]
+    prompt_text: str
+
+
+class CreateRichNodeRequest(BaseModel):
+    content: str = Field(..., max_length=MAX_ADD_MEMORY_CONTENT)
+    type: Literal["text", "image", "document", "collection"] | None = None
+    node_type: Literal["text", "image", "document", "collection"] = Field(
+        "text",
+        deprecated=True,
+        description="Deprecated input alias for type.",
+    )
+    payload: dict[str, Any] = Field(default_factory=dict)
+    perception: str | None = Field(None, max_length=MAX_ADD_MEMORY_CONTENT)
+    encoding: str = "memory"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+    auto_link: bool = True
+    custom_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    session_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    thread_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    source_id: str | None = Field(None, max_length=MAX_EXTERNAL_ID_LEN)
+    source_url: str | None = Field(None, max_length=MAX_SOURCE_URL_LEN)
+
+    @field_validator("custom_id", "session_id", "thread_id", "source_id", "source_url", mode="before")
+    @classmethod
+    def _source_identity_strings(cls, value: Any) -> str | None:
+        return _clean_optional_string(value)
+
+    def memory_metadata(self) -> dict[str, Any]:
+        return merge_source_identity_metadata(
+            self.metadata,
+            custom_id=self.custom_id,
+            session_id=self.session_id,
+            thread_id=self.thread_id,
+            source_id=self.source_id,
+            source_url=self.source_url,
+        )
+
+
+class CreateCollectionRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=200)
+    summary: str = Field(..., min_length=1, max_length=MAX_ADD_MEMORY_CONTENT)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class CreatePlacementRequest(BaseModel):
+    child_id: str
+    name: str = Field(..., min_length=1, max_length=300)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    inherit_parent_scope: bool = True
+
+
+class PlacementResponse(BaseModel):
+    id: str
+    parent_id: str
+    child_id: str
+    name: str
+    scope: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    inherit_parent_scope: bool = True
+
+
+class CreateRichNodeResponse(BaseModel):
+    status: str = "success"
+    node: MemoryResponse
+
+
+class LinkRichNodeResponse(BaseModel):
+    status: str = "success"
+    memory_id: str
+    links_created: int
+    node: MemoryResponse
+
+
+class CreateNodeLinkRequest(BaseModel):
+    target_id: str | None = Field(
+        None,
+        description="Target memory id. Defaults to the source node, creating a self-loop alias.",
+    )
+    description: str = Field(..., min_length=1, max_length=10_000)
+
+
+class CreateNodeLinkResponse(BaseModel):
+    status: str = "success"
+    memory_id: str
+    link: dict[str, Any]
+    created: bool
+    node: MemoryResponse
+
+
+class CreateCollectionResponse(BaseModel):
+    status: str = "success"
+    collection: MemoryResponse
+
+
+class CreatePlacementResponse(BaseModel):
+    status: str = "success"
+    placement: PlacementResponse
+
+
+class CollectionMembersResponse(BaseModel):
+    status: str = "success"
+    collection_id: str
+    count: int
+    members: list[dict[str, Any]]
+
+
+class DocumentIngestResponse(BaseModel):
+    status: str = "success"
+    document_key: str
+    custom_id: str | None = None
+    session_id: str | None = None
+    thread_id: str | None = None
+    source_id: str | None = None
+    source_url: str | None = None
+    source_type: str
+    media_type: str
+    file_name: str
+    page_count: int = 0
+    unreadable_pages: list[int] = Field(default_factory=list)
+    image_count: int = 0
+    graph_image_count: int = 0
+    skipped_image_count: int = 0
+    image_ids: list[str] = Field(default_factory=list)
+    source_object: dict[str, Any] | None = None
+    chunk_count: int
+    chunk_ids: list[str]
+    collection: MemoryResponse
+    document: MemoryResponse
+    images: list[MemoryResponse] = Field(default_factory=list)
+    chunks: list[MemoryResponse]
+    placements: list[PlacementResponse]
+    semantic_links_created: int = 0
+
+
+class DocumentSourceResponse(BaseModel):
+    status: str = "success"
+    requested_node_id: str
+    document_id: str
+    document_key: str
+    file_name: str
+    content_type: str
+    size_bytes: int
+    sha256: str
+    source_object: dict[str, Any]
+    download_url: str | None = None
+    expires_in_seconds: int | None = None
+
+
+class GraphPathResponse(BaseModel):
+    status: str
+    path: list[str] | None = None
+    length: int | None = None
+    memories: list[dict[str, Any]] | None = None
+    message: str | None = None
+
+
+class GraphHubsResponse(BaseModel):
+    status: str = "success"
+    hubs: list[dict[str, Any]]
+    total_memories: int
+
+
+class GraphNeighborhoodResponse(BaseModel):
+    status: str = "success"
+    center_memory_id: str
+    hops: int
+    neighborhood: list[dict[str, Any]]
+    total_in_neighborhood: int
+
+
+class GraphTraversalResponse(BaseModel):
+    status: str = "success"
+    start_memory_id: str
+    query: str
+    max_hops: int
+    edge_similarity_threshold: float
+    scope: list[str] | None = None
+    memories: list[dict[str, Any]]
+    traversed_edges: list[dict[str, Any]]
+    total_memories: int
+    total_edges: int
+
+
+class GraphExportResponse(BaseModel):
+    status: str = "success"
+    graph: dict[str, Any]

memuron/domain/scope_filter.py

@@ -0,0 +1,104 @@
+"""Safe scope glob matching (no user-supplied regex)."""
+
+from __future__ import annotations
+
+import re
+from fnmatch import fnmatch
+
+from memuron.domain.limits import MAX_SCOPE_TOKEN_LEN
+
+_UNSAFE_SCOPE_PATTERN = re.compile(r"[\\[\]?+^$|()]")
+
+
+def validate_scope_pattern(pattern: str) -> str:
+    pattern = pattern.strip()
+    if not pattern:
+        raise ValueError("scope pattern must be non-empty")
+    if len(pattern) > MAX_SCOPE_TOKEN_LEN:
+        raise ValueError(
+            f"Each scope pattern must be at most {MAX_SCOPE_TOKEN_LEN} characters"
+        )
+    if _UNSAFE_SCOPE_PATTERN.search(pattern):
+        raise ValueError("scope patterns may only use * as a wildcard")
+    return pattern
+
+
+def normalize_scope_patterns(raw: list[str] | None) -> list[str]:
+    patterns = [part.strip() for part in (raw or []) if part.strip()]
+    return [validate_scope_pattern(pattern) for pattern in patterns]
+
+
+def parse_comma_scope(scope: str | None) -> list[str]:
+    patterns = [part.strip() for part in (scope or "").split(",") if part.strip()]
+    return [validate_scope_pattern(pattern) for pattern in patterns]
+
+
+def scope_token_matches_pattern(token: str, pattern: str) -> bool:
+    token = token.strip()
+    pattern = pattern.strip()
+    if "*" in pattern:
+        return fnmatch(token.lower(), pattern.lower())
+    return token.lower() == pattern.lower()
+
+
+def scope_matches_filter(scope: list[str], scope_filter: list[str] | None) -> bool:
+    """Match scope tokens against filter patterns.
+
+    - ``org:*`` and non-space patterns use AND (all must match).
+    - Multiple ``space.*`` patterns use OR (memory belongs to any listed space).
+    """
+    if not scope_filter:
+        return True
+    tokens = [token.strip() for token in scope if token.strip()]
+    org_patterns = [p for p in scope_filter if str(p).startswith("org:")]
+    space_patterns = [p for p in scope_filter if str(p).startswith("space.")]
+    other_patterns = [
+        p
+        for p in scope_filter
+        if p not in org_patterns and p not in space_patterns
+    ]
+
+    for pattern in org_patterns + other_patterns:
+        if not any(scope_token_matches_pattern(token, pattern) for token in tokens):
+            return False
+    if space_patterns:
+        if not any(
+            any(scope_token_matches_pattern(token, pattern) for token in tokens)
+            for pattern in space_patterns
+        ):
+            return False
+    return True
+
+
+def scope_sql_clause(column: str, pattern: str) -> tuple[str, str]:
+    validate_scope_pattern(pattern)
+    if "*" not in pattern:
+        return (
+            f"EXISTS (SELECT 1 FROM jsonb_array_elements_text({column}::jsonb) AS t "
+            "WHERE lower(t) = lower(?))",
+            pattern,
+        )
+    like = (
+        pattern.replace("\\", "\\\\")
+        .replace("%", "\\%")
+        .replace("_", "\\_")
+        .replace("*", "%")
+    )
+    return (
+        f"EXISTS (SELECT 1 FROM jsonb_array_elements_text({column}::jsonb) AS t "
+        "WHERE t ILIKE ? ESCAPE E'\\\\')",
+        like,
+    )
+
+
+def scope_sql_clauses(column: str, scope: list[str] | None) -> tuple[str, list[str]]:
+    patterns = normalize_scope_patterns(scope)
+    if not patterns:
+        return "", []
+    parts: list[str] = []
+    params: list[str] = []
+    for pattern in patterns:
+        clause, param = scope_sql_clause(column, pattern)
+        parts.append(clause)
+        params.append(param)
+    return " AND ".join(parts), params

memuron/graphfs/__init__.py

@@ -0,0 +1 @@
+"""Graph-filesystem query language, manual, projections, and read model."""