aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/runtime/__init__.py

@@ -0,0 +1,62 @@
+# redirect runtime service imports for clean imports
+
+from aethergraph.core.runtime.ad_hoc_context import open_session
+from aethergraph.core.runtime.runtime_services import (
+    # logger service helpers
+    current_logger_factory,
+    current_services,
+    ensure_services_installed,
+    # channel service helpers
+    get_channel_service,
+    get_default_channel,
+    get_ext_context_service,
+    # llm service helpers
+    get_llm_service,
+    get_mcp_service,
+    # general service management
+    install_services,
+    list_ext_context_services,
+    list_mcp_clients,
+    register_channel_adapter,
+    # external context service helpers
+    register_context_service,
+    register_llm_client,
+    register_mcp_client,
+    set_channel_alias,
+    set_default_channel,
+    # mcp service helpers
+    set_mcp_service,
+    set_rag_index_backend,
+    set_rag_llm_client,
+)
+
+__all__ = [
+    # general service management
+    "install_services",
+    "ensure_services_installed",
+    "current_services",
+    # channel service helpers
+    "get_channel_service",
+    "set_default_channel",
+    "get_default_channel",
+    "set_channel_alias",
+    "register_channel_adapter",
+    # llm service helpers
+    "get_llm_service",
+    "register_llm_client",
+    "set_rag_llm_client",
+    "set_rag_index_backend",
+    # logger service helpers
+    "current_logger_factory",
+    # external context service helpers
+    "register_context_service",
+    "get_ext_context_service",
+    "list_ext_context_services",
+    # mcp service helpers
+    "set_mcp_service",
+    "get_mcp_service",
+    "register_mcp_client",
+    "list_mcp_clients",
+    # ad-hoc context
+    "open_session",
+]

aethergraph/server/__init__.py

@@ -0,0 +1,3 @@
+from .start import start_server, start_server_async, stop_server
+
+__all__ = ["start_server", "start_server_async", "stop_server"]

aethergraph/server/app_factory.py

@@ -0,0 +1,84 @@
+import asyncio
+from typing import Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from aethergraph.config.config import AppSettings
+from aethergraph.utils.optdeps import require
+
+from ..core.runtime.runtime_services import install_services
+
+# channel routes
+from ..services.container.default_container import build_default_container
+
+
+def create_app(
+    *,
+    workspace: str = "./aethergraph_data",
+    cfg: Optional["AppSettings"] = None,
+    log_level: str = "info",
+) -> FastAPI:
+    """
+    Builds the FastAPI app, registers routers, and installs all services
+    into app.state.container (and globally via install_services()).
+    """
+    app = FastAPI(title="AetherGraph Sidecar", version="0.1")
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:5173"],  # dev UI origin
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Resolve settings early, so we can conditionally include routers
+    settings = cfg or AppSettings()
+    app.state.settings = settings
+
+    # --- Routers (HTTP transports) ---
+    # For now, we can just always include; or gate it with a flag like settings.slack.use_webhook.
+    # app.include_router(slack_router)     # HTTP /slack/events + /slack/interact
+    # app.include_router(console_router)
+    # app.include_router(telegram_router)
+    # app.include_router(webui_router)
+
+    # override log level in config
+    settings.logging.level = log_level
+
+    # ---- Services container ----
+    container = build_default_container(root=workspace, cfg=settings)
+    app.state.container = container
+
+    # install globally so run()/tools see the same services
+    install_services(container)
+
+    # ---- External channel transports (Socket Mode, polling, etc.) ----
+    @app.on_event("startup")
+    async def start_external_transports():
+        slack_cfg = settings.slack
+        if (
+            slack_cfg
+            and slack_cfg.enabled
+            and slack_cfg.socket_mode_enabled
+            and slack_cfg.bot_token
+            and slack_cfg.app_token
+        ):
+            require("slack_sdk", "slack")
+            from ..plugins.channel.websockets.slack_ws import SlackSocketModeRunner
+
+            runner = SlackSocketModeRunner(container=container, settings=settings)
+            app.state.slack_socket_runner = runner
+            asyncio.create_task(runner.start())
+
+        # Telegram polling for local / dev
+        tg_cfg = settings.telegram
+        if tg_cfg and tg_cfg.enabled and tg_cfg.polling_enabled and tg_cfg.bot_token:
+            from ..plugins.channel.websockets.telegram_polling import TelegramPollingRunner
+
+            tg_runner = TelegramPollingRunner(container=container, settings=settings)
+            app.state.telegram_polling_runner = tg_runner
+            asyncio.create_task(tg_runner.start())
+
+    return app

