memuron 0.1.1__py3-none-any.whl

memuron/__init__.py

@@ -0,0 +1,3 @@
+from memuron.application.registry import build_registry
+
+__all__ = ["build_registry"]

memuron/actions/__init__.py

@@ -0,0 +1,12 @@
+"""Import all action modules to register handlers on the shared registry."""
+
+from memuron.actions.registry import actions
+from memuron.actions import context as _context  # noqa: F401
+from memuron.actions import memory as _memory  # noqa: F401
+from memuron.actions import memory_write as _memory_write  # noqa: F401
+from memuron.actions import nodes as _nodes  # noqa: F401
+from memuron.actions import runtime as _runtime  # noqa: F401
+from memuron.actions import spaces_documents as _spaces_documents  # noqa: F401
+from memuron.actions import sync as _sync  # noqa: F401
+
+__all__ = ["actions"]

memuron/actions/context.py

@@ -0,0 +1,63 @@
+"""Context assembly actions."""
+
+from __future__ import annotations
+
+from artha_engine import ActionContext, ArthaEngine, HttpExposure
+
+from memuron.actions.helpers import merge_tenant_scope, require_user_org
+from memuron.actions.registry import actions
+from memuron.context import assemble_context
+from memuron.domain.schemas import AssembleContextRequest, AssembleContextResponse
+from memuron.persistence.identity_store import IdentityStore
+from memuron.spaces.service import resolve_space_reference
+
+
+@actions.action(
+    name="context.assemble",
+    description=(
+        "Assemble graph-native prompt context from memory search results, "
+        "collection breadcrumbs, and semantic links with citation metadata."
+    ),
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("POST", "/memuron/context/assemble"),
+    mcp=False,
+    cli=False,
+    inject={"identity": "identity"},
+    tags=["context"],
+)
+def context_assemble(
+    input: AssembleContextRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> AssembleContextResponse:
+    _user_id, org_id = require_user_org(context.auth)
+    scoped = merge_tenant_scope(input.scope, context)
+    preferred_space_token = None
+    if input.space_ref:
+        space = resolve_space_reference(
+            identity,
+            org_id=org_id,
+            space_ref=input.space_ref,
+        )
+        if space is None:
+            raise KeyError("Space not found")
+        preferred_space_token = str(space["token"])
+        scoped = [token for token in scoped if not token.startswith("space.")]
+        if preferred_space_token not in scoped:
+            scoped.append(preferred_space_token)
+
+    payload = assemble_context(
+        engine,
+        query=input.query,
+        k=input.k,
+        scope=scoped or None,
+        org_id=org_id,
+        preferred_space_token=preferred_space_token,
+        token_budget=input.token_budget,
+        char_budget=input.char_budget,
+        include_links=input.include_links,
+        include_breadcrumbs=input.include_breadcrumbs,
+    )
+    return AssembleContextResponse.model_validate(payload)

memuron/actions/helpers.py

@@ -0,0 +1,88 @@
+"""Shared helpers for Memuron Artha actions."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from artha_engine.app.context import ActionContext
+from artha_engine.runtime.auth import AuthContext
+
+from memuron.domain.limits import MAX_SCOPE_ITEMS, MAX_SCOPE_TOKEN_LEN
+from memuron.security.tenant import merge_org_scope
+
+
+def require_user_org(auth: AuthContext) -> tuple[str, str]:
+    org_id = auth.tenant_id
+    if not org_id:
+        raise ValueError("Organization context required")
+    return str(auth.actor_id), str(org_id)
+
+
+def require_memory_in_tenant(
+    engine: Any,
+    memory_id: str,
+    context: ActionContext,
+) -> dict[str, Any]:
+    """Return a memory only when it belongs to the caller's active organization."""
+    from memuron.memory.recipes import get_memory
+    from memuron.security.tenant import org_scope_token
+
+    _user_id, org_id = require_user_org(context.auth)
+    memory = get_memory(engine, memory_id)
+    if org_scope_token(org_id) not in set(memory.get("scope") or []):
+        raise KeyError(f"Memory not found: {memory_id}")
+    return memory
+
+
+def event_metadata(
+    context: ActionContext,
+    *,
+    space_context: dict[str, str] | None = None,
+) -> dict[str, object]:
+    metadata = context.auth.event_metadata()
+    if context.request_id:
+        metadata["request_id"] = context.request_id
+    if space_context:
+        metadata["space_context"] = space_context
+    return metadata
+
+
+def merge_tenant_scope(scope: list[str] | None, context: ActionContext) -> list[str]:
+    return merge_org_scope(scope, context.auth.tenant_id)
+
+
+def tenant_scope_query(context: ActionContext, scope: str | None) -> str | None:
+    from memuron.security.tenant import tenant_scope_query as _tenant_scope_query
+
+    return _tenant_scope_query(context.auth.tenant_id, scope)
+
+
+def parse_scope_form(value: str | None) -> list[str] | None:
+    if value is None or not value.strip():
+        return None
+    raw = value.strip()
+    if raw.startswith("["):
+        decoded = json.loads(raw)
+        if not isinstance(decoded, list) or not all(isinstance(item, str) for item in decoded):
+            raise ValueError("scope must be a list of strings")
+        scope = decoded
+    else:
+        scope = [part.strip() for part in raw.split(",") if part.strip()]
+    if len(scope) > MAX_SCOPE_ITEMS:
+        raise ValueError(f"scope can contain at most {MAX_SCOPE_ITEMS} tokens")
+    for token in scope:
+        if len(token) > MAX_SCOPE_TOKEN_LEN:
+            raise ValueError(
+                f"Each scope token must be at most {MAX_SCOPE_TOKEN_LEN} characters"
+            )
+    return scope
+
+
+def parse_metadata_form(value: str | None) -> dict[str, object]:
+    if value is None or not value.strip():
+        return {}
+    decoded = json.loads(value)
+    if not isinstance(decoded, dict):
+        raise ValueError("metadata must be a JSON object")
+    return decoded

memuron/actions/memory.py

@@ -0,0 +1,340 @@
+"""Memory read/search actions."""
+
+from __future__ import annotations
+
+from artha_engine import ActionContext, ArthaEngine, HttpExposure
+
+from memuron.actions.helpers import (
+    merge_tenant_scope,
+    require_memory_in_tenant,
+    tenant_scope_query,
+)
+from memuron.actions.registry import actions
+from memuron.memory.recipes import (
+    count_memories,
+    export_graph,
+    get_memory,
+    graph_hubs,
+    graph_neighborhood,
+    graph_path,
+    list_memories,
+    search_memories,
+    semantic_traverse_graph,
+)
+from memuron.domain.schemas import (
+    CountMemoriesResponse,
+    GetMemoriesRequest,
+    GetMemoriesResponse,
+    GetMemoryResponse,
+    GetMemoryViewResponse,
+    GraphExportResponse,
+    GraphHubsResponse,
+    GraphNeighborhoodResponse,
+    GraphPathResponse,
+    GraphTraversalResponse,
+    ListMemoriesResponse,
+    MemoryResponse,
+    SearchMemoriesRequest,
+    SearchResponse,
+)
+from memuron.domain.scope_filter import parse_comma_scope
+
+
+@actions.action(
+    name="memory.count",
+    description="Count memories in the active organization, optionally filtered by scope.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/memories/count"),
+    mcp=False,
+    cli="memory count",
+    tags=["memory"],
+)
+def memory_count(
+    engine: ArthaEngine,
+    context: ActionContext,
+    scope: str | None = None,
+) -> CountMemoriesResponse:
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    count, filters = count_memories(engine, scope=effective_scope)
+    return CountMemoriesResponse(count=count, filters=filters)
+
+
+@actions.action(
+    name="memory.list",
+    description="List memories in the active organization with pagination and optional scope filtering.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/memories"),
+    mcp=False,
+    cli="memory list",
+    tags=["memory"],
+)
+def memory_list(
+    engine: ArthaEngine,
+    context: ActionContext,
+    scope: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+) -> ListMemoriesResponse:
+    if limit < 1 or limit > 1000:
+        raise ValueError("limit must be between 1 and 1000")
+    if offset < 0:
+        raise ValueError("offset must be >= 0")
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    memories, total, filters = list_memories(
+        engine,
+        scope=effective_scope,
+        limit=limit,
+        offset=offset,
+    )
+    return ListMemoriesResponse(
+        count=total,
+        memories=[MemoryResponse.model_validate(item) for item in memories],
+        filters=filters,
+    )
+
+
+@actions.action(
+    name="memory.search",
+    description="Run direct semantic memory search. Agents should normally prefer memuron_query, which combines semantic, regex, and graph operations.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("POST", "/memuron/memories/search"),
+    mcp=False,
+    cli="memory search",
+    tags=["memory"],
+)
+def memory_search(
+    input: SearchMemoriesRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+) -> SearchResponse:
+    scoped = merge_tenant_scope(input.scope, context)
+    results, scope = search_memories(engine, input.query, k=input.k, scope=scoped or None)
+    return SearchResponse(count=len(results), scope=scope, results=results)
+
+
+@actions.action(
+    name="memory.get",
+    description="Fetch one memory by ID from the active organization after an ID is discovered through memuron_query.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/memories/{memory_id}"),
+    mcp=False,
+    cli="memory get",
+    tags=["memory"],
+)
+def memory_get(
+    engine: ArthaEngine,
+    context: ActionContext,
+    memory_id: str,
+) -> GetMemoryResponse:
+    memory = require_memory_in_tenant(engine, memory_id, context)
+    return GetMemoryResponse(memory=MemoryResponse.model_validate(memory))
+
+
+@actions.action(
+    name="memory.get_mcp",
+    description="Fetch a known memory with bounded content. Use fields to select keys and raise max_chars only when the full body is necessary.",
+    kind="read",
+    scopes=["memory:read"],
+    mcp="memuron_get",
+    cli=False,
+    tags=["memory"],
+)
+def memory_get_mcp(
+    engine: ArthaEngine,
+    context: ActionContext,
+    memory_id: str,
+    fields: list[str] | None = None,
+    max_chars: int = 4000,
+    include_perception: bool = False,
+) -> GetMemoryViewResponse:
+    if max_chars < 0 or max_chars > 100_000:
+        raise ValueError("max_chars must be between 0 and 100000")
+    memory = require_memory_in_tenant(engine, memory_id, context)
+    allowed = set(MemoryResponse.model_fields)
+    selected = set(fields or allowed)
+    unknown = selected - allowed
+    if unknown:
+        raise ValueError(f"Unknown fields: {', '.join(sorted(unknown))}")
+    if not include_perception:
+        selected.discard("perception")
+    view = {key: value for key, value in memory.items() if key in selected}
+    truncated_fields: list[str] = []
+    for key in ("content", "perception"):
+        value = view.get(key)
+        if isinstance(value, str) and len(value) > max_chars:
+            view[key] = value[:max_chars]
+            truncated_fields.append(key)
+    return GetMemoryViewResponse(
+        memory=view,
+        truncated_fields=truncated_fields,
+    )
+
+
+@actions.action(
+    name="memory.batch_get",
+    description="Fetch several known memory IDs from the active organization.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("POST", "/memuron/memories/batch"),
+    mcp=False,
+    cli="memory batch-get",
+    tags=["memory"],
+)
+def memory_batch_get(
+    engine: ArthaEngine,
+    context: ActionContext,
+    input: GetMemoriesRequest,
+) -> GetMemoriesResponse:
+    memories = [
+        require_memory_in_tenant(engine, memory_id, context)
+        for memory_id in input.memory_ids
+    ]
+    return GetMemoriesResponse(
+        count=len(memories),
+        memories=[MemoryResponse.model_validate(item) for item in memories],
+    )
+
+
+@actions.action(
+    name="graph.export",
+    description="Export a bounded graph snapshot for the active organization. Prefer memuron_query for ordinary graph navigation.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/graph/export"),
+    mcp=False,
+    cli="graph export",
+    tags=["graph"],
+)
+def graph_export(
+    engine: ArthaEngine,
+    context: ActionContext,
+    scope: str | None = None,
+    limit: int = 1000,
+) -> GraphExportResponse:
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    return GraphExportResponse(
+        graph=export_graph(engine, scope=effective_scope, limit=limit)
+    )
+
+
+@actions.action(
+    name="graph.hubs",
+    description="Find highly connected memories in the active organization.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/graph/hubs"),
+    mcp=False,
+    cli="graph hubs",
+    tags=["graph"],
+)
+def graph_hubs_action(
+    engine: ArthaEngine,
+    context: ActionContext,
+    scope: str | None = None,
+    limit: int = 10,
+) -> GraphHubsResponse:
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    hubs, total_memories = graph_hubs(engine, scope=effective_scope, limit=limit)
+    return GraphHubsResponse(hubs=hubs, total_memories=total_memories)
+
+
+@actions.action(
+    name="graph.neighborhood",
+    description="Inspect the bounded graph neighborhood around a known memory in the active organization.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/graph/neighborhood"),
+    mcp=False,
+    cli="graph neighborhood",
+    tags=["graph"],
+)
+def graph_neighborhood_action(
+    engine: ArthaEngine,
+    context: ActionContext,
+    memory_id: str,
+    hops: int = 2,
+    scope: str | None = None,
+) -> GraphNeighborhoodResponse:
+    require_memory_in_tenant(engine, memory_id, context)
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    payload = graph_neighborhood(
+        engine,
+        memory_id=memory_id,
+        hops=hops,
+        scope=effective_scope,
+    )
+    return GraphNeighborhoodResponse(**payload)
+
+
+@actions.action(
+    name="graph.path",
+    description="Find a graph path between two known memories in the active organization.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/graph/path"),
+    mcp=False,
+    cli="graph path",
+    tags=["graph"],
+)
+def graph_path_action(
+    engine: ArthaEngine,
+    context: ActionContext,
+    from_id: str,
+    to_id: str,
+    scope: str | None = None,
+) -> GraphPathResponse:
+    require_memory_in_tenant(engine, from_id, context)
+    require_memory_in_tenant(engine, to_id, context)
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    payload = graph_path(engine, from_id=from_id, to_id=to_id, scope=effective_scope)
+    return GraphPathResponse(**payload)
+
+
+@actions.action(
+    name="graph.traverse",
+    description="Semantically traverse graph edges from a known memory in the active organization.",
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("GET", "/memuron/graph/traverse"),
+    mcp=False,
+    cli="graph traverse",
+    tags=["graph"],
+)
+def graph_traverse_action(
+    engine: ArthaEngine,
+    context: ActionContext,
+    start_memory_id: str,
+    query: str,
+    max_hops: int = 2,
+    edge_similarity_threshold: float = 0.7,
+    scope: str | None = None,
+) -> GraphTraversalResponse:
+    require_memory_in_tenant(engine, start_memory_id, context)
+    effective_scope = tenant_scope_query(context, scope)
+    if effective_scope is not None:
+        parse_comma_scope(effective_scope)
+    payload = semantic_traverse_graph(
+        engine,
+        start_memory_id=start_memory_id,
+        query=query,
+        max_hops=max_hops,
+        edge_similarity_threshold=edge_similarity_threshold,
+        scope=effective_scope,
+    )
+    return GraphTraversalResponse(**payload)