memuron 0.1.1__py3-none-any.whl

memuron/actions/sync.py

@@ -0,0 +1,155 @@
+"""Folder sync actions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from artha_engine import ActionContext, ArthaEngine
+from pydantic import BaseModel, Field
+
+from memuron.actions.helpers import event_metadata, require_user_org
+from memuron.actions.registry import actions
+from memuron.documents.parser import MAX_DOCUMENT_UPLOAD_BYTES
+from memuron.persistence.identity_store import IdentityStore
+from memuron.security.tenant import merge_org_scope
+from memuron.spaces.service import resolve_space_reference
+from memuron.sync.folder import (
+    init_manifest,
+    load_manifest,
+    resolve_manifest_path,
+    run_engine_folder_sync,
+    save_manifest,
+)
+
+
+class SyncInitInput(BaseModel):
+    path: str = Field(..., description="Local folder root to sync from.")
+    space_ref: str = Field(..., description="Target space UUID, slug, token, or /spaces path.")
+    include: list[str] = Field(default_factory=list, description="Include pattern; repeatable.")
+    exclude: list[str] = Field(default_factory=list, description="Exclude pattern; repeatable.")
+    manifest_path: str | None = Field(None, description="Manifest path override.")
+    max_file_bytes: int = Field(
+        MAX_DOCUMENT_UPLOAD_BYTES,
+        ge=1,
+        description="Skip files larger than this many bytes.",
+    )
+    overwrite: bool = False
+
+
+class SyncRunInput(BaseModel):
+    path: str = Field(..., description="Folder root or manifest JSON path.")
+    manifest_path: str | None = Field(None, description="Manifest path override.")
+    dry_run: bool = False
+
+
+def _space_payload(identity: IdentityStore, *, org_id: str, space_ref: str) -> dict[str, Any]:
+    space = resolve_space_reference(identity, org_id=org_id, space_ref=space_ref)
+    if space is None:
+        raise KeyError("Space not found")
+    return {
+        "id": str(space["id"]),
+        "slug": str(space["slug"]),
+        "name": str(space["name"]),
+        "token": str(space["token"]),
+    }
+
+
+@actions.action(
+    name="sync.init",
+    description="Initialize a one-way folder sync manifest for a local directory.",
+    kind="write",
+    scopes=["memory:write"],
+    cli="sync init",
+    http=False,
+    mcp=False,
+    inject={"identity": "identity"},
+    tags=["sync"],
+)
+def sync_init(
+    input: SyncInitInput,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> dict[str, Any]:
+    _user_id, org_id = require_user_org(context.auth)
+    space = _space_payload(identity, org_id=org_id, space_ref=input.space_ref)
+    manifest, path = init_manifest(
+        input.path,
+        space_ref=input.space_ref,
+        include=input.include,
+        exclude=input.exclude,
+        max_file_bytes=input.max_file_bytes,
+        manifest_path=input.manifest_path,
+        overwrite=input.overwrite,
+    )
+    manifest.space = space
+    save_manifest(manifest, path)
+    return {
+        "status": "success",
+        "manifest_path": str(path),
+        "manifest": manifest.to_dict(),
+    }
+
+
+@actions.action(
+    name="sync.add",
+    description="Add or replace a one-way folder sync manifest for a local directory.",
+    kind="write",
+    scopes=["memory:write"],
+    cli="sync add",
+    http=False,
+    mcp=False,
+    inject={"identity": "identity"},
+    tags=["sync"],
+)
+def sync_add(
+    input: SyncInitInput,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> dict[str, Any]:
+    return sync_init(
+        SyncInitInput(**{**input.model_dump(), "overwrite": True}),
+        context,
+        identity,
+    )
+
+
+@actions.action(
+    name="sync.run",
+    description="Run a one-way folder sync from a manifest, reporting local deletes without deleting remote graph nodes.",
+    kind="write",
+    scopes=["memory:write"],
+    cli="sync run",
+    http=False,
+    mcp=False,
+    inject={"identity": "identity"},
+    tags=["sync"],
+)
+def sync_run(
+    input: SyncRunInput,
+    engine: ArthaEngine,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> dict[str, Any]:
+    _user_id, org_id = require_user_org(context.auth)
+    manifest_path = resolve_manifest_path(input.path, input.manifest_path)
+    if not manifest_path.exists():
+        raise KeyError(f"Folder sync manifest not found: {manifest_path}")
+    manifest = load_manifest(manifest_path)
+    space = _space_payload(
+        identity,
+        org_id=org_id,
+        space_ref=str(manifest.space.get("token") or manifest.space_ref),
+    )
+    manifest.space = space
+    scope = merge_org_scope([space["token"]], org_id)
+    result = run_engine_folder_sync(
+        engine,
+        manifest,
+        scope=scope,
+        event_metadata=event_metadata(context),
+        manifest_path=manifest_path,
+        dry_run=input.dry_run,
+    )
+    result["manifest_path"] = str(Path(manifest_path))
+    return result

memuron/application/__init__.py

@@ -0,0 +1 @@
+"""Application entrypoints, configuration, and runtime assembly."""

memuron/application/api.py

@@ -0,0 +1,206 @@
+"""Memuron HTTP application factory."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+from pathlib import Path
+
+from artha_engine.store import is_postgres_dsn
+from fastapi import HTTPException, Request
+
+from memuron.application.app import configure_clerk_env, create_application
+from memuron.security.clerk_webhooks import router as clerk_webhook_router
+from memuron.application.config import resolve_database_url, settings
+from memuron.persistence.db_pool import close_postgres_pool
+from memuron.ingest.jobs import start_ingest_workers, stop_ingest_workers
+
+logger = logging.getLogger(__name__)
+
+
+class ChatGPTMcpHeaderCompat:
+    """Normalize ChatGPT connector JSON-RPC preflight posts for MCP."""
+
+    def __init__(self, app, auth_challenge: str):
+        self.app = app
+        self.auth_challenge = auth_challenge
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        if scope.get("method") == "POST" and scope.get("path") == "/mcp":
+            if self._has_empty_body(scope):
+                await self._send_auth_challenge(send)
+                return
+            headers = []
+            saw_accept = False
+            for name, value in scope.get("headers", []):
+                normalized_name = name.lower()
+                if (
+                    normalized_name == b"content-type"
+                    and value.split(b";", 1)[0].strip().lower()
+                    == b"application/octet-stream"
+                ):
+                    headers.append((name, b"application/json"))
+                elif normalized_name == b"accept":
+                    saw_accept = True
+                    media_types = [
+                        item.split(b";", 1)[0].strip().lower()
+                        for item in value.split(b",")
+                    ]
+                    if not {
+                        b"application/json",
+                        b"text/event-stream",
+                    }.issubset(set(media_types)):
+                        headers.append(
+                            (name, b"application/json, text/event-stream")
+                        )
+                    else:
+                        headers.append((name, value))
+                else:
+                    headers.append((name, value))
+            if not saw_accept:
+                headers.append((b"accept", b"application/json, text/event-stream"))
+            scope = {**scope, "headers": headers}
+        await self.app(scope, receive, send)
+
+    def _has_empty_body(self, scope) -> bool:
+        for name, value in scope.get("headers", []):
+            if name.lower() == b"content-length":
+                return value.strip() == b"0"
+        return False
+
+    async def _send_auth_challenge(self, send) -> None:
+        content = b'{"error":"authorization_required"}'
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 401,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(content)).encode("ascii")),
+                    (b"www-authenticate", self.auth_challenge.encode("utf-8")),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": content})
+
+
+def create_app(db: str | Path | None = None):
+    configure_clerk_env()
+    application = create_application(db)
+    target = resolve_database_url() if db is None else str(db)
+    engine = application.engine
+    guardian = application.services["guardian"]
+
+    http_app = application.create_http_app(expose_engine=False)
+
+    from artha_engine.runtime.api.app import create_app as create_engine_app
+
+    from memuron.application.capabilities import memuron_engine_profile_capability
+
+    async def engine_auth(request: Request):
+        from artha_engine.app.auth import AuthenticationError
+
+        try:
+            auth = await application.auth_provider.authenticate_http(request)
+        except AuthenticationError as exc:
+            raise HTTPException(status_code=401, detail=str(exc)) from exc
+        required = {"artha:admin"}
+        if "*" not in auth.scopes and not required.issubset(set(auth.scopes)):
+            raise HTTPException(status_code=403, detail="Engine admin scope required")
+        return auth
+
+    profile = memuron_engine_profile_capability(application.manifest())
+    http_app.mount(
+        "/engine",
+        create_engine_app(
+            engine,
+            auth_dependency=engine_auth,
+            profile_capabilities=[profile],
+        ),
+    )
+
+    remote_mcp = None
+    public_domain = os.environ.get("RAILWAY_PUBLIC_DOMAIN", "").strip()
+    public_mcp_url = os.environ.get("MEMURON_MCP_PUBLIC_URL", "").strip()
+    if not public_mcp_url and public_domain:
+        public_mcp_url = f"https://{public_domain}/mcp"
+    if public_mcp_url:
+        from memuron.application.mcp_oauth import (
+            create_remote_mcp_server,
+            mcp_auth_challenge,
+            protected_resource_metadata,
+            protected_resource_metadata_path,
+        )
+
+        remote_mcp = create_remote_mcp_server(application, public_mcp_url)
+
+        @http_app.get(
+            protected_resource_metadata_path(public_mcp_url),
+            include_in_schema=False,
+        )
+        def mcp_protected_resource_metadata():
+            return protected_resource_metadata(public_mcp_url)
+
+        http_app.mount(
+            "/",
+            ChatGPTMcpHeaderCompat(
+                remote_mcp.streamable_http_app(),
+                mcp_auth_challenge(public_mcp_url),
+            ),
+        )
+
+    def _warmup_embedder() -> None:
+        try:
+            engine.embedder.embed_queries(["memuron warmup"])
+            logger.info("Embedder warmed up (%s)", settings.embed_model)
+        except Exception as exc:
+            logger.warning("Embedder warmup failed: %s", exc)
+
+    def _init_projections() -> None:
+        from memuron.memory.recipes import ensure_memory_projections
+
+        ensure_memory_projections(engine)
+        engine.refresh_projection("memuron_fs")
+
+    @contextlib.asynccontextmanager
+    async def lifespan(_app):
+        async with contextlib.AsyncExitStack() as stack:
+            if remote_mcp is not None:
+                await stack.enter_async_context(remote_mcp.session_manager.run())
+            await asyncio.to_thread(_warmup_embedder)
+            await asyncio.to_thread(_init_projections)
+            http_app.state.identity_store = application.services["identity"]
+            await start_ingest_workers(http_app, engine, guardian)
+            try:
+                yield
+            finally:
+                await stop_ingest_workers(http_app)
+                identity_store = getattr(http_app.state, "identity_store", None)
+                if identity_store is not None:
+                    identity_store.close()
+                store_target = getattr(engine.store, "dsn", None) or getattr(
+                    engine.store, "database_target", target
+                )
+                if is_postgres_dsn(str(store_target)):
+                    close_postgres_pool(engine.store)
+
+    http_app.router.lifespan_context = lifespan
+
+    http_app.state.artha_application = application
+    http_app.state.engine = engine
+    http_app.state.guardian = guardian
+    http_app.state.identity_store = application.services["identity"]
+    http_app.state.ingest_job_store = application.services.get("jobs")
+    http_app.include_router(clerk_webhook_router)
+    return http_app
+
+
+def create_engine(db: str | Path | None = None):
+    from memuron.application.app import create_engine as _create_engine
+
+    return _create_engine(db)