aethergraph/server/start.py

@@ -0,0 +1,122 @@
+# aethergraph/start.py
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import socket
+import threading
+
+import uvicorn
+
+from aethergraph.config.context import set_current_settings
+from aethergraph.config.loader import load_settings
+
+from ..plugins.channel.routes.webui_routes import install_web_channel
+from .app_factory import create_app
+
+_started = False
+_server_thread: threading.Thread | None = None
+_shutdown_flag = threading.Event()
+_url: str | None = None
+
+
+def _pick_free_port(p: int) -> int:
+    if p:
+        return p
+    s = socket.socket()
+    s.bind(("", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def _run_uvicorn_in_thread(app, host: str, port: int, log_level: str):
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    server = uvicorn.Server(
+        uvicorn.Config(app, host=host, port=port, log_level=log_level, loop="asyncio")
+    )
+
+    async def runner():
+        task = asyncio.create_task(server.serve())
+        while not _shutdown_flag.is_set():
+            await asyncio.sleep(0.2)
+        if not server.should_exit:
+            server.should_exit = True
+        await task
+
+    try:
+        loop.run_until_complete(runner())
+    finally:
+        loop.stop()
+        loop.close()
+
+
+def start_server(
+    *,
+    workspace: str = "./aethergraph_data",
+    host: str = "127.0.0.1",
+    port: int = 8000,  # 0 = auto free port
+    log_level: str = "warning",
+    unvicorn_log_level: str = "warning",
+    return_container: bool = False,
+) -> str:
+    """
+    Start the AetherGraph sidecar server in a background thread and install
+    services using the given workspace. Safe to call at top of any script
+    or notebook cell (no main() wrapper needed). Returns base URL.
+    """
+    global _started, _server_thread, _url
+    if _started:
+        return _url  # type: ignore
+
+    # Build app (installs services inside create_app)
+    cfg = load_settings()
+    set_current_settings(cfg)
+
+    app = create_app(workspace=workspace, cfg=cfg, log_level=log_level)
+
+    picked_port = _pick_free_port(port)
+    t = threading.Thread(
+        target=_run_uvicorn_in_thread,
+        args=(app, host, picked_port, unvicorn_log_level),
+        name="aethergraph-sidecar",
+        daemon=True,
+    )
+    t.start()
+
+    _server_thread = t
+    _started = True
+    _url = f"http://{host}:{picked_port}"
+
+    install_web_channel(app)
+
+    if return_container:
+        return _url, app.state.container
+    return _url
+
+
+async def start_server_async(**kw) -> str:
+    # Async-friendly wrapper; still uses a thread to avoid clashing with caller loop
+    return start_server(**kw)
+
+
+def stop_server():
+    """Optional: stop the background server (useful in tests)."""
+    global _started, _server_thread, _url
+    if not _started:
+        return
+    _shutdown_flag.set()
+    if _server_thread and _server_thread.is_alive():
+        with contextlib.suppress(Exception):
+            _server_thread.join(timeout=5)
+    _started = False
+    _server_thread = None
+    _url = None
+    _shutdown_flag.clear()
+
+
+# backward compatibility
+start = start_server
+stop = stop_server
+start_async = start_server_async

aethergraph/services/__init__.py

@@ -0,0 +1,10 @@
+# redirect runtime.Service imports for clean imports
+from aethergraph.core.runtime.base_service import Service
+from aethergraph.services.mcp.http_client import HttpMCPClient
+
+# import mcp-related services
+from aethergraph.services.mcp.service import MCPService
+from aethergraph.services.mcp.stdio_client import StdioMCPClient
+from aethergraph.services.mcp.ws_client import WsMCPClient
+
+__all__ = ["HttpMCPClient", "MCPService", "Service", "StdioMCPClient", "WsMCPClient"]

aethergraph/services/artifacts/facade.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import builtins
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from aethergraph.contracts.services.artifacts import (
+    Artifact,
+    AsyncArtifactIndex,
+    AsyncArtifactStore,
+)
+
+from .paths import _from_uri_or_path
+
+Scope = Literal["node", "run", "graph", "all"]
+
+
+class ArtifactFacade:
+    """Facade for artifact storage and indexing operations within a specific context.
+    Provides async methods to stage, ingest, save, and write artifacts with automatic indexing.
+    """
+
+    def __init__(
+        self,
+        *,
+        run_id: str,
+        graph_id: str,
+        node_id: str,
+        tool_name: str,
+        tool_version: str,
+        store: AsyncArtifactStore,
+        index: AsyncArtifactIndex,
+    ):
+        self.run_id, self.graph_id, self.node_id = run_id, graph_id, node_id
+        self.tool_name, self.tool_version = tool_name, tool_version
+        self.store, self.index = store, index
+        self.last_artifact: Artifact | None = None
+
+    async def stage(self, ext: str = "") -> str:
+        return await self.store.plan_staging_path(ext)
+
+    async def ingest(
+        self,
+        staged_path: str,
+        *,
+        kind: str,
+        labels=None,
+        metrics=None,
+        suggested_uri: str | None = None,
+        pin: bool = False,
+    ):
+        a = await self.store.ingest_staged_file(
+            staged_path=staged_path,
+            kind=kind,
+            run_id=self.run_id,
+            graph_id=self.graph_id,
+            node_id=self.node_id,
+            tool_name=self.tool_name,
+            tool_version=self.tool_version,
+            labels=labels,
+            metrics=metrics,
+            suggested_uri=suggested_uri,
+            pin=pin,
+        )
+        await self.index.upsert(a)
+        await self.index.record_occurrence(a)
+        return a
+
+    async def save(
+        self,
+        path: str,
+        *,
+        kind: str,
+        labels=None,
+        metrics=None,
+        suggested_uri: str | None = None,
+        pin: bool = False,
+    ):
+        a = await self.store.save_file(
+            path=path,
+            kind=kind,
+            run_id=self.run_id,
+            graph_id=self.graph_id,
+            node_id=self.node_id,
+            tool_name=self.tool_name,
+            tool_version=self.tool_version,
+            labels=labels,
+            metrics=metrics,
+            suggested_uri=suggested_uri,
+            pin=pin,
+        )
+        await self.index.upsert(a)
+        await self.index.record_occurrence(a)
+        self.last_artifact = a
+        return a
+
+    async def save_text(self, payload: str, *, suggested_uri: str | None = None):
+        a = await self.store.save_text(payload=payload, suggested_uri=suggested_uri)
+        await self.index.upsert(a)
+        await self.index.record_occurrence(a)
+        self.last_artifact = a
+        return a
+
+    async def save_json(self, payload: dict, *, suggested_uri: str | None = None):
+        a = await self.store.save_json(payload=payload, suggested_uri=suggested_uri)
+        await self.index.upsert(a)
+        await self.index.record_occurrence(a)
+        self.last_artifact = a
+        return a
+
+    @asynccontextmanager
+    async def writer(self, *, kind: str, planned_ext: str | None = None, pin: bool = False):
+        # Use the store's (sync) contextmanager via async wrapper; user writes bytes
+        cm = await self.store.open_writer(
+            kind=kind,
+            run_id=self.run_id,
+            graph_id=self.graph_id,
+            node_id=self.node_id,
+            tool_name=self.tool_name,
+            tool_version=self.tool_version,
+            planned_ext=planned_ext,
+            pin=pin,
+        )
+        with cm as w:
+            yield w
+            a = getattr(w, "_artifact", None)
+        if a:
+            await self.index.upsert(a)
+            await self.index.record_occurrence(a)
+            self.last_artifact = a
+        else:
+            self.last_artifact = None
+
+    async def stage_dir(self, suffix: str = "") -> str:
+        return await self.store.plan_staging_dir(suffix)
+
+    async def ingest_dir(self, staged_dir: str, **kw):
+        a = await self.store.ingest_directory(
+            staged_dir=staged_dir,
+            run_id=self.run_id,
+            graph_id=self.graph_id,
+            node_id=self.node_id,
+            tool_name=self.tool_name,
+            tool_version=self.tool_version,
+            **kw,
+        )
+        await self.index.upsert(a)
+        await self.index.record_occurrence(a)
+        self.last_artifact = a
+        return a
+
+    async def tmp_path(self, suffix: str = "") -> str:
+        return await self.store.plan_staging_path(suffix)
+
+    async def load_bytes(self, uri: str) -> bytes:
+        return await self.store.load_bytes(uri)
+
+    async def load_text(self, uri: str, *, encoding: str = "utf-8", errors: str = "strict") -> str:
+        data = await self.store.load_text(uri)
+        return data
+
+    async def load_json(self, uri: str, *, encoding: str = "utf-8", errors: str = "strict") -> Any:
+        data = await self.store.load_json(uri, encoding=encoding, errors=errors)
+        return data
+
+    async def load_artifact(self, uri: str) -> Any:
+        return await self.store.load_artifact(uri)
+
+    async def load_artifact_bytes(self, uri: str) -> bytes:
+        return await self.store.load_artifact_bytes(uri)
+
+    # ------- indexing pass-throughs with scoping -------
+    async def list(self, *, scope: Scope = "run") -> builtins.list[Artifact]:
+        """
+        Quick listing scoped to current run/graph/node by default.
+        scope:
+          - "node": filter by (run_id, graph_id, node_id)
+          - "graph": filter by (run_id, graph_id)
+          - "run": filter by (run_id)   [default]
+          - "all": no implicit filters (dangerous; use sparingly)
+        """
+        if scope == "node":
+            arts = await self.index.search(
+                labels={"graph_id": self.graph_id, "node_id": self.node_id}
+            )
+            return [a for a in arts if a.run_id == self.run_id]
+        if scope == "graph":
+            arts = await self.index.search(labels={"graph_id": self.graph_id})
+            return [a for a in arts if a.run_id == self.run_id]
+        if scope == "run":
+            return await self.index.list_for_run(self.run_id)
+        if scope == "all":
+            return await self.index.search()
+        return await self.index.search(labels=self._scope_labels(scope))
+
+    async def search(
+        self,
+        *,
+        kind: str | None = None,
+        labels: dict[str, Any] | None = None,
+        metric: str | None = None,
+        mode: Literal["max", "min"] | None = None,
+        scope: Scope = "run",
+        extra_scope_labels: dict[str, Any] | None = None,
+    ) -> builtins.list[Artifact]:
+        """Pass-through search with automatic scoping."""
+        eff_labels = dict(labels or {})
+        if scope in ("node", "graph", "project"):
+            eff_labels.update(self._scope_labels(scope))
+        if extra_scope_labels:
+            eff_labels.update(extra_scope_labels)
+        # Delegate heavy lifting to the index
+        return await self.index.search(kind=kind, labels=eff_labels, metric=metric, mode=mode)
+
+    async def best(
+        self,
+        *,
+        kind: str,
+        metric: str,
+        mode: Literal["max", "min"],
+        scope: Scope = "run",
+        filters: dict[str, Any] | None = None,
+    ) -> Artifact | None:
+        eff_filters = dict(filters or {})
+        if scope in ("node", "graph", "project"):
+            eff_filters.update(self._scope_labels(scope))
+        return await self.index.best(
+            kind=kind, metric=metric, mode=mode, filters=eff_filters or None
+        )
+
+    async def pin(self, artifact_id: str, pinned: bool = True) -> None:
+        await self.index.pin(artifact_id, pinned)
+
+    # -------- internal helpers --------
+    def _scope_labels(self, scope: Scope) -> dict[str, Any]:
+        if scope == "node":
+            return {"run_id": self.run_id, "graph_id": self.graph_id, "node_id": self.node_id}
+        if scope == "graph":
+            return {"run_id": self.run_id, "graph_id": self.graph_id}
+        if scope == "run":
+            return {"run_id": self.run_id}
+        return {}  # "all"
+
+    def _project_id(self) -> str | None:
+        # This function is no longer used, but kept for possible future use.
+        return getattr(self, "project_id", None)
+
+    # ---------- convenience: URI -> local path (FS only) ----------
+    def to_local_path(self, uri_or_path: str | Path | Artifact, *, must_exist: bool = True) -> str:
+        """
+        Return an absolute native path string if input is a file:// URI or local path.
+        If given an Artifact, uses artifact.uri.
+        If the scheme is not file://, returns the string form unchanged (or raise in strict mode).
+        """
+        s = uri_or_path.uri or "" if isinstance(uri_or_path, Artifact) else str(uri_or_path)
+
+        p = _from_uri_or_path(s).resolve()
+
+        # If not a file:// (e.g., s3://, http://), _from_uri_or_path returns Path(s);
+        # detect that and either pass through or raise for clarity.
+        u = urlparse(s)
+        if "://" in s and (u.scheme or "").lower() != "file":
+            # Not a filesystem artifact; caller likely needs a downloader
+            return s  # or: raise ValueError("Not a local filesystem URI")
+
+        if must_exist and not p.exists():
+            raise FileNotFoundError(f"Local path not found: {p}")
+        return str(p)
+
+    def to_local_file(self, uri_or_path: str | Path | Artifact, *, must_exist: bool = True) -> str:
+        """Same as to_local_path but asserts it's a file (not a dir)."""
+        p = Path(self.to_local_path(uri_or_path, must_exist=must_exist))
+        if must_exist and not p.is_file():
+            raise IsADirectoryError(f"Expected file, got directory: {p}")
+        return str(p)
+
+    def to_local_dir(self, uri_or_path: str | Path | Artifact, *, must_exist: bool = True) -> str:
+        """Same as to_local_path but asserts it's a directory."""
+        p = Path(self.to_local_path(uri_or_path, must_exist=must_exist))
+        if must_exist and not p.is_dir():
+            raise NotADirectoryError(f"Expected directory, got file: {p}")
+        return str(p)

aethergraph/services/artifacts/factory.py

@@ -0,0 +1,35 @@
+import os
+
+from .fs_store import FSArtifactStore
+from .jsonl_index import JsonlArtifactIndex
+from .sqlite_index import SqliteArtifactIndex  # if present
+
+
+def make_artifact_store() -> FSArtifactStore:
+    base = os.getenv("ARTIFACTS_DIR", "./artifacts")
+    return FSArtifactStore(base)
+
+
+def make_artifact_index():
+    kind = (os.getenv("ARTIFACT_INDEX", "jsonl")).lower()
+    if kind == "sqlite":
+        path = os.getenv("ARTIFACT_INDEX_SQLITE", "./artifacts/index.sqlite")
+        return SqliteArtifactIndex(path)
+    path = os.getenv("ARTIFACT_INDEX_JSONL", "./artifacts/index.jsonl")
+    return JsonlArtifactIndex(path)
+
+
+def make_facade_for_node(*, env, node, store=None, index=None):
+    store = store or make_artifact_store()
+    index = index or make_artifact_index()
+    from aethergraph.services.artifacts.facade import ArtifactFacade
+
+    return ArtifactFacade(
+        run_id=env.run_id,
+        graph_id=env.graph_id,
+        node_id=node.node_id,
+        tool_name=node.tool_name,
+        tool_version=node.tool_version,
+        store=store,
+        index=index,
+    )