memuron 0.1.1__py3-none-any.whl

memuron/actions/spaces_documents.py

@@ -0,0 +1,720 @@
+"""Document ingest and space actions."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from time import perf_counter
+from typing import Any
+
+from artha_engine import ActionContext, ArthaEngine, HttpExposure
+from fastapi import UploadFile
+from pydantic import BaseModel, Field, field_validator
+
+from memuron.actions.helpers import (
+    event_metadata,
+    merge_tenant_scope,
+    parse_metadata_form,
+    parse_scope_form,
+    require_memory_in_tenant,
+    require_user_org,
+)
+from memuron.actions.registry import actions
+from memuron.application.config import settings
+from memuron.context import space_profile
+from memuron.documents.linking import link_document_after_ingest
+from memuron.documents.parser import DocumentParseError
+from memuron.documents.url_ingest import UrlIngestError, fetch_url_source
+from memuron.graphfs.manual import filesystem_manual, manual_topics
+from memuron.graphfs.query import FsQueryError, run_fs_query
+from memuron.persistence.identity_store import IdentityStore
+from memuron.memory.recipes import (
+    document_source_payload,
+    get_memory,
+    ingest_document_source,
+    link_memory_with_guardian,
+)
+from memuron.domain.schemas import (
+    DocumentIngestResponse,
+    DocumentSourceResponse,
+    MemoryResponse,
+    SpaceProfileResponse,
+    merge_source_identity_metadata,
+)
+from memuron.domain.limits import MAX_SCOPE_ITEMS, MAX_SCOPE_TOKEN_LEN
+from memuron.spaces.service import (
+    guardian_space_context,
+    resolve_ingest_hint_space,
+    resolve_space_reference,
+)
+from memuron.security.tenant import merge_space_scope
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentIngestInput(BaseModel):
+    model_config = {"arbitrary_types_allowed": True}
+
+    file: UploadFile
+    scope: str | None = None
+    metadata: str | 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
+
+
+class DocumentUrlIngestInput(BaseModel):
+    url: str = Field(..., min_length=1, max_length=4096)
+    scope: list[str] | None = Field(None, max_length=MAX_SCOPE_ITEMS)
+    space_ref: str | None = Field(None, max_length=500)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    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("scope")
+    @classmethod
+    def _scope_token_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 CreateSpaceInput(BaseModel):
+    name: str = Field(..., min_length=1, max_length=120)
+    slug: str | None = Field(None, max_length=64)
+    description: str = Field("", max_length=500)
+    guardian_prompt: str = Field("", max_length=4000)
+    is_default: bool = False
+
+
+class UpdateSpaceInput(BaseModel):
+    name: str | None = Field(None, min_length=1, max_length=120)
+    description: str | None = Field(None, max_length=500)
+    guardian_prompt: str | None = Field(None, max_length=4000)
+
+
+class SetSpaceEnabledInput(BaseModel):
+    enabled: bool
+
+
+class SpaceQueryInput(BaseModel):
+    query: str = Field(..., min_length=1, max_length=10_000)
+    cwd: str = Field("/spaces", min_length=1, max_length=500)
+
+
+class SpaceResponse(BaseModel):
+    id: str
+    slug: str
+    name: str
+    token: str
+    description: str
+    guardian_prompt: str
+    is_default: bool
+    is_enabled: bool = False
+
+
+class SpaceListResponse(BaseModel):
+    spaces: list[SpaceResponse]
+    count: int
+    enabled_count: int
+
+
+class SpaceQueryResponse(BaseModel):
+    kind: str
+    protocol: str = "memuron.graph-filesystem.v1"
+    query: str
+    cwd: str
+    navigation: dict[str, Any] | None = None
+    manual: dict[str, Any] | None = None
+    items: list[dict[str, Any]]
+    count: int
+    trace: list[dict[str, Any]]
+    ast: list[dict[str, Any]]
+
+
+def _space_response(space: dict[str, object]) -> SpaceResponse:
+    return SpaceResponse(
+        id=str(space["id"]),
+        slug=str(space["slug"]),
+        name=str(space["name"]),
+        token=str(space["token"]),
+        description=str(space["description"]),
+        guardian_prompt=str(space["guardian_prompt"]),
+        is_default=bool(space["is_default"]),
+        is_enabled=bool(space.get("is_enabled", False)),
+    )
+
+
+async def _run_document_semantic_linking(
+    *,
+    payload: dict[str, Any],
+    engine: ArthaEngine,
+    context: ActionContext,
+    guardian: object,
+    identity: IdentityStore,
+    scoped: list[str],
+    meta: dict[str, object],
+    image_attachments: list[dict[str, Any]],
+) -> int:
+    semantic_links_created = 0
+    if payload.get("source_type") == "image":
+        document = payload.get("document") or {}
+        link_text = str(document.get("perception") or document.get("content") or "").strip()
+        if link_text and guardian is not None and settings.openrouter_api_key:
+            space_context = None
+            org_id = context.auth.tenant_id
+            user_id = str(context.auth.actor_id)
+            if org_id:
+                hint_space = resolve_ingest_hint_space(
+                    identity,
+                    user_id=user_id,
+                    org_id=str(org_id),
+                    space_id=None,
+                )
+                space_context = guardian_space_context(
+                    identity,
+                    user_id=user_id,
+                    org_id=str(org_id),
+                    hint_space=hint_space,
+                    space_mode="assist",
+                )
+            try:
+                semantic_links_created = await link_memory_with_guardian(
+                    engine,
+                    guardian,
+                    memory_id=str(document["id"]),
+                    content=link_text,
+                    scope=scoped,
+                    event_metadata=meta,
+                    space_context=space_context,
+                )
+                payload["document"] = get_memory(engine, str(document["id"]))
+            except Exception as exc:
+                logger.warning("Image ingest auto-link failed: %s", exc)
+    else:
+        try:
+            semantic_links_created = await link_document_after_ingest(
+                engine,
+                ingest_payload=payload,
+                scope=scoped,
+                event_metadata=meta,
+                image_attachments=image_attachments,
+            )
+        except Exception as exc:
+            logger.warning("Document ingest semantic linking failed: %s", exc)
+    return semantic_links_created
+
+
+@actions.action(
+    name="document.ingest",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/documents/ingest"),
+    multipart=True,
+    mcp=False,
+    cli=False,
+    inject={"guardian": "guardian", "identity": "identity"},
+    tags=["documents"],
+)
+async def document_ingest(
+    input: DocumentIngestInput,
+    engine: ArthaEngine,
+    context: ActionContext,
+    guardian: object,
+    identity: IdentityStore,
+) -> DocumentIngestResponse:
+    file_bytes = await input.file.read()
+    scoped = merge_tenant_scope(parse_scope_form(input.scope), context)
+    parsed_metadata = merge_source_identity_metadata(
+        parse_metadata_form(input.metadata),
+        custom_id=input.custom_id,
+        session_id=input.session_id,
+        thread_id=input.thread_id,
+        source_id=input.source_id,
+        source_url=input.source_url,
+    )
+    meta = event_metadata(context)
+    try:
+        payload = await asyncio.to_thread(
+            ingest_document_source,
+            engine,
+            file_name=input.file.filename or "document",
+            content_type=input.file.content_type,
+            file_bytes=file_bytes,
+            scope=scoped,
+            metadata=parsed_metadata,
+            event_metadata=meta,
+        )
+    except DocumentParseError as exc:
+        raise ValueError(str(exc)) from exc
+
+    image_attachments = payload.pop("image_attachments", [])
+    semantic_links_created = await _run_document_semantic_linking(
+        payload=payload,
+        engine=engine,
+        context=context,
+        guardian=guardian,
+        identity=identity,
+        scoped=scoped,
+        meta=meta,
+        image_attachments=image_attachments,
+    )
+
+    payload["semantic_links_created"] = semantic_links_created
+    return DocumentIngestResponse.model_validate(payload)
+
+
+@actions.action(
+    name="document.ingest_url",
+    description="Fetch a URL, extract readable content, and ingest it as a Memuron document graph.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/documents/ingest-url"),
+    mcp=False,
+    cli=False,
+    inject={"guardian": "guardian", "identity": "identity"},
+    tags=["documents"],
+)
+async def document_ingest_url(
+    input: DocumentUrlIngestInput,
+    engine: ArthaEngine,
+    context: ActionContext,
+    guardian: object,
+    identity: IdentityStore,
+) -> DocumentIngestResponse:
+    user_id, org_id = require_user_org(context.auth)
+    scoped = merge_tenant_scope(input.scope, context)
+    if input.space_ref:
+        space = resolve_ingest_hint_space(
+            identity,
+            user_id=user_id,
+            org_id=org_id,
+            space_id=input.space_ref,
+        )
+        scoped = merge_space_scope(
+            scoped,
+            org_id=org_id,
+            space_token=str(space["token"]),
+        )
+
+    parsed_metadata = merge_source_identity_metadata(
+        dict(input.metadata or {}),
+        custom_id=input.custom_id,
+        session_id=input.session_id,
+        thread_id=input.thread_id,
+        source_id=input.source_id,
+        source_url=input.source_url or input.url,
+    )
+
+    try:
+        fetched = await asyncio.to_thread(fetch_url_source, input.url)
+    except UrlIngestError as exc:
+        raise ValueError(str(exc)) from exc
+
+    source_metadata = {
+        "url_ingest": True,
+        **fetched.metadata,
+    }
+    meta = {
+        **event_metadata(context),
+        "url_ingest": True,
+        "source_url": fetched.metadata.get("source_url") or input.url,
+        "fetched_url": fetched.metadata.get("fetched_url") or input.url,
+    }
+    try:
+        payload = await asyncio.to_thread(
+            ingest_document_source,
+            engine,
+            file_name=fetched.file_name,
+            content_type=fetched.content_type,
+            file_bytes=fetched.file_bytes,
+            scope=scoped,
+            metadata={
+                **parsed_metadata,
+                "url": source_metadata,
+            },
+            source_metadata=source_metadata,
+            event_metadata=meta,
+        )
+    except DocumentParseError as exc:
+        raise ValueError(str(exc)) from exc
+
+    image_attachments = payload.pop("image_attachments", [])
+    semantic_links_created = await _run_document_semantic_linking(
+        payload=payload,
+        engine=engine,
+        context=context,
+        guardian=guardian,
+        identity=identity,
+        scoped=scoped,
+        meta=meta,
+        image_attachments=image_attachments,
+    )
+    payload["semantic_links_created"] = semantic_links_created
+    return DocumentIngestResponse.model_validate(payload)
+
+
+@actions.action(
+    name="document.source",
+    description=(
+        "Resolve a document, chunk, image, or document collection node to the original "
+        "uploaded source object and a short-lived download URL."
+    ),
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/documents/{node_id}/source"),
+    mcp="memuron_document_source",
+    cli="document source",
+    tags=["documents"],
+)
+def document_source(
+    node_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> DocumentSourceResponse:
+    require_memory_in_tenant(engine, node_id, context)
+    payload = document_source_payload(engine, node_id)
+    require_memory_in_tenant(engine, str(payload["document_id"]), context)
+    return DocumentSourceResponse.model_validate(payload)
+
+
+@actions.action(
+    name="space.list",
+    description="List every space available to the active user and organization, including IDs, tokens, defaults, and enabled state.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/spaces"),
+    mcp="memuron_list_spaces",
+    cli="space list",
+    inject={"identity": "identity"},
+    tags=["spaces"],
+)
+def space_list(context: ActionContext, identity: IdentityStore) -> SpaceListResponse:
+    user_id, org_id = require_user_org(context.auth)
+    spaces = identity.list_user_org_spaces(user_id, org_id)
+    items = [_space_response(space) for space in spaces]
+    enabled_count = sum(1 for item in items if item.is_enabled)
+    return SpaceListResponse(spaces=items, count=len(items), enabled_count=enabled_count)
+
+
+@actions.action(
+    name="space.query_manual",
+    description="Read the Memuron graph-filesystem manual. Call this first when learning query commands or recovering from a query error.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/spaces/query/manual"),
+    mcp="memuron_help",
+    cli="space manual",
+    tags=["spaces"],
+)
+def space_query_manual(context: ActionContext, topic: str = "overview") -> dict[str, Any]:
+    require_user_org(context.auth)
+    try:
+        manual = filesystem_manual(topic)
+    except KeyError as exc:
+        raise KeyError(
+            f"Unknown manual topic: {topic}. Topics: {', '.join(manual_topics())}"
+        ) from exc
+    return {
+        "protocol": "memuron.graph-filesystem.v1",
+        "endpoint": {
+            "method": "POST",
+            "path": "/memuron/spaces/query",
+            "body": {"cwd": "/spaces/space.personal", "query": "ls"},
+        },
+        "topics": manual_topics(),
+        "manual": manual,
+    }
+
+
+@actions.action(
+    name="space.query",
+    description="Run a filesystem-style Memuron query or pipeline inside a space. Supports navigation, regex rg, semantic search, graph traversal, neighborhoods, paths, and related-memory discovery.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("POST", "/memuron/spaces/query"),
+    mcp="memuron_query",
+    cli="query",
+    inject={"identity": "identity"},
+    tags=["spaces"],
+)
+def space_query(
+    input: SpaceQueryInput,
+    engine: ArthaEngine,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceQueryResponse:
+    user_id, org_id = require_user_org(context.auth)
+    spaces = identity.list_user_org_spaces(user_id, org_id)
+    try:
+        result = run_fs_query(
+            engine,
+            query=input.query,
+            cwd=input.cwd,
+            spaces=spaces,
+            org_id=org_id,
+        )
+    except FsQueryError as exc:
+        raise ValueError(exc.detail(query=input.query, cwd=input.cwd)) from exc
+    return SpaceQueryResponse.model_validate(result)
+
+
+@actions.action(
+    name="space.profile",
+    description=(
+        "Return a lightweight deterministic profile for one space, including "
+        "counts, collections, previews, and a prompt-ready block."
+    ),
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/spaces/{space_id}/profile"),
+    mcp=False,
+    cli=False,
+    inject={"identity": "identity"},
+    tags=["spaces"],
+)
+def space_profile_action(
+    space_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceProfileResponse:
+    user_id, org_id = require_user_org(context.auth)
+    space = resolve_space_reference(identity, org_id=org_id, space_ref=space_id)
+    if space is None:
+        raise KeyError("Space not found")
+    enabled = False
+    for candidate in identity.list_user_org_spaces(user_id, org_id):
+        if candidate["id"] == space["id"]:
+            space = candidate
+            enabled = bool(candidate.get("is_enabled"))
+            break
+    payload = space_profile(engine, space=space, org_id=org_id)
+    return SpaceProfileResponse.model_validate(
+        {
+            "space": {**space, "is_enabled": enabled},
+            "profile": payload["profile"],
+            "prompt_text": payload["prompt_text"],
+        }
+    )
+
+
+@actions.action(
+    name="space.create",
+    description="Create a space in the active organization and optionally make it the organization default.",
+    kind="write",
+    scopes=["space:admin"],
+    http=HttpExposure("POST", "/memuron/spaces"),
+    mcp="memuron_create_space",
+    cli="space create",
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_create(
+    input: CreateSpaceInput,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceResponse:
+    user_id, org_id = require_user_org(context.auth)
+    identity.ensure_org_spaces(org_id, user_id)
+    space = identity.create_space(
+        org_id=org_id,
+        name=input.name,
+        slug=input.slug,
+        description=input.description,
+        guardian_prompt=input.guardian_prompt,
+        is_default=input.is_default,
+    )
+    identity.seed_space_pref_for_user(
+        user_id,
+        space["id"],
+        enabled=bool(input.is_default),
+    )
+    enabled = bool(input.is_default)
+    if not enabled:
+        for member in identity.list_user_org_spaces(user_id, org_id):
+            if member["id"] == space["id"]:
+                enabled = bool(member.get("is_enabled"))
+                break
+    return _space_response({**space, "is_enabled": enabled})
+
+
+@actions.action(
+    name="space.update",
+    description="Update a space by UUID, slug, token such as space.work, or path such as /spaces/space.work.",
+    kind="write",
+    scopes=["space:admin"],
+    http=HttpExposure("PATCH", "/memuron/spaces/{space_id}"),
+    mcp=False,
+    cli="space update",
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_update(
+    space_id: str,
+    input: UpdateSpaceInput,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceResponse:
+    user_id, org_id = require_user_org(context.auth)
+    existing = resolve_space_reference(identity, org_id=org_id, space_ref=space_id)
+    if existing is None:
+        raise KeyError("Space not found")
+    resolved_id = str(existing["id"])
+    identity.update_space(
+        resolved_id,
+        name=input.name,
+        description=input.description,
+        guardian_prompt=input.guardian_prompt,
+    )
+    for member in identity.list_user_org_spaces(user_id, org_id):
+        if member["id"] == resolved_id:
+            return _space_response(member)
+    updated = identity.get_space_by_id(resolved_id)
+    if updated is None:
+        raise KeyError("Space not found")
+    return _space_response({**updated, "is_enabled": False})
+
+
+@actions.action(
+    name="space.update_mcp",
+    description="Update a space by UUID, slug, space.* token, or /spaces path using flat editable fields.",
+    kind="write",
+    scopes=["space:admin"],
+    mcp="memuron_update_space",
+    cli=False,
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_update_mcp(
+    space_ref: str,
+    context: ActionContext,
+    identity: IdentityStore,
+    name: str | None = None,
+    description: str | None = None,
+    guardian_prompt: str | None = None,
+) -> SpaceResponse:
+    return space_update(
+        space_ref,
+        UpdateSpaceInput(
+            name=name,
+            description=description,
+            guardian_prompt=guardian_prompt,
+        ),
+        context,
+        identity,
+    )
+
+
+@actions.action(
+    name="space.set_default",
+    description="Make a space the organization default using its UUID, slug, token, or /spaces path.",
+    kind="write",
+    scopes=["space:admin"],
+    http=HttpExposure("POST", "/memuron/spaces/{space_id}/set-default"),
+    mcp=False,
+    cli="space set-default",
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_set_default(
+    space_id: str,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceResponse:
+    user_id, org_id = require_user_org(context.auth)
+    space = resolve_space_reference(identity, org_id=org_id, space_ref=space_id)
+    if space is None:
+        raise KeyError("Space not found")
+    resolved_id = str(space["id"])
+    identity.set_default_space(org_id, resolved_id)
+    for member in identity.list_user_org_spaces(user_id, org_id):
+        if member["id"] == resolved_id:
+            return _space_response(member)
+    raise KeyError("Space not found")
+
+
+@actions.action(
+    name="space.set_default_mcp",
+    description="Make a space the organization default using its UUID, slug, space.* token, or /spaces path.",
+    kind="write",
+    scopes=["space:admin"],
+    mcp="memuron_set_default_space",
+    cli=False,
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_set_default_mcp(
+    space_ref: str,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceResponse:
+    return space_set_default(space_ref, context, identity)
+
+
+@actions.action(
+    name="space.set_enabled",
+    description="Enable or disable a space by UUID, slug, token, or /spaces path without deleting it.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/spaces/{space_id}/set-enabled"),
+    mcp=False,
+    cli="space set-enabled",
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_set_enabled(
+    space_id: str,
+    input: SetSpaceEnabledInput,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceResponse:
+    user_id, org_id = require_user_org(context.auth)
+    space = resolve_space_reference(identity, org_id=org_id, space_ref=space_id)
+    if space is None:
+        raise KeyError("Space not found")
+    resolved_id = str(space["id"])
+    identity.set_space_enabled(
+        user_id,
+        org_id,
+        resolved_id,
+        enabled=input.enabled,
+    )
+    for member in identity.list_user_org_spaces(user_id, org_id):
+        if member["id"] == resolved_id:
+            return _space_response(member)
+    raise KeyError("Space not found")
+
+
+@actions.action(
+    name="space.set_enabled_mcp",
+    description="Enable or disable a space by UUID, slug, space.* token, or /spaces path.",
+    kind="write",
+    scopes=["memory:write"],
+    mcp="memuron_set_space_enabled",
+    cli=False,
+    tags=["spaces"],
+    inject={"identity": "identity"},
+)
+def space_set_enabled_mcp(
+    space_ref: str,
+    enabled: bool,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> SpaceResponse:
+    return space_set_enabled(
+        space_ref,
+        SetSpaceEnabledInput(enabled=enabled),
+        context,
+        identity,
+    )