memuron/application/app.py

@@ -0,0 +1,103 @@
+"""Memuron ArthaApplication factory."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from artha_engine import ArthaApplication, create_store, resolve_database_target
+from artha_engine.app.managed_api_keys import register_api_key_actions
+from artha_engine.store.api_key_store import ApiKeyStore
+from artha_engine.store import is_postgres_dsn
+
+from memuron.actions import actions
+from memuron.security.auth_provider import create_memuron_auth_provider
+from memuron.security.authorization import MemuronAuthorizationPolicy
+from memuron.application.config import resolve_database_url, settings
+from memuron.persistence.db_pool import install_postgres_pool
+from memuron.persistence.db_pool import close_postgres_pool
+from memuron.memory.engine import MemuronArthaEngine
+from memuron.ingest.guardian import create_guardian
+from memuron.persistence.identity_store import IdentityStore
+from memuron.ingest.jobs import IngestJobStore
+from memuron.application.registry import build_registry
+
+
+def _build_embedder():
+    from artha_engine import DeterministicTextEmbedder, FastEmbedTextEmbedder
+
+    if settings.embedder == "deterministic":
+        return DeterministicTextEmbedder(dimensions=8)
+    try:
+        return FastEmbedTextEmbedder(model_name=settings.embed_model)
+    except Exception:
+        return DeterministicTextEmbedder(dimensions=8)
+
+
+def create_engine(db: str | Path | None = None) -> MemuronArthaEngine:
+    registry = build_registry()
+    target = resolve_database_target(db or resolve_database_url())
+    store = create_store(target, type_registry=registry.arthaanu_types)
+    if is_postgres_dsn(target):
+        install_postgres_pool(store)
+    return MemuronArthaEngine(
+        store=store,
+        registry=registry,
+        embedder=_build_embedder(),
+    )
+
+
+def create_application(db: str | Path | None = None) -> ArthaApplication:
+    target = resolve_database_target(db or resolve_database_url())
+    engine = create_engine(db)
+    services: dict[str, Any] = {
+        "guardian": create_guardian(),
+        "identity": IdentityStore.from_target(target),
+        "jobs": IngestJobStore(target) if is_postgres_dsn(target) else None,
+    }
+    application = ArthaApplication(
+        name="memuron",
+        version="0.1.1",
+        description="Product memory layer on Artha Engine",
+        engine=engine,
+        actions=actions,
+        auth_provider=create_memuron_auth_provider(),
+        authorization_policy=MemuronAuthorizationPolicy(),
+        services=services,
+    )
+    api_key_store = ApiKeyStore.from_target(str(target))
+    registered = {item.name for item in actions.list()}
+    if "api_key.create" not in registered:
+        register_api_key_actions(
+            actions,
+            api_key_store,
+            path_prefix="/memuron/api-keys",
+        )
+    application.services["api_keys"] = api_key_store
+    application.auth_provider = create_memuron_auth_provider(api_key_store=api_key_store)
+    return application
+
+
+def close_application(application: ArthaApplication) -> None:
+    """Release resources owned by a short-lived CLI or MCP application."""
+    identity = application.services.get("identity")
+    close = getattr(identity, "close", None)
+    if callable(close):
+        close()
+    close_postgres_pool(application.engine.store)
+
+
+def configure_clerk_env() -> None:
+    """Apply sensible Clerk defaults from documented env vars."""
+    if not os.environ.get("CLERK_ISSUER") and os.environ.get("NEXT_PUBLIC_CLERK_FRONTEND_API"):
+        os.environ["CLERK_ISSUER"] = os.environ["NEXT_PUBLIC_CLERK_FRONTEND_API"].rstrip("/")
+    if not os.environ.get("CLERK_ISSUER"):
+        os.environ.setdefault(
+            "CLERK_ISSUER",
+            "https://credible-perch-55.clerk.accounts.dev",
+        )
+    issuer = os.environ["CLERK_ISSUER"].rstrip("/")
+    os.environ.setdefault("CLERK_JWKS_URL", f"{issuer}/.well-known/jwks.json")
+    os.environ.setdefault("CLERK_AUTHORIZED_PARTIES", "http://localhost:3000")
+    os.environ.setdefault("ARTHA_AUTH_PROVIDER", "clerk_api_key")

memuron/application/capabilities.py

@@ -0,0 +1,82 @@
+"""Memuron profile manifest built from registered actions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+MEMURON_PROFILE_NAME = "memuron"
+
+_BASE_MANIFEST: dict[str, Any] = {
+    "profile": MEMURON_PROFILE_NAME,
+    "description": "Product memory layer: Guardian ingest, rich nodes, collections, links, semantic search.",
+    "api_prefix": "/memuron",
+    "arthaanu_types": ["memory", "memory_link", "memory_placement"],
+    "encoders": ["memory", "memory_link", "memory_placement"],
+    "projections": ["memuron_memories", "memuron_links", "memuron_placements", "memuron_fs"],
+    "semantic_events": [
+        "memory.created",
+        "memory.updated",
+        "collection.created",
+        "link.created",
+        "placement.created",
+        "delete",
+    ],
+    "event_metadata": [
+        "domain_event_type",
+        "actor_id",
+        "tenant_id",
+        "auth_scopes",
+        "request_id",
+    ],
+    "agent_tools": [
+        {
+            "name": "list_spaces",
+            "description": "List registered spaces with name, token, description, and default flag.",
+            "route": "GET /memuron/spaces",
+        },
+        {
+            "name": "read_graph_filesystem_manual",
+            "description": "Read this before issuing filesystem commands.",
+            "route": "GET /memuron/spaces/query/manual?topic=overview",
+        },
+        {
+            "name": "query_graph_filesystem",
+            "description": "Execute one command or a | pipeline.",
+            "route": "POST /memuron/spaces/query",
+        },
+    ],
+}
+
+
+def memuron_profile_manifest(application_manifest: dict[str, Any] | None = None) -> dict[str, Any]:
+    manifest = dict(_BASE_MANIFEST)
+    if application_manifest is not None:
+        manifest["actions"] = application_manifest.get("actions", [])
+    return manifest
+
+
+def memuron_engine_profile_capability(
+    application_manifest: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    manifest = memuron_profile_manifest(application_manifest)
+    return {
+        "name": manifest["profile"],
+        "description": manifest.get("description"),
+        "projections": manifest.get("projections", []),
+        "arthaanu_types": manifest.get("arthaanu_types", []),
+        "actions": manifest.get("actions", []),
+        "routes": manifest.get("agent_tools", []),
+        "metadata": {
+            key: value
+            for key, value in manifest.items()
+            if key
+            not in {
+                "profile",
+                "description",
+                "projections",
+                "arthaanu_types",
+                "actions",
+                "agent_tools",
+            }
+        },
+    }

memuron/application/cli.py

@@ -0,0 +1,35 @@
+"""Memuron CLI entry point."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from memuron.application.app import close_application, configure_clerk_env, create_application
+
+
+def main(argv: list[str] | None = None) -> int:
+    configure_clerk_env()
+    os.environ.setdefault("ARTHA_AUTH_PROVIDER", "api_key")
+    os.environ.setdefault(
+        "ARTHA_CONFIG_PATH",
+        str(Path.home() / ".config" / "memuron" / "config.json"),
+    )
+    if os.environ.get("MEMURON_API_KEY") and not os.environ.get("ARTHA_API_KEY"):
+        os.environ["ARTHA_API_KEY"] = os.environ["MEMURON_API_KEY"]
+    if os.environ.get("MEMURON_BASE_URL") and not os.environ.get("ARTHA_BASE_URL"):
+        os.environ["ARTHA_BASE_URL"] = os.environ["MEMURON_BASE_URL"]
+    effective_argv = list(sys.argv[1:] if argv is None else argv)
+    help_only = not effective_argv or any(
+        item in {"-h", "--help"} for item in effective_argv
+    )
+    application = create_application(":memory:" if help_only else None)
+    try:
+        return application.run_cli(argv, prog="memuron")
+    finally:
+        close_application(application)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())