aethergraph 0.1.0a2__py3-none-any.whl → 0.1.0a4__py3-none-any.whl

aethergraph/core/runtime/run_types.py

@@ -1,6 +1,7 @@
-from dataclasses import dataclass, field
+from dataclasses import asdict, dataclass, field, is_dataclass
 from datetime import datetime
 from enum import Enum
+import json
 from typing import Any
 
 # used to represent the status of a run, primiarily used in endpoint with RunManager
@@ -87,3 +88,55 @@ class SessionKind(str, Enum):
     playground = "playground"
     notebook = "notebook"
     pipline = "pipeline"  # future
+
+
+MAX_PREVIEW_CHARS = 16_000  # tune as you like
+
+
+def _to_json_ish(obj: Any) -> Any:
+    """
+    Best-effort conversion of arbitrary Python objects to something JSON-ish.
+    This is ONLY for UI preview, never for planner semantics.
+    """
+    if obj is None:
+        return None
+    if isinstance(obj, (str, int, float, bool)):  # noqa: UP038
+        return obj
+    if isinstance(obj, (list, tuple, set)):  # noqa: UP038
+        return [_to_json_ish(x) for x in obj]
+    if isinstance(obj, dict):
+        return {str(k): _to_json_ish(v) for k, v in obj.items()}
+    if is_dataclass(obj):
+        return _to_json_ish(asdict(obj))
+
+    # Optional: numpy handling
+    try:
+        import numpy as np  # type: ignore
+
+        if isinstance(obj, np.ndarray):
+            return {
+                "__ndarray__": True,
+                "shape": obj.shape,
+                "dtype": str(obj.dtype),
+                "preview": _to_json_ish(obj.flatten()[:10].tolist()),
+            }
+    except Exception:
+        pass
+
+    return repr(obj)
+
+
+def _make_preview(obj: Any, max_chars: int = MAX_PREVIEW_CHARS) -> tuple[str, bool]:
+    """
+    Returns (preview_str, truncated_flag).
+    Never used for planning; only for UI.
+    """
+    jsonish = _to_json_ish(obj)
+    try:
+        s = json.dumps(jsonish, ensure_ascii=False)
+    except TypeError:
+        s = repr(jsonish)
+    truncated = len(s) > max_chars
+    if truncated:
+        s = s[:max_chars] + "... (truncated)"
+    return s, truncated

aethergraph/core/runtime/runtime_env.py

@@ -17,6 +17,7 @@ from aethergraph.services.continuations.stores.fs_store import (
 )
 
 # ---- memory services ----
+from aethergraph.services.indices.scoped_indices import ScopedIndices
 from aethergraph.services.memory.facade import MemoryFacade
 from aethergraph.services.rag.node_rag import NodeRAG
 from aethergraph.services.resume.router import ResumeRouter
@@ -118,6 +119,18 @@ class RuntimeEnv:
             "entities": [],
         }
 
+        node_scope = (
+            self.container.scope_factory.for_node(
+                identity=self.identity,
+                run_id=self.run_id,
+                graph_id=self.graph_id,
+                node_id=node.node_id,
+                session_id=self.session_id,
+            )
+            if self.container.scope_factory
+            else None
+        )
+
         level, custom_scope_id = self._resolve_memory_config()
         mem_scope = (
             self.container.scope_factory.for_memory(
@@ -133,24 +146,25 @@ class RuntimeEnv:
             else None
         )
 
+        indices: ScopedIndices | None = None  # scoped indices for this node
+        if self.container.global_indices is not None and node_scope is not None:
+            # Attach scoped indices to container for this node's scope
+            # Prefer memory scope id if available for memory-tied corpora
+            base_scope = mem_scope or node_scope
+            if base_scope:
+                scope_id = mem_scope.memory_scope_id() if mem_scope else None
+                indices = self.container.global_indices.for_scope(
+                    scope=base_scope,
+                    scope_id=scope_id,
+                )
+
         mem: MemoryFacade = self.memory_factory.for_session(
             run_id=self.run_id,
             graph_id=self.graph_id,
             node_id=node.node_id,
             session_id=self.session_id,
             scope=mem_scope,
-        )
-
-        node_scope = (
-            self.container.scope_factory.for_node(
-                identity=self.identity,
-                run_id=self.run_id,
-                graph_id=self.graph_id,
-                node_id=node.node_id,
-                session_id=self.session_id,
-            )
-            if self.container.scope_factory
-            else None
+            scoped_indices=indices,
         )
 
         from aethergraph.services.artifacts.facade import ArtifactFacade
@@ -161,8 +175,9 @@ class RuntimeEnv:
             node_id=node.node_id,
             tool_name=node.tool_name,
             tool_version=node.tool_version,  # to be filled from node if available
-            store=self.artifacts,
-            index=self.artifact_index,
+            art_store=self.artifacts,
+            art_index=self.artifact_index,
+            scoped_indices=indices,
             scope=node_scope,
         )
 
