aethergraph 0.1.0a1__py3-none-any.whl → 0.1.0a3__py3-none-any.whl

aethergraph/services/registry/agent_app_meta.py

@@ -0,0 +1,419 @@
+# aethergraph/runtime/agent_app_meta.py
+from __future__ import annotations
+
+from collections.abc import Callable
+import inspect
+from typing import Any, Literal, TypedDict
+
+from aethergraph.core.runtime.run_types import RunImportance, RunVisibility
+
+# ---------------------------------------------------------------------
+# Config schemas used by decorators
+# ---------------------------------------------------------------------
+SUPPORTED_AGENT_MODES = {"chat_v1"}
+
+
+class AgentConfig(TypedDict, total=False):
+    """
+    Configuration metadata for an agent. Register an agent with `as_agent`
+    parameter in `@graphify` or `@graph_fn`.
+
+    All fields are optional except `id` in practice; anything omitted gets
+    reasonable defaults in build_agent_meta.
+
+    Attributes:
+        id (str): Unique identifier for the agent. Defaults to graph name.
+        title (str): Display name of the agent. Optional, shown in the UI.
+        description (str): Brief description of the agent. Optional, shown in the UI.
+        short_description (str): Shorter summary (used in cards). Optional.
+        icon_key (str): Icon key used in the UI (e.g. "message-circle").
+        color (str): Accent color token (e.g. "emerald").
+        badge (str): Badge label, e.g. "Chat Agent".
+        category (str): Category, e.g. "Core", "R&D Lab", "Infra", "Productivity".
+        status (str): "available" | "coming-soon" | "hidden" | "error" | ...
+        mode (str): Operational mode. Defaults to "chat_v1" for chat agents.
+        session_kind (str): Session type, e.g. "chat". Defaults to "chat".
+        flow_id (str): Flow identifier for wiring. Defaults to graph name.
+        tags (list[str]): Tags used for search / grouping.
+        tool_graphs (list[str]): Related tool graph identifiers.
+        features (list[str]): Optional feature bullets for UI.
+        run_visibility (RunVisibility): "normal" | "inline" | ...
+        run_importance (RunImportance): "normal" | "high" | ...
+        memory_level (Literal["user","session","run"]): Memory scope level.
+        memory_scope (str): Logical scope, e.g. "session.global", "user.all".
+        github_url (str): Optional GitHub link.
+    """
+
+    # Identity & basic UI
+    id: str
+    title: str
+    description: str
+    short_description: str
+    icon_key: str
+    color: str
+    badge: str
+    category: str
+    status: str  # "available" | "coming-soon" | "hidden" | ...
+
+    # Behavior & wiring
+    mode: str  # "chat_v1", etc.
+    session_kind: str  # "chat", "batch", ...
+
+    flow_id: str
+    tags: list[str]
+    tool_graphs: list[str]
+    features: list[str]
+
+    # Runtime behavior
+    run_visibility: RunVisibility
+    run_importance: RunImportance
+
+    # Memory policy
+    memory_level: Literal["user", "session", "run"]
+    memory_scope: str
+
+    # Optional metadata
+    github_url: str
+
+
+class AppConfig(TypedDict, total=False):
+    """
+    Configuration metadata for an application. Register an app with `as_app`
+    parameter in `@graphify` or `@graph_fn`.
+
+    Attributes:
+        id (str): Unique identifier for the app. Defaults to graph name.
+        name (str): Human-readable name of the app. Defaults to "App for <graph>".
+        badge (str): Short badge or label for the app. Optional, shown in the UI.
+        short_description (str): Brief summary of the app's purpose. Optional.
+        description (str): Detailed description of the app. Optional.
+        category (str): Category, e.g. "Core", "R&D Lab", "Infra", "Productivity".
+        status (str): "available" | "coming-soon" | "hidden" | "error" | ...
+        icon_key (str): Icon key for the app.
+        color (str): Accent color token.
+        mode (str): App mode, e.g. "no_input_v1". Defaults to "no_input_v1".
+        tags (list[str]): Tags for search / grouping.
+        features (list[str]): Notable features for the app.
+        run_visibility (RunVisibility): "normal" | "inline" | ...
+        run_importance (RunImportance): "normal" | "high" | ...
+        flow_id (str): Flow identifier. Defaults to graph name.
+        github_url (str): Optional GitHub link.
+    """
+
+    # Identity & UI
+    id: str
+    name: str
+    badge: str
+    short_description: str
+    description: str
+    category: str
+    status: str
+    icon_key: str
+    color: str
+    mode: str
+    tags: list[str]
+
+    # UX hints
+    features: list[str]
+
+    # Runtime behavior
+    run_visibility: RunVisibility
+    run_importance: RunImportance
+    flow_id: str
+
+    # Optional metadata
+    github_url: str
+
+
+AGENT_CORE_KEYS = {
+    "id",
+    "title",
+    "description",
+    "short_description",
+    "icon_key",
+    "color",
+    "badge",
+    "category",
+    "status",
+    "mode",
+    "session_kind",
+    "flow_id",
+    "tags",
+    "tool_graphs",
+    "features",
+    "run_visibility",
+    "run_importance",
+    "memory_level",
+    "memory_scope",
+    "github_url",
+}
+
+APP_CORE_KEYS = {
+    "id",
+    "name",
+    "badge",
+    "short_description",
+    "description",
+    "category",
+    "status",
+    "icon_key",
+    "color",
+    "mode",
+    "tags",
+    "features",
+    "run_visibility",
+    "run_importance",
+    "flow_id",
+    "github_url",
+}
+
+# ---------------------------------------------------------------------
+# Shared constants / validators
+# ---------------------------------------------------------------------
+
+CHAT_V1_REQUIRED_INPUTS = [
+    "message",
+    "files",
+    "context_refs",
+    "session_id",
+    "user_meta",
+]
+
+
+def normalize_agent_mode(agent_cfg: AgentConfig) -> str:
+    # Default behavior: if user doesn't specify, it's chat_v1
+    mode = (agent_cfg.mode or "chat_v1").strip()
+
+    if mode not in SUPPORTED_AGENT_MODES:
+        # this will be caught and turned into status="error" for now
+        raise ValueError(
+            f"Unsupported agent mode '{mode}'. "
+            "Currently only 'chat_v1' is supported. "
+            "Omit 'mode' or set mode='chat_v1'."
+        )
+    return mode
+
+
+SUPPORTED_APP_MODES = {"no_input_v1"}
+
+
+def normalize_app_mode(app_cfg: AppConfig) -> str:
+    mode = (app_cfg.mode or "no_input_v1").strip()
+    if mode not in SUPPORTED_APP_MODES:
+        raise ValueError(
+            f"Unsupported app mode '{mode}'. "
+            "Currently only 'no_input_v1' is supported for gallery apps. "
+            "Omit 'mode' or set mode='no_input_v1'."
+        )
+    return mode
+
+
+def validate_agent_signature(
+    graph_name: str, fn: Callable, agent_cfg: AgentConfig
+) -> tuple[str, list[str]]:
+    mode = normalize_agent_mode(agent_cfg)
+
+    sig = inspect.signature(fn)
+    param_names = list(sig.parameters.keys())
+
+    if mode == "chat_v1":
+        missing = [p for p in CHAT_V1_REQUIRED_INPUTS if p not in param_names]
+        if missing:
+            raise ValueError(
+                f"chat_v1 agent '{graph_name}' is missing parameters: {missing}. "
+                f"Expected parameters: {CHAT_V1_REQUIRED_INPUTS}"
+            )
+        # TODO future: could be more flexible here:
+        #  - use CHAT_V1_REQUIRED_INPUTS as canonical inputs, or
+        #  - accept superset but keep these first.
+        inputs = CHAT_V1_REQUIRED_INPUTS
+    else:
+        # Currently unreachable because normalize_agent_mode rejects unknowns,
+        # but future-proof if add more modes.
+        inputs = param_names
+
+    return mode, inputs
+
+
+# ---------------------------------------------------------------------
+# Normalization helpers used by decorators & other runtime code
+# ---------------------------------------------------------------------
+
+
+def build_agent_meta(
+    *,
+    graph_name: str,
+    version: str,
+    graph_meta: dict[str, Any],
+    agent_cfg: AgentConfig | None,
+) -> dict[str, Any] | None:
+    """
+    Normalize AgentConfig + graph metadata into a registry-ready meta dict.
+
+    Returns None if agent_cfg is None.
+    """
+    if agent_cfg is None:
+        return None
+
+    cfg: dict[str, Any] = dict(agent_cfg)
+    base_tags = graph_meta.get("tags") or []
+
+    agent_id = cfg.get("id", graph_name)
+    agent_title = cfg.get("title", f"Agent for {graph_name}")
+    agent_flow_id = cfg.get("flow_id", graph_meta.get("flow_id", graph_name))
+    agent_tags = cfg.get("tags", base_tags)
+
+    # Anything not in core keys becomes "extra" for future use
+    extra = {k: v for k, v in cfg.items() if k not in AGENT_CORE_KEYS}
+
+    # Memory policy
+    memory_level = cfg.get("memory_level", "session")
+    memory_scope = cfg.get("memory_scope")
+
+    # Text fields
+    description = cfg.get("description")
+    short_description = cfg.get("short_description") or description
+
+    # Visuals
+    icon_key = cfg.get("icon_key")
+    accent_color = cfg.get("color")
+
+    # Behavior
+    agent_mode = cfg.get("mode") or "chat_v1"
+    session_kind = cfg.get("session_kind", "chat")
+
+    meta: dict[str, Any] = {
+        "kind": "agent",
+        "id": agent_id,
+        "title": agent_title,
+        "description": description,
+        "short_description": short_description,
+        "icon_key": icon_key,
+        "color": accent_color,
+        "badge": cfg.get("badge"),
+        "category": cfg.get("category"),
+        "status": cfg.get("status", "available"),
+        "mode": agent_mode,
+        "session_kind": session_kind,
+        "flow_id": agent_flow_id,
+        "tags": agent_tags,
+        "tool_graphs": cfg.get("tool_graphs", []),
+        "features": cfg.get("features", []),
+        "run_visibility": cfg.get("run_visibility", "inline"),
+        "run_importance": cfg.get("run_importance", "normal"),
+        "memory": {
+            "level": memory_level,
+            "scope": memory_scope,
+        },
+        "github_url": cfg.get("github_url"),
+        "backing": {
+            "type": "graphfn",
+            "name": graph_name,
+            "version": version,
+        },
+        "extra": extra,
+    }
+
+    # unified gallery view
+    meta["gallery"] = {
+        "kind": "agent",
+        "id": agent_id,
+        "title": agent_title,
+        "subtitle": session_kind or agent_mode,
+        "badge": cfg.get("badge"),
+        "category": cfg.get("category"),
+        "status": meta["status"],
+        "short_description": short_description,
+        "description": description,
+        "icon_key": icon_key,
+        "accent_color": accent_color,
+        "tags": agent_tags,
+        "github_url": cfg.get("github_url"),
+        "flow_id": agent_flow_id,
+        "backing": meta["backing"],
+        "extra": extra,
+    }
+
+    return meta
+
+
+def build_app_meta(
+    *,
+    graph_name: str,
+    version: str,
+    graph_meta: dict[str, Any],
+    app_cfg: AppConfig | None,
+) -> dict[str, Any] | None:
+    """
+    Normalize AppConfig + graph metadata into a registry-ready meta dict.
+
+    Returns None if app_cfg is None.
+    """
+    if app_cfg is None:
+        return None
+
+    cfg: dict[str, Any] = dict(app_cfg)
+    base_tags = graph_meta.get("tags") or []
+
+    app_id = cfg.get("id", graph_name)
+    app_flow_id = cfg.get("flow_id", graph_meta.get("flow_id", graph_name))
+    app_name = cfg.get("name", f"App for {graph_name}")
+    app_tags = cfg.get("tags", base_tags)
+
+    extra = {k: v for k, v in cfg.items() if k not in APP_CORE_KEYS}
+
+    short_description = cfg.get("short_description") or cfg.get("description")
+    description = cfg.get("description")
+
+    icon_key = cfg.get("icon_key")
+    accent_color = cfg.get("color")
+    app_mode = cfg.get("mode") or "no_input_v1"
+
+    meta: dict[str, Any] = {
+        "kind": "app",
+        "id": app_id,
+        "name": app_name,
+        "graph_id": graph_name,
+        "flow_id": app_flow_id,
+        "badge": cfg.get("badge"),
+        "category": cfg.get("category"),
+        "short_description": short_description,
+        "description": description,
+        "status": cfg.get("status", "available"),
+        "icon_key": icon_key,
+        "color": accent_color,
+        "mode": app_mode,
+        "tags": app_tags,
+        "features": cfg.get("features", []),
+        "run_visibility": cfg.get("run_visibility", "normal"),
+        "run_importance": cfg.get("run_importance", "normal"),
+        "github_url": cfg.get("github_url"),
+        "backing": {
+            "type": "graphfn",
+            "name": graph_name,
+            "version": version,
+        },
+        "extra": extra,
+    }
+
+    # unified gallery view
+    meta["gallery"] = {
+        "kind": "app",
+        "id": app_id,
+        "title": app_name,
+        "subtitle": cfg.get("category"),
+        "badge": cfg.get("badge"),
+        "category": cfg.get("category"),
+        "status": meta["status"],
+        "short_description": short_description,
+        "description": description,
+        "icon_key": icon_key,
+        "accent_color": accent_color,
+        "tags": app_tags,
+        "github_url": cfg.get("github_url"),
+        "flow_id": app_flow_id,
+        "backing": meta["backing"],
+        "extra": extra,
+    }
+
+    return meta

