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

aethergraph/core/runtime/runtime_services.py

@@ -5,26 +5,45 @@ from pathlib import Path
 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
 
 _current = ContextVar("aeg_services", default=None)
 # process-wide fallback (handles contextvar boundary issues)
 _services_global: Any = None
+# allow registering external services before main services are ready
+_pending_ext_services: dict[str, Any] = {}
 
 
 def install_services(services: Any) -> None:
-    global _services_global
+    global _services_global, _pending_ext_services
     _services_global = services
+
+    # Attach any services that were registered before install_services().
+    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 = {}
+
     return _current.set(services)
 
 
 def ensure_services_installed(factory: Callable[[], Any]) -> Any:
-    global _services_global
+    global _services_global, _pending_ext_services
     svc = _current.get() or _services_global
     if svc is None:
         svc = factory()
         _services_global = svc
-    _current.set(svc)  # keep ContextVar in sync for this context
+
+        # hydrate pending external services here too
+        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 = {}
+    _current.set(svc)
     return svc
 
 
@@ -174,33 +193,182 @@ def current_logger_factory() -> Any:
 
 
 # --------- External context services ---------
-def register_context_service(name: str, service: Any) -> None:
-    svc = current_services()
+def register_context_service(name: str, service: Service) -> None:
+    """
+    Register an external service for NodeContext access.
+
+    This function attaches an external service to the current service container
+    under the specified name. If no container is installed yet, the service is
+    stashed in a pending registry and will be attached automatically when
+    install_services() is called.
+
+    Examples:
+        Register a custom database service:
+        ```python
+        register_context_service("mydb", MyDatabaseService())
+        ```
+
+    Args:
+        name: The unique string identifier for the external service.
+        service: The service instance to register.
+
+    Returns:
+        None
+
+    Notes:
+        - If called before install_services(), the service will be attached later.
+        - Services are accessible via NodeContext.ext_services[name].
+    """
+    global _pending_ext_services
+
+    try:
+        svc = current_services()
+    except RuntimeError:
+        # No container yet: keep it in the staging area.
+        _pending_ext_services[name] = service
+        return
+
+    # Container exists: attach immediately.
     svc.ext_services[name] = service
 
 
-def get_ext_context_service(name: str) -> Any:
+def get_ext_context_service(name: str) -> Service:
+    """
+    Retrieve an external context service by name.
+
+    This function returns the external service registered under the given name
+    from the current service container's ext_services registry.
+
+    Examples:
+        Access a registered service:
+        ```python
+        mydb = get_ext_context_service("mydb")
+        ```
+
+    Args:
+        name: The string name of the external service to retrieve.
+
+    Returns:
+        The service instance registered under the given name, or None if not found.
+
+    Raises:
+        RuntimeError: If no services container is installed.
+    """
     svc = current_services()
     return svc.ext_services.get(name)
 
 
 def list_ext_context_services() -> list[str]:
+    """
+    List all registered external context service names.
+
+    This function returns a list of all names for services currently registered
+    in the ext_services registry of the current service container.
+
+    Examples:
+        List all available external services:
+        ```python
+        services = list_ext_context_services()
+        print(services)
+        ```
+
+    Args:
+        None
+
+    Returns:
+        A list of strings representing the names of all registered external services.
+        Returns an empty list if no services are registered.
+
+    Raises:
+        RuntimeError: If no services container is installed.
+    """
     svc = current_services()
     return list(svc.ext_services.keys())
 
 
 # --------- MCP service helpers ---------
 def set_mcp_service(mcp_service: Any) -> None:
+    """
+    Set the MCP service in the current service container.
+
+    This function assigns the provided MCP service instance to the current application's
+    service container, making it available for subsequent MCP client registrations and lookups.
+
+    Examples:
+        ```python
+        from aethergraph.runtime import set_mcp_service
+        set_mcp_service(MyMCPService())
+        ```
+
+    Args:
+        mcp_service: An instance implementing the MCP service interface.
+
+    Returns:
+        None
+
+    Notes:
+        - This should be called once during application startup before registering MCP clients.
+        - This is an internal function; users typically interact with MCP services via higher-level APIs.
+    """
     svc = current_services()
     svc.mcp = mcp_service
 
 
 def get_mcp_service() -> Any:
+    """
+    Retrieve the currently configured MCP service.
+
+    This function returns the MCP service instance from the current application's
+    service container. It is used to access MCP-related functionality throughout the app.
+
+    Examples:
+        ```python
+        mcp = get_mcp_service()
+        ```
+
+    Args:
+        None
+
+    Returns:
+        The MCP service instance currently set in the service container.
+
+    Raises:
+        RuntimeError: If no MCP service has been set.
+
+    Notes:
+        - Ensure that set_mcp_service() has been called during application initialization.
+        - This is an internal function; users typically interact with MCP services via higher-level APIs.
+    """
     svc = current_services()
     return svc.mcp
 
 
 def register_mcp_client(name: str, client: Any) -> None:
+    """
+    Register a new MCP client with the current MCP service.
+
+    This function adds a client instance to the MCP service under the specified name,
+    allowing it to be accessed and managed by the MCP infrastructure.
+
+    Examples:
+        ```python
+        from aethergraph.runtime import register_mcp_client
+        from aethergraph.services.mcp import HttpMCPClient
+        my_client = HttpMCPClient("https://mcp.example.com", ...)
+        register_mcp_client("myclient", my_client)
+        ```
+
+    Args:
+        name: The unique name to associate with the MCP client.
+        client: The client instance to register.
+
+    Returns:
+        None
+
+    Raises:
+        RuntimeError: If no MCP service has been installed via set_mcp_service().
+
+    """
     svc = current_services()
     if svc.mcp is None:
         raise RuntimeError("No MCP service installed. Call set_mcp_service() first.")
@@ -208,6 +376,26 @@ def register_mcp_client(name: str, client: Any) -> None:
 
 
 def list_mcp_clients() -> list[str]:
+    """
+    List all registered MCP client names in the current MCP service.
+
+    This function returns a list of all client names that have been registered
+    with the MCP service, allowing for discovery and management of available clients.
+
+    Examples:
+        ```python
+        from aethergraph.runtime import list_mcp_clients
+        clients = list_mcp_clients()
+        print(clients)
+        ```
+
+    Args:
+        None
+
+    Returns:
+        A list of strings representing the names of registered MCP clients.
+        Returns an empty list if no MCP service is installed or no clients are registered.
+    """
     svc = current_services()
     if svc.mcp:
         return svc.mcp.list_clients()

aethergraph/core/tools/builtins/toolset.py