@@ -202,6 +217,12 @@ class RuntimeEnv:
             rag=rag_for_node,  # RAGService
             mcp=self.mcp_service,  # MCPService
             run_manager=self.container.run_manager,  # RunManager
+            indices=indices,  # ScopedIndices for this node
+            execution=self.container.execution
+            if self.container.execution is not None
+            else None,  # ExecutionService
+            planner_service=self.container.planner_service,
+            skills=self.container.skills_registry,
         )
         return ExecutionContext(
             run_id=self.run_id,

aethergraph/core/runtime/runtime_services.py

@@ -2,11 +2,14 @@ from collections.abc import Callable
 from contextlib import contextmanager
 from contextvars import ContextVar
 from pathlib import Path
+from threading import RLock
 from typing import Any
 
 from aethergraph.contracts.services.llm import LLMClientProtocol
 from aethergraph.core.runtime.base_service import Service
 from aethergraph.services.llm.generic_client import GenericLLMClient
+from aethergraph.services.skills.skill_registry import SkillRegistry
+from aethergraph.services.skills.skills import Skill
 
 _current = ContextVar("aeg_services", default=None)
 # process-wide fallback (handles contextvar boundary issues)
@@ -15,18 +18,72 @@ _services_global: Any = None
 _pending_ext_services: dict[str, Any] = {}
 
 
+_pending_lock = RLock()
+
+# Ordered operations (some things depend on earlier steps)
+_pending_ops_order: list[str] = []
+# Keyed storage so repeated registrations overwrite instead of duplicating
+_pending_ops: dict[str, Callable[[Any], Any]] = {}
+# Optional: store results if you want “handles” later
+_pending_results: dict[str, Any] = {}
+
+
+def _defer_op(key: str, op: Callable[[Any], Any]) -> None:
+    """Register (or replace) a deferred operation."""
+    with _pending_lock:
+        if key not in _pending_ops:
+            _pending_ops_order.append(key)
+        _pending_ops[key] = op
+
+
+def _flush_pending_ops(services: Any) -> None:
+    """Apply all deferred operations once services exist."""
+    with _pending_lock:
+        keys = list(_pending_ops_order)
+        _pending_ops_order.clear()
+        ops = _pending_ops.copy()
+        _pending_ops.clear()
+
+    for key in keys:
+        op = ops.get(key)
+        if op is None:
+            continue
+        try:
+            _pending_results[key] = op(services)
+        except Exception:
+            # You can choose to log here instead of raising,
+            # but raising is usually better so startup fails loudly.
+            raise
+
+
+def _try_apply_or_defer(key: str, fn: Callable[[Any], Any]) -> Any | None:
+    """
+    If services installed: run now and return result.
+    Else: defer it and return None.
+    """
+    try:
+        svc = current_services()
+    except RuntimeError:
+        _defer_op(key, fn)
+        return None
+    else:
+        return fn(svc)
+
+
 def install_services(services: Any) -> None:
     global _services_global, _pending_ext_services
     _services_global = services
 
-    # Attach any services that were registered before install_services().
+    # Attach pending ext services (your existing behavior)
     ext = getattr(services, "ext_services", None)
     if isinstance(ext, dict) and _pending_ext_services:
-        # Don't clobber anything that was already present.
         for name, svc in _pending_ext_services.items():
             ext.setdefault(name, svc)
         _pending_ext_services = {}
 
+    # NEW: apply all other pending mutations
+    _flush_pending_ops(services)
+
     return _current.set(services)
 
 
@@ -37,12 +94,16 @@ def ensure_services_installed(factory: Callable[[], Any]) -> Any:
         svc = factory()
         _services_global = svc
 
-        # hydrate pending external services here too
+        # hydrate pending external services
         ext = getattr(svc, "ext_services", None)
         if isinstance(ext, dict) and _pending_ext_services:
             for name, s in _pending_ext_services.items():
                 ext.setdefault(name, s)
             _pending_ext_services = {}
+
+        # NEW: apply pending ops on first creation too
+        _flush_pending_ops(svc)
+
     _current.set(svc)
     return svc
 
@@ -72,9 +133,10 @@ def get_channel_service() -> Any:
 
 
 def set_default_channel(key: str) -> None:
-    svc = current_services()
-    svc.channels.set_default_channel_key(key)
-    return
+    def _op(svc: Any) -> None:
+        svc.channels.set_default_channel_key(key)
+
+    return _try_apply_or_defer(key, _op)
 
 
 def get_default_channel() -> str:
@@ -89,7 +151,7 @@ def set_channel_alias(alias: str, channel_key: str) -> None:
 
 def register_channel_adapter(name: str, adapter: Any) -> None:
     svc = current_services()
-    svc.channel.register_adapter(name, adapter)
+    svc.channels.register_adapter(name, adapter)
 
 
 # --------- LLM service helpers ---------
@@ -107,17 +169,20 @@ def register_llm_client(
     api_key: str | None = None,
     timeout: float | None = None,
 ) -> None:
-    svc = current_services()
-    client = svc.llm.configure_profile(
-        profile=profile,
-        provider=provider,
-        model=model,
-        embed_model=embed_model,
-        base_url=base_url,
-        api_key=api_key,
-        timeout=timeout,
-    )
-    return client
+    def _op(svc: Any) -> LLMClientProtocol:
+        client = svc.llm.configure_profile(
+            profile=profile,
+            provider=provider,
+            model=model,
+            embed_model=embed_model,
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+        )
+        return client
+
+    key = f"llm_client:profile={profile}:provider={provider}:model={model}"
+    return _try_apply_or_defer(key, _op)
 
 
 # backend compatibility
@@ -402,6 +467,231 @@ def list_mcp_clients() -> list[str]:
     return []
 
 
+# --------- Skill registry helpers ---------
+def get_skill_registry() -> SkillRegistry:
+    svc = current_services()
+    return svc.skills_registry
+
+
+def register_skill(skill: Skill, *, overwrite: bool = False) -> Skill:
+    """
+    Register an existing Skill object into the global registry.
+
+    This method adds a `Skill` instance to the global `SkillRegistry`, making it
+    available for use throughout the application. The `overwrite` flag determines
+    whether an existing skill with the same ID will be replaced.
+
+    Examples:
+        Registering a skill object:
+        ```python
+        skill = Skill(id="example.skill", title="Example Skill")
+        register_skill(skill)
+        ```
+
+        Overwriting an existing skill:
+        ```python
+        skill = Skill(id="example.skill", title="Updated Skill")
+        register_skill(skill, overwrite=True)
+        ```
+
+    Args:
+        skill: The `Skill` object to register.
+        overwrite: Whether to overwrite an existing skill with the same ID. Default is `False`.
+
+    Returns:
+        Skill: The registered `Skill` instance.
+
+    """
+
+    def _op(svc: Any) -> "Skill":
+        reg = svc.skills_registry
+        reg.register(skill, overwrite=overwrite)
+        return skill
+
+    # Key should be stable and allow overwriting the deferred op if called again.
+    # Usually skill.id is the right identity here.
+    key = f"skills:obj:{skill.id}:overwrite={overwrite}"
+    return _try_apply_or_defer(key, _op)
+
+
+def register_skill_inline(
+    *,
+    id: str,
+    title: str,
+    description: str = "",
+    tags: list[str] | None = None,
+    domain: str | None = None,
+    modes: list[str] | None = None,
+    version: str | None = None,
+    config: dict[str, Any] | None = None,
+    sections: dict[str, str] | None = None,
+    overwrite: bool = False,
+) -> Skill:
+    """
+    Define and register a Skill entirely in Python.
+
+    This method allows you to define a Skill inline with all its metadata and sections,
+    and directly register it into the global Skill registry.
+
+    Examples:
+        Registering a skill with basic metadata and sections:
+        ```python
+        register_skill_inline(
+            id="surrogate.workflow",
+            title="Surrogate workflow planning",
+            description="Prompts and patterns for surrogate planning.",
+            tags=["surrogate", "planning"],
+            modes=["planning"],
+            sections={
+                "planning.header": "...",
+                "planning.binding_hints": "...",
+                "chat.system": "...",
+            },
+        )
+        ```
+
+    Args:
+        id (str): The unique identifier for the Skill. (Required)
+        title (str): A human-readable title for the Skill. (Required)
+        description (str): A short description of the Skill's purpose. (Optional)
+        tags (list[str]): A list of tags for categorization. (Optional)
+        domain (str): The domain or namespace for the Skill. (Optional)
+        modes (list[str]): The operational modes supported by the Skill. (Optional)
+        version (str): The version string for the Skill. (Optional)
+        config (dict[str, Any]): Additional configuration data. (Optional)
+        sections (dict[str, str]): A dictionary mapping section names to their content. (Optional)
+        overwrite (bool): Whether to overwrite an existing Skill with the same ID. (Optional)
+
+    Returns:
+        Skill: The registered Skill instance.
+    """
+
+    def _op(svc: Any) -> "Skill":
+        reg = svc.skills_registry
+        return reg.register_inline(
+            id=id,
+            title=title,
+            description=description,
+            tags=tags,
+            domain=domain,
+            modes=modes,
+            version=version,
+            config=config,
+            sections=sections,
+            overwrite=overwrite,
+        )
+
+    # Include overwrite, and optionally version to avoid surprising replacements.
+    key = f"skills:inline:{id}:overwrite={overwrite}:version={version or ''}"
+    return _try_apply_or_defer(key, _op)
+
+
+def register_skill_file(path: str | Path, *, overwrite: bool = False) -> Skill:
+    """
+    Load a single markdown skill file and register it.
+
+    This function processes a markdown file containing skill definitions and
+    registers it into the global skill registry. The file must adhere to the
+    expected format for parsing skill metadata and sections.
+
+    Examples:
+        Registering a skill from a markdown file:
+        ```python
+        skill = register_skill_file("skills/surrogate-workflow.md")
+        ```
+
+    Args:
+        path: The path to the markdown file to load.
+        overwrite: Whether to overwrite an existing skill with the same ID. (Optional, default: False)
+
+    Returns:
+        Skill: The registered `Skill` instance.
+
+    Notes:
+        To start the server and load all desired packages:
+        1. Open a terminal and navigate to the project directory.
+        2. Run the server using the appropriate command (e.g., `python -m aethergraph.server`).
+        3. Ensure all required dependencies are installed via `pip install -r requirements.txt`.
+
+    """
+
+    p = str(path)
+
+    def _op(svc: Any) -> Skill:
+        reg = svc.skills_registry
+        return reg.load_file(path, overwrite=overwrite)
+
+    p = str(path)
+
+    def _op(svc: Any) -> "Skill":
+        reg = svc.skills_registry
+        return reg.load_file(path, overwrite=overwrite)
+
+    key = f"skills:file:{p}:overwrite={overwrite}"
+    return _try_apply_or_defer(key, _op)
+
+
+def register_skills_from_path(
+    root: str | Path,
+    *,
+    pattern: str = "*.md",
+    recursive: bool = True,
+    overwrite: bool = False,
+) -> list[Skill]:
+    """
+    Load and register all skill markdown files under a directory.
+
+    This method scans the specified directory for markdown files matching the
+    given pattern, parses their content into `Skill` objects, and registers
+    them into the global skill registry. The directory can have a flat or
+    nested structure.
+
+    Examples:
+        Register all skills in a flat directory:
+        ```python
+        register_skills_from_path("skills/")
+        ```
+
+        Register skills in a nested directory structure:
+        ```python
+        register_skills_from_path("skills/", recursive=True)
+        ```
+
+        Use a custom file pattern to filter files:
+        ```python
+        register_skills_from_path("skills/", pattern="*.skill.md")
+        ```
+
+    Args:
+        root: The root directory to scan for skill files.
+        pattern: A glob pattern to match skill files. Default is `"*.md"`.
+        recursive: Whether to scan subdirectories recursively. Default is `True`.
+        overwrite: Whether to overwrite existing skills with the same ID. Default is `False`.
+
+    Returns:
+        list[Skill]: A list of all registered `Skill` objects.
+
+    Notes:
+        To start the server and load all desired packages:
+        1. Open a terminal and navigate to the project directory.
+        2. Run the server using the appropriate command (e.g., `python -m aethergraph.server`).
+        3. Ensure all required dependencies are installed via `pip install -r requirements.txt`.
+
+    """
+    root_str = str(root)
+
+    def _op(svc: Any) -> list[Skill]:
+        return svc.skills_registry.load_path(
+            root=root_str,
+            pattern=pattern,
+            recursive=recursive,
+            overwrite=overwrite,
+        )
+
+    key = f"skills:path:{root_str}:pattern={pattern}:recursive={recursive}:overwrite={overwrite}"
+    return _try_apply_or_defer(key, _op)
+
+
 # --------- Scheduler helpers --------- - (Not used)
 def ensure_global_scheduler_started() -> None:
     svc = current_services()