aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/services/logger/compat.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import logging
+
+from .std import LoggingConfig, StdLoggerService
+
+"""For backward compatibility with v2 LoggerFactory interface. Delegates to StdLoggerService under the hood. Will deprecate in future."""
+
+
+def build_logging(force: bool = True, cfg: LoggingConfig | None = None) -> logging.Logger:
+    """
+    Back-compat entry point. Returns the base logger (as before), but created via StdLoggerService.
+    `force` is kept for signature parity; handlers are already reset in StdLoggerService.build().
+    """
+    svc = StdLoggerService.build(cfg)
+    return svc.base()
+
+
+class LoggerFactory:
+    """
+    Back-compat API that delegates to StdLoggerService.
+    """
+
+    def __init__(self, base: logging.Logger | None = None, *, cfg: LoggingConfig | None = None):
+        self._svc = (
+            StdLoggerService.build(cfg)
+            if base is None
+            else StdLoggerService(base, cfg=cfg or LoggingConfig.from_env())
+        )
+        self.base = self._svc.base()  # keep original attr for callers that relied on it
+
+    def for_node(self, node_id: str) -> logging.Logger:
+        return self._svc.for_node(node_id)
+
+    def for_inspect(self) -> logging.Logger:
+        return self._svc.for_inspect()
+
+    def for_run(self) -> logging.Logger:
+        return self._svc.for_run()
+
+    def for_scheduler(self) -> logging.Logger:
+        return self._svc.for_scheduler()
+
+    def for_node_ctx(
+        self, *, run_id: str, node_id: str, graph_id: str | None = None
+    ) -> logging.Logger:
+        return self._svc.for_node_ctx(run_id=run_id, node_id=node_id, graph_id=graph_id)
+
+    def for_run_ctx(self, *, run_id: str, graph_id: str | None = None) -> logging.Logger:
+        return self._svc.for_run_ctx(run_id=run_id, graph_id=graph_id)