@@ -77,7 +77,7 @@ async def ask_files(
 
 @tool(name="send_text", outputs=["ok"])
 async def send_text(
-    *, text: str, meta: dict[str, Any] | None = None, channel: str | None = None, context=None
+    text: str, *, meta: dict[str, Any] | None = None, channel: str | None = None, context=None
 ):
     ch = context.channel(channel)
     await ch.send_text(text, meta=meta or {})

aethergraph/core/tools/toolkit.py

@@ -141,11 +141,16 @@ def tool(
         # registry behavior
         registry = current_registry()
         if registry is not None:
+            meta = {
+                "kind": "tool",
+                "tags": [],
+            }
             registry.register(
                 nspace="tool",
                 name=name or getattr(impl, "__name__", "tool"),
                 version=version,
                 obj=impl,
+                meta=meta,
             )
 
         return proxy

aethergraph/plugins/agents/default_chat_agent copy.py

@@ -0,0 +1,90 @@
+# aethergraph/examples/agents/default_chat_agent.py (or similar)
+
+from __future__ import annotations
+
+from typing import Any
+
+from aethergraph import NodeContext, graph_fn
+from aethergraph.plugins.agents.shared import build_session_memory_prompt_segments
+
+
+@graph_fn(
+    name="default_chat_agent",
+    inputs=["message", "files", "session_id", "user_meta"],
+    outputs=["reply"],
+    as_agent={
+        "id": "chat_agent",
+        "title": "Chat",
+        "description": "Built-in chat agent that uses the configured LLM.",
+        "icon": "message-circle",
+        "color": "sky",
+        "session_kind": "chat",
+        "mode": "chat_v1",
+        "memory_level": "session",
+        "memory_scope": "session.global",
+    },
+)
+async def default_chat_agent(
+    message: str,
+    files: list[Any] | None = None,
+    session_id: str | None = None,
+    user_meta: dict[str, Any] | None = None,
+    context_refs: list[dict[str, Any]] | None = None,
+    *,
+    context: NodeContext,
+):
+    """
+    Simple built-in chat agent:
+
+    - Takes {message, files}
+    - Calls the configured LLM
+    - Uses shared session memory (summary + recent events) in the prompt.
+    """
+
+    llm = context.llm()
+    chan = context.ui_session_channel()
+
+    # 1) Build memory segments for this session
+    session_summary, recent_events = await build_session_memory_prompt_segments(
+        context,
+        summary_tag="session",
+        recent_limit=12,
+    )
+
+    # print("Session summary:", session_summary)
+    # print("Recent events:", recent_events)
+
+    # 2) System + user messages (you can move this into PromptStore later)
+    system_prompt = (
+        "You are AetherGraph's built-in session helper.\n\n"
+        "You can see a short summary of the session and a few recent events from all agents.\n"
+        "Use them to answer questions about previous steps or runs, but do not invent details.\n"
+        "If you are unsure, say that clearly.\n"
+        "When return math or code snippets, use markdown formatting.\n"
+        "Math formatting rules:\n"
+        "- Use LaTeX math delimiters:\n"
+        "  - Inline: \\( ... \\)  (no extra spaces right after \\( or before \\))\n"
+        "  - Display: $$ ... $$  (for standalone equations)\n"
+    )
+
+    memory_context = ""
+    if session_summary:
+        memory_context += f"Session summary:\n{session_summary}\n\n"
+    if recent_events:
+        memory_context += f"Recent events:\n{recent_events}\n\n"
+
+    user_prompt = f"{memory_context}" "User message:\n" f"{message}\n"
+
+    # 3) Call LLM with chat-style API
+    resp, _usage = await llm.chat(
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+    )
+
+    await chan.send_text(resp)
+
+    return {
+        "reply": resp,
+    }

aethergraph/plugins/agents/default_chat_agent.py

@@ -0,0 +1,171 @@
+# aethergraph/examples/agents/default_chat_agent.py (or similar)
+
+from __future__ import annotations
+
+from typing import Any
+
+from aethergraph import NodeContext, graph_fn
+
+
+@graph_fn(
+    name="default_chat_agent",
+    inputs=["message", "files", "session_id", "user_meta"],
+    outputs=["reply"],
+    as_agent={
+        "id": "chat_agent",
+        "title": "Chat",
+        "short_description": "General-purpose chat agent.",
+        "description": "Built-in chat agent that uses the configured LLM and memory across sessions.",
+        "icon": "message-circle",
+        "color": "sky",
+        "session_kind": "chat",
+        "mode": "chat_v1",
+        "memory_level": "session",
+        "memory_scope": "session.global",
+    },
+)
+async def default_chat_agent(
+    message: str,
+    files: list[Any] | None = None,
+    session_id: str | None = None,
+    user_meta: dict[str, Any] | None = None,
+    context_refs: list[dict[str, Any]] | None = None,
+    *,
+    context: NodeContext,
+):
+    """
+    Built-in chat agent with session memory:
+
+    - Hydrates long-term + recent chat memory into the prompt.
+    - Records user and assistant messages as chat.turn events.
+    - Periodically distills chat history into long-term summaries.
+    """
+
+    llm = context.llm()
+    chan = context.ui_session_channel()
+
+    mem = context.memory()
+
+    # 1) Build memory segments for this session
+    long_term_summary: str = ""
+    recent_chat: list[dict[str, Any]] = []
+
+    """
+    Build prompt segments:    
+    {
+        "long_term": "<combined summary text or ''>",
+        "recent_chat": [ {ts, role, text, tags}, ... ],
+        "recent_tools": [ {ts, tool, message, inputs, outputs, tags}, ... ]
+    }
+    """
+    segments = await mem.build_prompt_segments(
+        recent_chat_limit=20,
+        include_long_term=True,
+        summary_tag="session",
+        max_summaries=3,
+        include_recent_tools=False,
+    )
+    long_term_summary = segments.get("long_term") or ""
+    recent_chat = segments.get("recent_chat") or []
+
+    # 2) System prompt
+    system_prompt = (
+        "You are AetherGraph's built-in session helper.\n\n"
+        "You can see a summary of the session and some recent messages.\n"
+        "Use them to answer questions about previous steps or runs, but do not invent details.\n"
+        "If you are unsure, say that clearly.\n"
+        # "When returning math or code snippets, use markdown formatting.\n"
+    )
+
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": system_prompt},
+    ]
+
+    # Inject long-term summary as a system message (if present)
+    if long_term_summary:
+        messages.append(
+            {
+                "role": "system",
+                "content": "Summary of previous context:\n" + long_term_summary,
+            }
+        )
+
+    # Inject recent chat as prior turns
+    for item in recent_chat:
+        role = item.get("role") or "user"
+        text = item.get("text") or ""
+        # Map non-standard roles (e.g. "tool") to "assistant" for chat APIs
+        mapped_role = role if role in {"user", "assistant", "system"} else "assistant"
+        if text:
+            messages.append({"role": mapped_role, "content": text})
+
+    # Add some lightweight metadata about files / context refs into the user message
+    meta_lines: list[str] = []
+    if files:
+        meta_lines.append(f"(User attached {len(files)} file(s).)")
+    if context_refs:
+        meta_lines.append(f"(User attached {len(context_refs)} context reference(s).)")
+    meta_block = ""
+    if meta_lines:
+        meta_block = "\n\n" + "\n".join(meta_lines)
+
+    user_content = f"{message}{meta_block}"
+
+    # 3) Record the user message into memory
+    user_data: dict[str, Any] = {}
+    if files:
+        # Store only lightweight file metadata; avoid huge payloads
+        user_data["files"] = [
+            {k: v for k, v in (f or {}).items() if k in {"name", "url", "mimetype", "size"}}
+            for f in files
+        ]
+    if context_refs:
+        user_data["context_refs"] = context_refs
+
+    await mem.record_chat_user(
+        message,
+        data=user_data,
+        tags=["session.chat"],
+    )
+
+    # Append current user message to LLM prompt
+    messages.append({"role": "user", "content": user_content})
+    # 4) Call LLM with chat-style API
+    resp, _usage = await llm.chat(
+        messages=messages,
+    )
+
+    # 5) Record assistant reply into memory and run simple distillation policy
+    try:
+        await mem.record_chat_assistant(
+            resp,
+            tags=["session.chat"],
+        )
+
+        # Simple distillation policy:
+        # If we have "enough" chat turns in recent history, run a long-term summary.
+        recent_for_distill = await mem.recent_chat(limit=120)
+        if len(recent_for_distill) >= 80:
+            # Non-LLM summarizer by default; flip use_llm=True later.
+            await mem.distill_long_term(
+                summary_tag="session",
+                summary_kind="long_term_summary",
+                include_kinds=["chat.turn"],
+                include_tags=["chat"],
+                max_events=200,
+                use_llm=False,
+            )
+    except Exception:
+        # Memory issues should never break the chat agent
+        import traceback
+
+        trace = traceback.format_exc()
+        logger = context.logger()
+        logger.warning("Chat agent memory record/distill error:\n" + trace)
+
+    # 6) Send reply to UI channel
+    await chan.send_text(resp)
+
+    return {
+        "reply": resp,
+    }

aethergraph/plugins/agents/shared.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from aethergraph import NodeContext
+
+
+async def build_session_memory_prompt_segments(
+    context: NodeContext,
+    *,
+    summary_tag: str = "session",
+    recent_limit: int = 12,
+) -> tuple[str, str]:
+    """
+    Build reusable 'memory segments' for LLM prompts:
+
+      - session_summary: long-term summary text (may be empty)
+      - recent_events: short list of recent events (chat, status, etc.)
+
+    Any agent that wants cross-agent memory can call this, then
+    feed these into its LLM prompt or structured prompt store.
+
+    The underlying MemoryFacade is responsible for:
+    - Choosing a scope_id (usually tied to the session).
+    - Storing summaries in DocStore (mem/{scope_id}/summaries/{tag}/...).
+    - Exposing hotlog events via mem.recent().
+    """
+    mem = None
+    try:
+        mem = context.memory()
+    except TypeError:
+        # Depending on how NodeContext is wired, .memory might be property or method
+        mem = getattr(context, "memory", None)
+
+    if mem is None:
+        return "", ""
+
+    # ---- 1) Long-term session summary (if summarization has been run) ----
+    session_summary = ""
+    try:
+        summary = await mem.soft_hydrate_last_summary(
+            summary_tag=summary_tag,
+            summary_kind="long_term_summary",
+        )
+        if summary:
+            session_summary = summary.get("text") or ""
+    except Exception as e:
+        logger = getattr(context, "logger", None)
+        if logger:
+            logger.warning(
+                "build_session_memory_prompt_segments: soft_hydrate_last_summary failed",
+                extra={"error": str(e)},
+            )
+
+    # ---- 2) Recent events across runs/agents in this session ----
+    recent_events = ""
+    try:
+        events = await mem.recent(kinds=None, limit=recent_limit)
+        lines: list[str] = []
+        for evt in events:
+            kind = getattr(evt, "kind", None) or "event"
+            text = getattr(evt, "text", None)
+            data = getattr(evt, "data", None)
+
+            # Try to recover some text from data if text is empty
+            if not text and isinstance(data, dict):
+                text = data.get("text") or data.get("message") or data.get("summary")
+
+            if not text:
+                continue
+
+            # Keep it short-ish; you can truncate here if needed
+            lines.append(f"[{kind}] {text}")
+        recent_events = "\n".join(lines)
+    except Exception as e:
+        logger = getattr(context, "logger", None)
+        if logger:
+            logger.warning(
+                "build_session_memory_prompt_segments: mem.recent failed",
+                extra={"error": str(e)},
+            )
+
+    return session_summary, recent_events