memuron 0.1.1__py3-none-any.whl

memuron/actions/memory_write.py

@@ -0,0 +1,290 @@
+"""Memory write/delete and ingest job actions."""
+
+from __future__ import annotations
+
+from artha_engine import ActionContext, ArthaEngine, HttpExposure
+
+from memuron.actions.helpers import (
+    event_metadata,
+    merge_tenant_scope,
+    require_memory_in_tenant,
+    require_user_org,
+)
+from memuron.actions.registry import actions
+from memuron.application.config import settings
+from memuron.persistence.identity_store import IdentityStore
+from memuron.ingest.jobs import build_job_payload
+from memuron.memory.recipes import (
+    bulk_delete_memories,
+    delete_memory,
+    unlink_memories,
+    update_memory,
+)
+from memuron.domain.schemas import (
+    AddMemoryRequest,
+    BulkDeleteRequest,
+    BulkDeleteResponse,
+    CreateMemoryResponse,
+    DeleteMemoryResponse,
+    IngestJobAcceptedResponse,
+    IngestJobErrorResponse,
+    IngestJobStatusResponse,
+    MemoryResponse,
+    UnlinkMemoriesRequest,
+    UnlinkMemoriesResponse,
+    UpdateMemoryRequest,
+    UpdateMemoryResponse,
+)
+from memuron.spaces.service import guardian_space_context, resolve_ingest_hint_space
+from memuron.security.tenant import merge_org_scope, merge_space_scope
+
+
+@actions.action(
+    name="memory.ingest",
+    description="Queue a memory for Guardian ingest into the active organization and optional space. Poll the returned job ID with memuron_job_status.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/memories", status_code=202),
+    mcp="memuron_ingest",
+    cli="memory ingest",
+    inject={"identity": "identity", "jobs": "jobs"},
+    tags=["memory"],
+)
+def memory_ingest(
+    input: AddMemoryRequest,
+    context: ActionContext,
+    identity: IdentityStore,
+    jobs: object,
+) -> IngestJobAcceptedResponse:
+    if jobs is None:
+        raise RuntimeError("Ingest job store is unavailable (PostgreSQL required)")
+    user_id, org_id = require_user_org(context.auth)
+    space = None
+    space_context = None
+    candidate_scope = None
+    explicit_space_pick = input.space_ref is not None
+    space = resolve_ingest_hint_space(
+        identity,
+        user_id=user_id,
+        org_id=org_id,
+        space_id=input.space_ref,
+    )
+    space_mode = "strict" if explicit_space_pick else "assist"
+    space_context = guardian_space_context(
+        identity,
+        user_id=user_id,
+        org_id=org_id,
+        hint_space=space,
+        space_mode=space_mode,
+    )
+    candidate_scope = merge_org_scope(None, org_id)
+    if space_mode == "strict" and space:
+        candidate_scope = merge_space_scope(
+            candidate_scope,
+            org_id=org_id,
+            space_token=str(space["token"]),
+        )
+    ingest_scope = merge_org_scope(input.scope, org_id)
+    if explicit_space_pick and space:
+        ingest_scope = merge_space_scope(
+            ingest_scope,
+            org_id=org_id,
+            space_token=str(space["token"]),
+        )
+    payload = build_job_payload(
+        input.content,
+        ingest_scope,
+        metadata=input.memory_metadata(),
+        event_metadata=event_metadata(context, space_context=space_context),
+        space_context=space_context,
+        candidate_scope=candidate_scope,
+    )
+    job = jobs.create_job(payload, max_attempts=settings.ingest_job_max_attempts)  # type: ignore[union-attr]
+    return IngestJobAcceptedResponse(
+        job_id=job["id"],
+        job_status=job["status"],
+        status_url=f"/memuron/jobs/{job['id']}",
+        created_at=job["created_at"],
+    )
+
+
+@actions.action(
+    name="memory.job_status",
+    description="Poll an ingest job created by memuron_ingest. Returns queued, processing, completed, or failed state.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/jobs/{job_id}"),
+    mcp="memuron_job_status",
+    cli="memory job-status",
+    tags=["memory"],
+    inject={"jobs": "jobs"},
+)
+def memory_job_status(
+    job_id: str,
+    context: ActionContext,
+    jobs: object,
+) -> IngestJobStatusResponse:
+    if jobs is None:
+        raise RuntimeError("Ingest job store is unavailable (PostgreSQL required)")
+    job = jobs.get_job(job_id)  # type: ignore[union-attr]
+    if job is None:
+        raise KeyError("Job not found")
+    payload = job.get("payload_json") or {}
+    tenant_id = (payload.get("event_metadata") or {}).get("tenant_id")
+    if tenant_id != context.auth.tenant_id:
+        raise KeyError("Job not found")
+    result = None
+    if job.get("result_json"):
+        result = CreateMemoryResponse.model_validate(job["result_json"])
+    error = None
+    if job.get("error_json"):
+        error = IngestJobErrorResponse.model_validate(job["error_json"])
+    return IngestJobStatusResponse(
+        job_id=job["id"],
+        status=job["status"],
+        created_at=job["created_at"],
+        started_at=job.get("started_at"),
+        completed_at=job.get("completed_at"),
+        result=result,
+        error=error,
+    )
+
+
+@actions.action(
+    name="memory.update",
+    description="Update the content or scope of a known memory in the active organization.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("PUT", "/memuron/memories/{memory_id}"),
+    mcp=False,
+    cli="memory update",
+    tags=["memory"],
+)
+def memory_update(
+    memory_id: str,
+    input: UpdateMemoryRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> UpdateMemoryResponse:
+    require_memory_in_tenant(engine, memory_id, context)
+    if input.content is None and input.scope is None:
+        raise ValueError("Provide content and/or scope to update")
+    memory = update_memory(
+        engine,
+        memory_id,
+        content=input.content,
+        scope=merge_tenant_scope(input.scope, context) if input.scope is not None else None,
+        event_metadata=event_metadata(context),
+    )
+    return UpdateMemoryResponse(memory=MemoryResponse.model_validate(memory))
+
+
+@actions.action(
+    name="memory.update_mcp",
+    description="Update a known memory with flat content and scope arguments. Provide at least one field.",
+    kind="write",
+    scopes=["memory:write"],
+    mcp="memuron_update",
+    cli=False,
+    tags=["memory"],
+)
+def memory_update_mcp(
+    memory_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+    content: str | None = None,
+    scope: list[str] | None = None,
+) -> UpdateMemoryResponse:
+    require_memory_in_tenant(engine, memory_id, context)
+    if content is None and scope is None:
+        raise ValueError("Provide content and/or scope to update")
+    memory = update_memory(
+        engine,
+        memory_id,
+        content=content,
+        scope=merge_tenant_scope(scope, context) if scope is not None else None,
+        event_metadata=event_metadata(context),
+    )
+    return UpdateMemoryResponse(memory=MemoryResponse.model_validate(memory))
+
+
+@actions.action(
+    name="memory.delete",
+    description="Permanently delete one known memory from the active organization. Use only when the user clearly requested deletion.",
+    kind="destructive",
+    scopes=["memory:delete"],
+    http=HttpExposure("DELETE", "/memuron/memories/{memory_id}"),
+    mcp="memuron_delete",
+    cli="memory delete",
+    tags=["memory"],
+)
+def memory_delete(
+    memory_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+    confirm: bool = False,
+) -> DeleteMemoryResponse:
+    if context.transport == "mcp" and not confirm:
+        raise ValueError("confirm must be true to delete a memory through MCP")
+    require_memory_in_tenant(engine, memory_id, context)
+    deleted = delete_memory(engine, memory_id, event_metadata=event_metadata(context))
+    if not deleted:
+        raise KeyError(f"Memory not found: {memory_id}")
+    return DeleteMemoryResponse(message=f"Memory {memory_id} deleted")
+
+
+@actions.action(
+    name="memory.bulk_delete",
+    description="Permanently delete memories matching a scope filter after explicit confirmation.",
+    kind="destructive",
+    scopes=["memory:delete"],
+    http=HttpExposure("POST", "/memuron/memories/bulk-delete"),
+    mcp=False,
+    cli="memory bulk-delete",
+    tags=["memory"],
+)
+def memory_bulk_delete(
+    input: BulkDeleteRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> BulkDeleteResponse:
+    deleted_count, memory_ids = bulk_delete_memories(
+        engine,
+        scope=tenant_scope_query(context, input.scope) or input.scope,
+        event_metadata=event_metadata(context),
+    )
+    return BulkDeleteResponse(deleted_count=deleted_count, memory_ids=memory_ids)
+
+
+@actions.action(
+    name="memory.unlink",
+    description="Remove semantic links between two known memories in the active organization.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/memories/unlink"),
+    mcp=False,
+    cli="memory unlink",
+    tags=["memory"],
+)
+def memory_unlink(
+    input: UnlinkMemoriesRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> UnlinkMemoriesResponse:
+    require_memory_in_tenant(engine, input.memory_id_1, context)
+    require_memory_in_tenant(engine, input.memory_id_2, context)
+    removed = unlink_memories(
+        engine,
+        input.memory_id_1,
+        input.memory_id_2,
+        event_metadata=event_metadata(context),
+    )
+    return UnlinkMemoriesResponse(
+        message=f"Removed {removed} link(s) between {input.memory_id_1} and {input.memory_id_2}"
+    )
+
+
+def tenant_scope_query(context: ActionContext, scope: str) -> str | None:
+    from memuron.actions.helpers import tenant_scope_query as _query
+
+    return _query(context, scope)

memuron/actions/nodes.py

@@ -0,0 +1,340 @@
+"""Rich node and collection actions."""
+
+from __future__ import annotations
+
+import logging
+
+from artha_engine import ActionContext, ArthaEngine, HttpExposure
+
+from memuron.actions.helpers import (
+    event_metadata,
+    merge_tenant_scope,
+    require_memory_in_tenant,
+)
+from memuron.actions.registry import actions
+from memuron.application.config import settings
+from memuron.context import collection_profile
+from memuron.persistence.identity_store import IdentityStore
+from memuron.memory.recipes import (
+    collection_members,
+    create_collection,
+    create_memory_link,
+    create_rich_node,
+    get_memory,
+    link_memory_with_guardian,
+    place_node_in_collection,
+)
+from memuron.domain.schemas import (
+    CollectionMembersResponse,
+    CollectionProfileResponse,
+    CreateCollectionRequest,
+    CreateNodeLinkRequest,
+    CreateNodeLinkResponse,
+    CreateCollectionResponse,
+    CreatePlacementRequest,
+    CreatePlacementResponse,
+    CreateRichNodeRequest,
+    CreateRichNodeResponse,
+    LinkRichNodeResponse,
+    MemoryResponse,
+    PlacementResponse,
+)
+from memuron.spaces.service import guardian_space_context, resolve_ingest_hint_space
+from memuron.security.tenant import merge_org_scope
+
+logger = logging.getLogger(__name__)
+
+
+@actions.action(
+    name="node.create",
+    description="Create a typed rich memory node in the active organization.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/nodes"),
+    mcp=False,
+    cli="node create",
+    tags=["nodes"],
+    inject={"guardian": "guardian", "identity": "identity"},
+)
+async def node_create(
+    input: CreateRichNodeRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+    guardian: object,
+    identity: IdentityStore,
+) -> CreateRichNodeResponse:
+    meta = event_metadata(context)
+    scoped = merge_tenant_scope(input.scope, context)
+    space_context = None
+    candidate_scope = None
+    org_id = context.auth.tenant_id
+    user_id = str(context.auth.actor_id)
+    if org_id:
+        candidate_scope = merge_org_scope(None, str(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",
+        )
+    requested_type = input.type or str(input.model_dump()["node_type"])
+    node = create_rich_node(
+        engine,
+        content=input.content,
+        node_type=requested_type,
+        payload=input.payload,
+        perception=input.perception,
+        encoding=input.encoding,
+        metadata=input.memory_metadata(),
+        scope=scoped,
+        event_metadata=meta,
+    )
+    if input.auto_link and requested_type not in {"collection"}:
+        link_text = (input.perception or input.content).strip()
+        if link_text and guardian is not None:
+            try:
+                linked = await link_memory_with_guardian(
+                    engine,
+                    guardian,
+                    memory_id=str(node["id"]),
+                    content=link_text,
+                    scope=scoped,
+                    event_metadata=meta,
+                    space_context=space_context,
+                    candidate_scope=candidate_scope,
+                )
+                node = get_memory(engine, str(node["id"]))
+                node["metadata"] = {
+                    **(node.get("metadata") or {}),
+                    "auto_link_count": linked,
+                }
+            except Exception as exc:
+                logger.warning("Rich node auto-link failed for %s: %s", node["id"], exc)
+    return CreateRichNodeResponse(node=MemoryResponse.model_validate(node))
+
+
+@actions.action(
+    name="node.link",
+    description="Ask Guardian to create semantic links for a known memory in the active organization.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/nodes/{memory_id}/link"),
+    mcp=False,
+    cli="node link",
+    tags=["nodes"],
+    inject={"guardian": "guardian", "identity": "identity"},
+)
+async def node_link(
+    memory_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+    guardian: object,
+    identity: IdentityStore,
+) -> LinkRichNodeResponse:
+    if guardian is None:
+        raise RuntimeError("Guardian not available")
+    meta = event_metadata(context)
+    memory = require_memory_in_tenant(engine, memory_id, context)
+    if memory.get("node_type") == "collection":
+        raise ValueError("collection nodes use placements, not semantic links")
+    scoped = list(memory.get("scope") or [])
+    scoped = merge_tenant_scope(scoped, context)
+    link_text = (memory.get("perception") or memory.get("content") or "").strip()
+    if not link_text:
+        raise ValueError("memory has no perception/content to link on")
+    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",
+        )
+    linked = await link_memory_with_guardian(
+        engine,
+        guardian,
+        memory_id=memory_id,
+        content=link_text,
+        scope=scoped,
+        event_metadata=meta,
+        space_context=space_context,
+    )
+    refreshed = get_memory(engine, memory_id)
+    refreshed["metadata"] = {
+        **(refreshed.get("metadata") or {}),
+        "auto_link_count": linked,
+    }
+    return LinkRichNodeResponse(
+        memory_id=memory_id,
+        links_created=linked,
+        node=MemoryResponse.model_validate(refreshed),
+    )
+
+
+@actions.action(
+    name="node.create_link",
+    description="Create an explicit semantic link or self-loop alias for a known memory.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/nodes/{memory_id}/links"),
+    mcp=False,
+    cli="node create-link",
+    tags=["nodes"],
+)
+def node_create_link(
+    memory_id: str,
+    input: CreateNodeLinkRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> CreateNodeLinkResponse:
+    meta = event_metadata(context)
+    target_id = input.target_id or memory_id
+    require_memory_in_tenant(engine, memory_id, context)
+    require_memory_in_tenant(engine, target_id, context)
+    link, created = create_memory_link(
+        engine,
+        source_id=memory_id,
+        target_id=target_id,
+        description=input.description,
+        event_metadata=meta,
+    )
+    refreshed = get_memory(engine, memory_id)
+    return CreateNodeLinkResponse(
+        memory_id=memory_id,
+        link=link,
+        created=created,
+        node=MemoryResponse.model_validate(refreshed),
+    )
+
+
+@actions.action(
+    name="collection.create",
+    description="Create a named collection node in the active organization.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/collections"),
+    mcp=False,
+    cli="collection create",
+    tags=["collections"],
+)
+def collection_create(
+    input: CreateCollectionRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> CreateCollectionResponse:
+    collection = create_collection(
+        engine,
+        name=input.name,
+        summary=input.summary,
+        scope=merge_tenant_scope(input.scope, context),
+        metadata=input.metadata,
+        event_metadata=event_metadata(context),
+    )
+    return CreateCollectionResponse(collection=MemoryResponse.model_validate(collection))
+
+
+@actions.action(
+    name="collection.place",
+    description="Place a memory or collection inside a collection, optionally inheriting the parent scope.",
+    kind="write",
+    scopes=["memory:write"],
+    http=HttpExposure("POST", "/memuron/collections/{collection_id}/placements"),
+    mcp=False,
+    cli="collection place",
+    tags=["collections"],
+)
+def collection_place(
+    collection_id: str,
+    input: CreatePlacementRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> CreatePlacementResponse:
+    require_memory_in_tenant(engine, collection_id, context)
+    require_memory_in_tenant(engine, input.child_id, context)
+    placement = place_node_in_collection(
+        engine,
+        parent_id=collection_id,
+        child_id=input.child_id,
+        name=input.name,
+        scope=merge_tenant_scope(input.scope, context),
+        metadata=input.metadata,
+        inherit_parent_scope=input.inherit_parent_scope,
+        event_metadata=event_metadata(context),
+    )
+    return CreatePlacementResponse(placement=PlacementResponse.model_validate(placement))
+
+
+@actions.action(
+    name="collection.members",
+    description="List direct members of a known collection in the active organization.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/collections/{collection_id}/members"),
+    mcp=False,
+    cli="collection members",
+    tags=["collections"],
+)
+def collection_members_action(
+    collection_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> CollectionMembersResponse:
+    require_memory_in_tenant(engine, collection_id, context)
+    members = collection_members(engine, collection_id)
+    return CollectionMembersResponse(
+        collection_id=collection_id,
+        count=len(members),
+        members=members,
+    )
+
+
+@actions.action(
+    name="collection.profile",
+    description=(
+        "Return a lightweight deterministic collection profile with direct member "
+        "summaries and a prompt-ready block."
+    ),
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/collections/{collection_id}/profile"),
+    mcp=False,
+    cli=False,
+    tags=["collections"],
+)
+def collection_profile_action(
+    collection_id: str,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> CollectionProfileResponse:
+    require_memory_in_tenant(engine, collection_id, context)
+    org_id = context.auth.tenant_id
+    if not org_id:
+        raise ValueError("Organization context required")
+    payload = collection_profile(
+        engine,
+        collection_id=collection_id,
+        org_id=str(org_id),
+    )
+    return CollectionProfileResponse.model_validate(
+        {
+            "collection_id": collection_id,
+            "profile": payload["profile"],
+            "prompt_text": payload["prompt_text"],
+        }
+    )

memuron/actions/registry.py

@@ -0,0 +1,5 @@
+"""Bound ActionRegistry for Memuron."""
+
+from artha_engine import ActionRegistry
+
+actions = ActionRegistry()

memuron/actions/runtime.py

@@ -0,0 +1,37 @@
+"""Register Memuron runtime actions."""
+
+from __future__ import annotations
+
+from artha_engine import ActionContext, HttpExposure
+
+from memuron.actions.registry import actions
+from memuron.application.capabilities import memuron_profile_manifest
+
+
+@actions.action(
+    name="memuron.health",
+    kind="read",
+    public=True,
+    http=HttpExposure("GET", "/memuron/health"),
+    mcp=False,
+    cli=False,
+    tags=["memuron"],
+)
+def memuron_health() -> dict[str, str]:
+    return {"status": "ok", "service": "memuron"}
+
+
+@actions.action(
+    name="memuron.profile",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/profile"),
+    mcp=False,
+    cli=False,
+    tags=["memuron"],
+)
+def memuron_profile(context: ActionContext) -> dict[str, object]:
+    _ = context
+    from memuron.actions import actions
+
+    return memuron_profile_manifest({"actions": actions.manifests()})