aethergraph/services/logger/formatters.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import time
+from typing import Any
+
+
+class SafeFormatter(logging.Formatter):
+    """
+    Text formatter that won't explode if `extra` keys are missing.
+    Use %(run_id)s etc. in format strings without having to always bind them.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Provide default values for our known keys so %()s doesn't KeyError
+        for k in ("run_id", "node_id", "graph_id", "agent_id"):
+            if not hasattr(record, k):
+                setattr(record, k, "-")
+        return super().format(record)
+
+
+class JsonFormatter(logging.Formatter):
+    """
+    Structured JSON logs; safe for missing extras.
+    """
+
+    def __init__(self, *, include_timestamp: bool = True):
+        super().__init__()
+        self.include_timestamp = include_timestamp
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        if self.include_timestamp:
+            payload["time"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(record.created))
+        # standard attrs we care about
+        payload.update(
+            {
+                "run_id": getattr(record, "run_id", None),
+                "node_id": getattr(record, "node_id", None),
+                "graph_id": getattr(record, "graph_id", None),
+                "agent_id": getattr(record, "agent_id", None),
+            }
+        )
+        if record.exc_info:
+            payload["exc_info"] = self.formatException(record.exc_info)
+        return json.dumps({k: v for k, v in payload.items() if v is not None}, ensure_ascii=False)
+
+
+class ColorFormatter(SafeFormatter):
+    """
+    Console/file formatter that adds ANSI color only to:
+      - level name (INFO/WARNING/ERROR/...)
+      - run_id / node_id / graph_id tokens
+
+    Everything else stays uncolored.
+    """
+
+    RESET = "\033[0m"
+    LEVEL_COLORS = {
+        "DEBUG": "\033[36m",  # cyan
+        "INFO": "\033[32m",  # green
+        "WARNING": "\033[33m",  # yellow
+        "ERROR": "\033[31m",  # red
+        "CRITICAL": "\033[41m",  # red background
+    }
+
+    ID_COLOR = "\033[35m"  # magenta for IDs
+
+    def __init__(self, fmt: str, datefmt: str | None = None, use_color: bool | None = None):
+        super().__init__(fmt, datefmt=datefmt)
+        # auto-disable color if not a TTY unless explicitly forced
+        if use_color is None:
+            use_color = sys.stderr.isatty()
+        self.use_color = use_color
+
+    def format(self, record: logging.LogRecord) -> str:
+        # First let SafeFormatter fill in missing run_id/node_id/etc
+        base = super().format(record)
+
+        if not self.use_color:
+            return base
+
+        reset = self.RESET
+        level = record.levelname
+        level_color = self.LEVEL_COLORS.get(level, "")
+
+        # 1) Color only the level name token (first occurrence)
+        if level_color:
+            base = base.replace(level, f"{level_color}{level}{reset}", 1)
+
+        # 2) Color run_id / node_id / graph_id tokens like `run=...`, `node=...`, `graph=...`
+        id_color = self.ID_COLOR
+        for key in ("run_id", "node_id", "graph_id"):
+            val = getattr(record, key, None)
+            if val and val != "-":
+                token = f"{key}={val}"
+                colored = f"{id_color}{token}{reset}"
+                base = base.replace(token, colored)
+
+        return base

aethergraph/services/logger/std.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+import logging
+import logging.handlers
+import os
+from pathlib import Path
+import queue
+
+from aethergraph.config.config import AppSettings
+
+from .base import LogContext, LoggerService
+from .formatters import ColorFormatter, JsonFormatter, SafeFormatter
+
+
+def _ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+@dataclass(frozen=True)
+class LoggingConfig:
+    """
+    Configure sinks & formats.
+
+    Attributes:
+      root_ns: base logger name to use (`aethergraph`).
+      level: default level for root logger.
+      log_dir: directory for file logs (rotated).
+      use_json: True => JSON logs for files; console stays text by default.
+      enable_queue: True => offload file IO via QueueHandler/Listener (non-blocking).
+      per_namespace_levels: optional map (e.g. {"aethergraph.node": "DEBUG"}).
+      console_pattern: text format string for console.
+      file_pattern: text format string for file when use_json=False.
+      max_bytes / backup_count: rotation for file handlers.
+    """
+
+    root_ns: str = "aethergraph"
+    level: str = "INFO"
+    log_dir: str = "./logs"
+    use_json: bool = False
+    enable_queue: bool = False
+    per_namespace_levels: Mapping[str, str] = None
+    console_pattern: str = (
+        "%(asctime)s %(levelname)s \t%(name)s    run=%(run_id)s    node=%(node_id)s - %(message)s"
+    )
+    file_pattern: str = (
+        "%(asctime)s %(levelname)s %(name)s %(run_id)s %(node_id)s %(graph_id)s %(message)s"
+    )
+    max_bytes: int = 10 * 1024 * 1024
+    backup_count: int = 5
+
+    # external loggers
+    external_level: str = "WARNING"
+    quiet_loggers: tuple[str, ...] = ("httpx", "faiss", "faiss.loader")
+
+    @staticmethod
+    def from_env() -> LoggingConfig:
+        return LoggingConfig(
+            root_ns=os.getenv("AETHERGRAPH_LOG_ROOT", "aethergraph"),
+            level=os.getenv("AETHERGRAPH_LOG_LEVEL", "INFO"),
+            log_dir=os.getenv("AETHERGRAPH_LOG_DIR", "./logs"),
+            use_json=os.getenv("AETHERGRAPH_LOG_JSON", "0") == "1",
+            enable_queue=os.getenv("AETHERGRAPH_LOG_ASYNC", "0") == "1",
+        )
+
+    @staticmethod
+    def from_cfg(cfg: AppSettings, log_dir: str | None = None) -> LoggingConfig:
+        return LoggingConfig(
+            root_ns=cfg.logging.nspace or "aethergraph",
+            level=cfg.logging.level,
+            log_dir=log_dir or "./logs",
+            use_json=cfg.logging.json_logs,
+            enable_queue=cfg.logging.enable_queue,
+            external_level=cfg.logging.external_level,
+            quiet_loggers=tuple(cfg.logging.quiet_loggers),
+        )
+
+
+class _ContextAdapter(logging.LoggerAdapter):
+    """
+    Injects contextual fields into LogRecord via `extra`.
+    Preserves original logger API (info, debug, etc.).
+    """
+
+    def process(self, msg, kwargs):
+        extra = kwargs.get("extra") or {}
+        merged = {**self.extra, **extra}
+        kwargs["extra"] = merged
+        return msg, kwargs
+
+
+class StdLoggerService(LoggerService):
+    """
+    • text/JSON formatters
+    • per-namespace levels
+    • optional async file IO via QueueHandler
+    • context helpers (with_context / for_*_ctx)
+    """
+
+    def __init__(self, base: logging.Logger, *, cfg: LoggingConfig):
+        self._base = base
+        self._cfg = cfg
+
+    # --- LoggerService interface ---
+
+    def base(self) -> logging.Logger:
+        return self._base
+
+    def for_namespace(self, ns: str) -> logging.Logger:
+        return self._base.getChild(ns)
+
+    def with_context(self, logger: logging.Logger, ctx: LogContext) -> logging.Logger:
+        return _ContextAdapter(logger, ctx.as_extra())
+
+    # Back-compat helpers
+    def for_node(self, node_id: str) -> logging.Logger:
+        return self.for_namespace(f"node.{node_id}")
+
+    def for_run(self) -> logging.Logger:
+        return self.for_namespace("run")
+
+    def for_inspect(self) -> logging.Logger:
+        return self.for_namespace("inspect")
+
+    def for_scheduler(self) -> logging.Logger:
+        return self.for_namespace("scheduler")
+
+    def for_node_ctx(
+        self, *, run_id: str, node_id: str, graph_id: str | None = None
+    ) -> logging.Logger:
+        base = self.for_node(node_id)
+        return self.with_context(
+            base, LogContext(run_id=run_id, node_id=node_id, graph_id=graph_id)
+        )
+
+    def for_run_ctx(self, *, run_id: str, graph_id: str | None = None) -> logging.Logger:
+        base = self.for_run()
+        return self.with_context(base, LogContext(run_id=run_id, graph_id=graph_id))
+
+    # --- builder ---
+
+    @staticmethod
+    def build(cfg: LoggingConfig | None = None) -> StdLoggerService:
+        cfg = cfg or LoggingConfig.from_env()
+
+        root = logging.getLogger(cfg.root_ns)
+        # Reset handlers if rebuilding (idempotent server restarts)
+        for h in list(root.handlers):
+            root.removeHandler(h)
+        root.setLevel(getattr(logging, cfg.level.upper(), logging.INFO))
+        root.propagate = False
+
+        # Per-namespace levels
+        if cfg.per_namespace_levels:
+            for ns, lvl in cfg.per_namespace_levels.items():
+                logging.getLogger(ns).setLevel(getattr(logging, str(lvl).upper(), logging.INFO))
+
+        # Console handler (text)
+        console = logging.StreamHandler()
+        console.setLevel(getattr(logging, cfg.level.upper(), logging.INFO))
+        console.setFormatter(ColorFormatter(cfg.console_pattern))
+        root.addHandler(console)
+
+        # File handler (rotating)
+        _ensure_dir(Path(cfg.log_dir))
+        file_path = Path(cfg.log_dir) / "aethergraph.log"
+
+        if cfg.enable_queue:
+            # Non-blocking file IO
+            q = queue.Queue(-1)
+            qh = logging.handlers.QueueHandler(q)
+            root.addHandler(qh)
+
+            fh = logging.handlers.RotatingFileHandler(
+                file_path, maxBytes=cfg.max_bytes, backupCount=cfg.backup_count, encoding="utf-8"
+            )
+            if cfg.use_json:
+                fh.setFormatter(JsonFormatter())
+            else:
+                fh.setFormatter(SafeFormatter(cfg.file_pattern))
+            fh.setLevel(getattr(logging, cfg.level.upper(), logging.INFO))
+            listener = logging.handlers.QueueListener(q, fh, respect_handler_level=True)
+            listener.daemon = True
+            listener.start()
+        else:
+            fh = logging.handlers.RotatingFileHandler(
+                file_path, maxBytes=cfg.max_bytes, backupCount=cfg.backup_count, encoding="utf-8"
+            )
+            if cfg.use_json:
+                fh.setFormatter(JsonFormatter())
+            else:
+                fh.setFormatter(SafeFormatter(cfg.file_pattern))
+            fh.setLevel(getattr(logging, cfg.level.upper(), logging.INFO))
+            root.addHandler(fh)
+
+        ext_level = getattr(logging, cfg.external_level.upper(), logging.WARNING)
+        for name in cfg.quiet_loggers:
+            lg = logging.getLogger(name)
+            lg.setLevel(ext_level)
+            lg.propagate = True
+
+        return StdLoggerService(root, cfg=cfg)

aethergraph/services/mcp/helpers.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import logging
+
+from aethergraph.core.runtime.node_context import NodeContext
+
+logger = logging.getLogger("aethergraph.services.mcp.helpers")
+
+
+async def mcp_call_logged(context: NodeContext, server: str, tool: str, params: dict | None = None):
+    client = context.mcp(server)
+    res = await client.call(tool, params or {})
+    try:
+        await context.mem().write_result(
+            topic=f"mcp.{server}.{tool}",
+            inputs=[{"name": "args", "kind": "json", "value": params or {}}],
+            outputs=[{"name": "result", "kind": "json", "value": res}],
+            tags=["mcp", "tool_call"],
+            message=f"MCP {server}:{tool}",
+        )
+    except Exception:
+        logger.warning("Failed to log MCP tool call result")
+    return res

aethergraph/services/mcp/http_client.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+import httpx
+
+from aethergraph.contracts.services.mcp import MCPClientProtocol, MCPResource, MCPTool
+
+
+class HttpMCPClient(MCPClientProtocol):
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = 60.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.headers = {"Content-Type": "application/json"}
+        if headers:
+            self.headers.update(headers)
+        self.timeout = timeout
+
+        self._client: httpx.AsyncClient | None = None
+        self._id = 0
+        self._lock = asyncio.Lock()
+
+    async def open(self):
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+
+    async def close(self):
+        if self._client is not None:
+            try:
+                await self._client.aclose()
+            finally:
+                self._client = None
+
+    async def _ensure(self):
+        if self._client is None:
+            await self.open()
+
+    async def _rpc(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        await self._ensure()
+        async with self._lock:
+            self._id += 1
+            req = {"jsonrpc": "2.0", "id": self._id, "method": method, "params": params or {}}
+            assert self._client is not None
+            r = await self._client.post(
+                f"{self.base_url}/rpc", headers=self.headers, content=json.dumps(req)
+            )
+            r.raise_for_status()
+            resp = r.json()
+            if "error" in resp:
+                raise RuntimeError(str(resp["error"]))
+            return resp.get("result")
+
+    async def list_tools(self) -> list[MCPTool]:
+        return await self._rpc("tools/list")
+
+    async def call(self, tool: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self._rpc("tools/call", {"name": tool, "arguments": params or {}})
+
+    async def list_resources(self) -> list[MCPResource]:
+        return await self._rpc("resources/list")
+
+    async def read_resource(self, uri: str) -> dict[str, Any]:
+        return await self._rpc("resources/read", {"uri": uri})

aethergraph/services/mcp/mcp_tools.py

@@ -0,0 +1,21 @@
+from services.mcp.helpers import mcp_call_logged
+
+from aethergraph import NodeContext, tool
+
+
+@tool(outputs=["result"], name="mcp.call", version="0.1.0")
+async def mcp_call(server: str, tool_name: str, args: dict | None = None, *, context: NodeContext):
+    out = await mcp_call_logged(context, server, tool_name, args or {})
+    await context.channel().send_text(f"🔌 MCP {server}:{tool_name} ✓")
+    return {"result": out}
+
+
+@tool(outputs=["tools"], name="mcp.list_tools", version="0.1.0")
+async def mcp_list_tools(server: str, *, context: NodeContext):
+    tools = await context.mcp(server).list_tools()
+    await context.mem().write_result(
+        topic=f"mcp.{server}.list_tools",
+        outputs=[{"name": "tools", "kind": "json", "value": tools}],
+        tags=["mcp"],
+    )
+    return {"tools": tools}

aethergraph/services/mcp/registry.py

@@ -0,0 +1,14 @@
+from contracts.services.mcp import MCPClientProtocol
+
+
+class MCPRegistry:
+    def __init__(self):
+        self._clients: dict[str, MCPClientProtocol] = {}
+
+    def register(self, name: str, client: MCPClientProtocol):
+        self._clients[name] = client
+
+    def get(self, name: str) -> MCPClientProtocol:
+        if name not in self._clients:
+            raise KeyError(f"MCP server '{name}' not registered")
+        return self._clients[name]

aethergraph/services/mcp/service.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aethergraph.contracts.services.mcp import MCPClientProtocol, MCPResource, MCPTool
+
+logger = logging.getLogger("aethergraph.services.mcp")
+
+
+class MCPService:
+    """
+    Holds many MCP clients (stdio/ws) under names, manages lifecycle, and
+    provides thin convenience helpers (open/close/call/list_tools).
+    """
+
+    def __init__(self, clients: dict[str, MCPClientProtocol] | None = None, *, secrets=None):
+        self._clients: dict[str, MCPClientProtocol] = clients or {}
+        self._secrets = secrets  # optional (Secrets provider) Not implemented here
+
+    # ---- registration ----
+    def register(self, name: str, client: MCPClientProtocol) -> None:
+        self._clients[name] = client
+
+    def remove(self, name: str) -> None:
+        self._clients.pop(name, None)
+
+    def has(self, name: str) -> bool:
+        return name in self._clients
+
+    def names(self) -> list[str]:
+        return list(self._clients.keys())
+
+    def list_clients(self) -> list[str]:
+        return list(self._clients.keys())
+
+    def get(self, name: str = "default") -> MCPClientProtocol:
+        if name not in self._clients:
+            raise KeyError(f"Unknown MCP server '{name}'")
+        return self._clients[name]
+
+    # ---- lifecycle ----
+    async def open(self, name: str) -> None:
+        await self.get(name).open()
+
+    async def close(self, name: str) -> None:
+        try:
+            await self.get(name).close()
+        except Exception:
+            logger.warning(f"Failed to close MCP client '{name}'")
+
+    async def open_all(self) -> None:
+        for n in self._clients:
+            await self._clients[n].open()
+
+    async def close_all(self) -> None:
+        for n in self._clients:
+            try:
+                await self._clients[n].close()
+            except Exception:
+                logger.warning(f"Failed to close MCP client '{n}'")
+
+    # ---- call helpers (optional, keeps call sites tiny) ----
+    async def call(
+        self, name: str, tool: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        # lazy-open on first use; clients themselves also lazy-reconnect
+        c = self.get(name)
+        await c.open()
+        return await c.call(tool, params or {})
+
+    async def list_tools(self, name: str) -> list[MCPTool]:
+        c = self.get(name)
+        await c.open()
+        return await c.list_tools()
+
+    async def list_resources(self, name: str) -> list[MCPResource]:
+        c = self.get(name)
+        await c.open()
+        return await c.list_resources()
+
+    async def read_resource(self, name: str, uri: str) -> dict[str, Any]:
+        c = self.get(name)
+        await c.open()
+        return await c.read_resource(uri)
+
+    # ---- optional secrets helpers  ----
+    def set_header(self, name: str, key: str, value: str) -> None:
+        """For ws clients: set/override a header at runtime (demo/notebook UX)."""
+        c = self.get(name)
+        # duck-typing for ws client
+        if hasattr(c, "headers") and isinstance(c.headers, dict):  # type: ignore[attr-defined]
+            c.headers[key] = value  # type: ignore[attr-defined]
+        else:
+            raise RuntimeError(f"MCP '{name}' does not support headers")
+
+    def persist_secret(self, secret_name: str, value: str) -> None:
+        if not self._secrets or not hasattr(self._secrets, "set"):
+            raise RuntimeError("Secrets provider is not writable")
+        self._secrets.set(secret_name, value)  # type: ignore

aethergraph/services/mcp/stdio_client.py

@@ -0,0 +1,70 @@
+import asyncio
+import json
+import os
+from typing import Any
+
+from aethergraph.contracts.services.mcp import MCPClientProtocol, MCPResource, MCPTool
+
+
+class StdioMCPClient(MCPClientProtocol):
+    def __init__(self, cmd: list[str], env: dict[str, str] | None = None, timeout: float = 60.0):
+        """MCP client that talks to a subprocess over stdio using JSON-RPC 2.0.
+        Args:
+            cmd: Command to start the MCP server subprocess (list of str).
+            env: Optional environment variables to set for the subprocess.
+            timeout: Timeout in seconds for each RPC call.
+        """
+        self.cmd, self.env, self.timeout = cmd, env or {}, timeout
+        self.proc = None
+        self._id = 0
+        self._lock = asyncio.Lock()
+
+    async def open(self):
+        if self.proc:
+            return
+        self.proc = await asyncio.create_subprocess_exec(
+            *self.cmd,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env={**os.environ, **self.env},
+        )
+
+    async def close(self):
+        if not self.proc:
+            return
+        try:
+            self.proc.terminate()
+        except Exception:
+            self.logger.warning("mcp_stdio_terminate_failed")
+
+        self.proc = None
+
+    async def _rpc(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        await self.open()
+        async with self._lock:
+            self._id += 1
+            req = {"jsonrpc": "2.0", "id": self._id, "method": method, "params": params or {}}
+            data = (json.dumps(req) + "\n").encode("utf-8")
+            assert self.proc and self.proc.stdin and self.proc.stdout
+            self.proc.stdin.write(data)
+            await self.proc.stdin.drain()
+            line = await asyncio.wait_for(self.proc.stdout.readline(), timeout=self.timeout)
+            if not line:
+                raise RuntimeError("MCP server closed")
+            resp = json.loads(line.decode("utf-8"))
+            if "error" in resp:
+                raise RuntimeError(str(resp["error"]))
+            return resp.get("result")
+
+    async def list_tools(self) -> list[MCPTool]:
+        return await self._rpc("tools/list")
+
+    async def call(self, tool: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self._rpc("tools/call", {"name": tool, "arguments": params or {}})
+
+    async def list_resources(self) -> list[MCPResource]:
+        return await self._rpc("resources/list")
+
+    async def read_resource(self, uri: str) -> dict[str, Any]:
+        return await self._rpc("resources/read", {"uri": uri})