aethergraph/services/registry/registry_key.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 import re
 
-NS = {"tool", "graph", "graphfn", "agent"}
+NS = {"tool", "graph", "graphfn", "agent", "app"}
 
 # Simple ref regex to detect optional leading 'registry:'
 _REG_PREFIX = re.compile(r"^registry:(.+)$", re.I)

aethergraph/services/registry/unified_registry.py

@@ -37,9 +37,20 @@ class UnifiedRegistry:
         self._lock = threading.RLock()
         self._allow_overwrite = allow_overwrite
 
+        # per-version metadata
+        self._meta: dict[tuple[str, str, str], dict[str, Any]] = {}
+
     # ---------- registration ----------
 
-    def register(self, *, nspace: str, name: str, version: str, obj: RegistryValue) -> None:
+    def register(
+        self,
+        *,
+        nspace: str,
+        name: str,
+        version: str,
+        obj: RegistryValue,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
         if nspace not in NS:
             raise ValueError(f"Unknown namespace: {nspace}")
         key = (nspace, name)
@@ -52,6 +63,10 @@ class UnifiedRegistry:
             versions[version] = obj
             self._latest[key] = self._pick_latest(versions.keys())
 
+            # Store metadata
+            if meta is not None:
+                self._meta[(nspace, name, version)] = meta
+
     def register_latest(
         self, *, nspace: str, name: str, obj: RegistryValue, version: str = "0.0.0"
     ) -> None:
@@ -85,11 +100,13 @@ class UnifiedRegistry:
                 raise KeyError(f"Version not found: {key.nspace}:{key.name}@{ver}")
 
             val = versions[ver]
-            # Materialize factories lazily (and cache)
-            if callable(val):
-                obj = val()
-                versions[ver] = obj
-                return obj
+
+            ## Materialize if factory -> we handle it when executing the graphs. Here it can cause
+            # the graph_fn returns a coroutine inside the GraphFunction object, not the expected function.
+            # if callable(val):
+            #     obj = val()
+            #     versions[ver] = obj
+            #     return obj
             return val
 
     # ---------- listing / admin ----------
@@ -123,6 +140,10 @@ class UnifiedRegistry:
                 self._store.pop(k, None)
                 self._latest.pop(k, None)
                 self._aliases.pop(k, None)
+                # NEW: drop all meta for this (ns,name)
+                for key in list(self._meta.keys()):
+                    if key[0] == nspace and key[1] == name:
+                        self._meta.pop(key, None)
                 return
             vers = self._store[k]
             vers.pop(version, None)
@@ -131,6 +152,8 @@ class UnifiedRegistry:
                 for tag, v in list(self._aliases[k].items()):
                     if v == version:
                         self._aliases[k].pop(tag, None)
+            # drop meta for this version
+            self._meta.pop((nspace, name, version), None)
             # recompute latest
             if vers:
                 self._latest[k] = self._pick_latest(vers.keys())
@@ -144,6 +167,7 @@ class UnifiedRegistry:
             self._store.clear()
             self._latest.clear()
             self._aliases.clear()
+            self._meta.clear()
 
     # ---------- typed getters ----------
 
@@ -159,6 +183,50 @@ class UnifiedRegistry:
     def get_agent(self, name: str, version: str | None = None) -> Any:
         return self.get(Key(nspace="agent", name=name, version=version))
 
+    def get_meta(
+        self,
+        nspace: str,
+        name: str,
+        version: str | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Return metadata for a given registered object, or None if not set.
+        Follows the same version resolution as `get()`: explicit → alias → latest.
+        """
+        if nspace not in NS:
+            raise ValueError(f"Unknown namespace: {nspace}")
+        key = (nspace, name)
+        with self._lock:
+            versions = self._store.get(key)
+            if not versions:
+                return None
+
+            ver = version
+            # resolve aliases or default to latest
+            ver = self._aliases.get(key, {}).get(ver, ver) if ver else self._latest.get(key)
+            if ver is None:
+                return None
+
+            return self._meta.get((nspace, name, ver))
+
+    # ---------- list typed ----------
+    def list_tools(self) -> dict[str, str]:
+        return self.list(nspace="tool")
+
+    def list_graphs(self) -> dict[str, str]:
+        return self.list(nspace="graph")
+
+    def list_graphfns(self) -> dict[str, str]:
+        return self.list(nspace="graphfn")
+
+    def list_agents(self) -> dict[str, str]:
+        # Return {'agent:<id>': '<latest_version>'}
+        return self.list(nspace="agent")
+
+    def list_apps(self) -> dict[str, str]:
+        # Return {'app:<id>': '<latest_version>'}
+        return self.list(nspace="app")
+
     # ---------- helpers ----------
 
     @staticmethod