aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/__init__.py

@@ -0,0 +1,49 @@
+__version__ = "0.1.0a1"
+
+
+# Server
+# Channel buttons
+from .contracts.services.channel import Button
+
+# Graphs
+from .core.graph.graph_fn import graph_fn  # full-featured graph decorator
+from .core.graph.graphify import graphify  # graphify decorator to build TaskGraphs from functions
+from .core.graph.task_graph import (
+    TaskGraph,  # full task graph object for type checking, serialization, etc.
+)
+from .core.runtime.base_service import Service  # base service class for custom services
+
+# Runtime
+from .core.runtime.node_context import NodeContext  # per-node execution context (run_id)
+
+# Tools
+from .core.tools.toolkit import tool
+from .server.start import (
+    start_server,  # start a local sidecar server
+    start_server_async,  # async version of start_server
+    stop_server,  # stop the sidecar server
+)
+
+__all__ = [
+    # Server
+    "start_server",
+    "stop_server",
+    "start_server_async",
+    # Tools
+    "tool",
+    "graph_fn",
+    "graphify",
+    "TaskGraph",
+    "RuntimeEnv",
+    "NodeContext",
+    # Services
+    "Service",
+    # Channel buttons
+    "Button",
+]
+
+
+# Setup a default null logger to avoid "No handler found" warnings
+import logging
+
+logging.getLogger("aethergraph").addHandler(logging.NullHandler())

aethergraph/config/config.py

@@ -0,0 +1,121 @@
+# aethergraph/config.py
+from typing import Literal
+
+from pydantic import BaseModel, Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .llm import LLMSettings
+
+
+class LoggingSettings(BaseModel):
+    nspace: str = Field("aethergraph", description="Root logger namespace")
+    level: str = Field("INFO", description="Root log level")
+    json_logs: bool = Field(False, description="Emit JSON logs")
+    enable_queue: bool = Field(default=False, description="Enable async logging via queue")
+
+    external_level: str = Field("WARNING", description="Level for third-party loggers")
+    quiet_loggers: list[str] = Field(
+        default_factory=lambda: ["httpx", "faiss", "faiss.loader", "slack_sdk"],
+        description="Additional loggers to set to external_level",
+    )
+
+
+class SlackSettings(BaseModel):
+    # Turn Slack integration on/off globally
+    enabled: bool = Field(default=False)
+
+    # Tokens
+    bot_token: SecretStr | None = None  # xoxb-...
+    app_token: SecretStr | None = None  # xapp-... (Socket Mode)
+    signing_secret: SecretStr | None = None  # only needed for HTTP/webhook
+
+    # Transport mode flags
+    #
+    # Local / individual default:
+    #   enabled = true
+    #   socket_mode_enabled = true
+    #   webhook_enabled = false
+    #
+    # Production / webhook default:
+    #   enabled = true
+    #   socket_mode_enabled = false (optional)
+    #   webhook_enabled = true
+
+    socket_mode_enabled: bool = Field(
+        default=True, description="Use Slack Socket Mode (WS outbound) when app_token is set."
+    )
+    webhook_enabled: bool = Field(
+        default=False,
+        description="Expose /slack/events & /slack/interact HTTP endpoints for Slack.",
+    )
+
+    # Default routing
+    #
+    # For simple setups likely only need default_channel_id (+ maybe default_team_id).
+    # default_channel_key is the more general 'slack:team/T:chan/C' form.
+    # TODO: later we might deprecate the default setting in .env and require explicit channel keys in code.
+    default_team_id: str | None = None  # e.g. 'T...'
+    default_channel_id: str | None = None  # e.g. 'C...'
+    default_channel_key: str | None = None  # e.g. 'slack:team/T...:chan/C...'
+
+
+class TelegramSettings(BaseModel):
+    enabled: bool = Field(default=False)
+    bot_token: SecretStr | None = None
+
+    # for webhook mode
+    webhook_enabled: bool = False
+    webhook_secret: SecretStr | None = None  # used ONLY for HTTP webhook verification
+
+    # for local / dev mode
+    polling_enabled: bool = True  # use getUpdates loop by default for local
+
+    # default chat key
+    default_chat_id: str | None = None
+
+
+class ContinuationStoreSettings(BaseModel):
+    kind: Literal["fs", "inmem"] = "fs"
+    secret: SecretStr | None = None
+    root: str = "./artifacts/continuations"
+
+
+class MemorySettings(BaseModel):
+    hot_limit: int = 1000
+    hot_ttl_s: int = 7 * 24 * 3600
+    signal_threshold: float = 0.25
+
+
+class ChannelSettings(BaseModel):
+    # room for Telegram / Console etc.
+    default: str = "console:stdin"
+
+
+class RAGSettings(BaseModel):
+    root: str = "./aethergraph_data/rag"  # base dir for rag; should not use it unless customized
+    backend: str = "sqlite"  # "sqlite" | "faiss"
+    index_path: str | None = None  # defaults set at runtime if None
+    dim: int | None = None  # only for faiss; optional
+
+
+class AppSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="AETHERGRAPH_", env_nested_delimiter="__", extra="ignore", case_sensitive=False
+    )
+
+    # top-level for workspace root
+    root: str = "./aethergraph_data"
+
+    logging: LoggingSettings = LoggingSettings()
+    slack: SlackSettings = SlackSettings()
+    telegram: TelegramSettings = TelegramSettings()
+    llm: LLMSettings = LLMSettings()
+    cont: ContinuationStoreSettings = ContinuationStoreSettings()
+    memory: MemorySettings = MemorySettings()
+    channels: ChannelSettings = ChannelSettings()
+    rag: RAGSettings = RAGSettings()
+
+    # Future fields:
+    # authn: ...
+    # authz: ...
+    # tracer: ...

aethergraph/config/context.py

@@ -0,0 +1,16 @@
+from contextvars import ContextVar
+
+from .config import AppSettings
+
+_current_cfg: ContextVar[AppSettings | None] = ContextVar("current_cfg", default=None)
+
+
+def set_current_settings(cfg: AppSettings) -> None:
+    _current_cfg.set(cfg)
+
+
+def current_settings() -> AppSettings:
+    cfg = _current_cfg.get()
+    if cfg is None:
+        raise RuntimeError("Settings not installed. Call set_current_settings() at startup.")
+    return cfg

aethergraph/config/llm.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field, SecretStr
+
+from aethergraph.services.llm.providers import Provider
+
+
+class LLMProfile(BaseModel):
+    provider: Provider = "openai"
+    model: str = "gpt-4o-mini"
+    embed_model: str | None = None  # separate embedding model
+    base_url: str | None = None
+    timeout: float = 60.0
+
+    # provider-specific
+    azure_deployment: str | None = None
+
+    # secrets (either direct value or ref name)
+    api_key: SecretStr | None = None
+    api_key_ref: str | None = Field(
+        default=None, description="Name in secret store, e.g. 'OPENAI_API_KEY'"
+    )
+
+
+class LLMSettings(BaseModel):
+    enabled: bool = True
+    default: LLMProfile = LLMProfile()
+    profiles: dict[str, LLMProfile] = Field(default_factory=dict)

aethergraph/config/loader.py

@@ -0,0 +1,60 @@
+# aethergraph/config_loader.py
+from collections.abc import Iterable
+import logging
+import os
+from pathlib import Path
+
+from .config import AppSettings
+
+
+def _existing(paths: Iterable[Path]) -> list[Path]:
+    return [p for p in paths if p and p.exists()]
+
+
+def load_settings() -> AppSettings:
+    log = logging.getLogger("aethergraph.config.loader")
+
+    # 1) explicit override
+    explicit = os.getenv("AETHERGRAPH_ENV_FILE")
+    explicit_path = Path(explicit).expanduser().resolve() if explicit else None
+
+    # 2) execution context (project) – where user runs `python ...`
+    cwd = Path.cwd()
+
+    # 3) workspace-level (if user sets it)
+    workspace = Path(os.getenv("AETHERGRAPH_ROOT", "./aethergraph_data")).expanduser().resolve()
+
+    # 4) user config dir (~/.config/aethergraph/.env or XDG)
+    xdg = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")).expanduser().resolve()
+    user_cfg_env = xdg / "aethergraph" / ".env"
+
+    # Optional: keep a *repo dev* fallback if running from source
+    # (safe; only used if that path actually exists)
+    try:
+        repo_root = Path(__file__).resolve().parents[3]
+    except Exception:
+        repo_root = None
+    repo_env = (
+        (repo_root / ".env").resolve() if (repo_root and (repo_root / ".env").exists()) else None
+    )
+
+    candidates = _existing(
+        [
+            explicit_path or Path(),  # explicit if set
+            cwd / ".env",
+            cwd / ".env.local",
+            workspace / ".env",
+            user_cfg_env,
+            repo_env if repo_env else Path(),  # dev fallback only if exists
+        ]
+    )
+
+    if explicit and not explicit_path.exists():
+        raise FileNotFoundError(f"AETHERGRAPH_ENV_FILE not found: {explicit_path}")
+
+    if not candidates:
+        log.warning("No .env files found; using OS environment variables only.")
+        return AppSettings()
+
+    # Later files override earlier ones
+    return AppSettings(_env_file=[str(p) for p in candidates])

aethergraph/config/runtime.py

@@ -0,0 +1,9 @@
+from functools import lru_cache
+
+from .config import AppSettings
+from .loader import load_settings
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> AppSettings:
+    return load_settings()

aethergraph/contracts/errors/errors.py

@@ -0,0 +1,44 @@
+# Typed exceptions (ValidationError, MigrationError, etc.)
+
+
+class AetherGraphError(Exception):
+    """Base class for all AetherGraph errors."""
+
+
+class NodeContractError(AetherGraphError):
+    """Raised when a TaskNodeRuntime violates its declared input/output contract."""
+
+
+class MissingInputError(NodeContractError):
+    """Raised when a required input key is missing."""
+
+
+class MissingOutputError(NodeContractError):
+    """Raised when a required output key is missing."""
+
+
+class ExecutionError(AetherGraphError):
+    """Raised when a node’s logic fails during execution."""
+
+
+class GraphHasPendingWaits(RuntimeError):
+    """Raised when attempting to finalize a graph that has pending waits."""
+
+    def __init__(
+        self, message: str, waiting_nodes: list[str], continuations: list[dict] | None = None
+    ):
+        super().__init__(message)
+        self.waiting_nodes = waiting_nodes
+        self.continuations = continuations or []
+
+
+class ResumeIncompatibleSnapshot(RuntimeError):
+    """
+    Raised when a snapshot is not allowed for resume under the current policy
+    (e.g., contains non-JSON outputs or external refs like __aether_ref__).
+    """
+
+    def __init__(self, run_id: str, reasons: list[str]):
+        super().__init__(f"Resume blocked for run_id={run_id}. " + " / ".join(reasons))
+        self.run_id = run_id
+        self.reasons = reasons

aethergraph/contracts/services/artifacts.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass
+class Artifact:
+    artifact_id: str
+    uri: str
+    kind: str
+    bytes: int
+    sha256: str
+    mime: str | None
+    run_id: str
+    graph_id: str
+    node_id: str
+    tool_name: str
+    tool_version: str
+    created_at: str
+    labels: dict[str, Any]
+    metrics: dict[str, Any]
+    preview_uri: str | None = None  # for rendering previews in UI, not tied to storage
+    pinned: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "artifact_id": self.artifact_id,
+            "uri": self.uri,
+            "kind": self.kind,
+            "bytes": self.bytes,
+            "sha256": self.sha256,
+            "mime": self.mime,
+            "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,
+            "created_at": self.created_at,
+            "labels": self.labels,
+            "metrics": self.metrics,
+            "preview_uri": self.preview_uri,
+            "pinned": self.pinned,
+        }
+
+
+class AsyncArtifactStore(Protocol):
+    async def save_file(
+        self,
+        *,
+        path: str,
+        kind: str,
+        run_id: str,
+        graph_id: str,
+        node_id: str,
+        tool_name: str,
+        tool_version: str,
+        suggested_uri: str | None = None,
+        pin: bool = False,
+        labels: dict | None = None,
+        metrics: dict | None = None,
+        preview_uri: str | None = None,
+    ) -> Artifact: ...
+    async def open_writer(
+        self,
+        *,
+        kind: str,
+        run_id: str,
+        graph_id: str,
+        node_id: str,
+        tool_name: str,
+        tool_version: str,
+        planned_ext: str | None = None,
+        pin: bool = False,
+    ) -> AbstractAsyncContextManager[Any]: ...
+    async def plan_staging_path(self, planned_ext: str = "") -> str: ...
+    async def ingest_staged_file(
+        self,
+        *,
+        staged_path: str,
+        kind: str,
+        run_id: str,
+        graph_id: str,
+        node_id: str,
+        tool_name: str,
+        tool_version: str,
+        pin: bool = False,
+        labels: dict | None = None,
+        metrics: dict | None = None,
+        preview_uri: str | None = None,
+        suggested_uri: str | None = None,
+    ) -> Artifact: ...
+    async def plan_staging_dir(self, suffix: str = "") -> str: ...
+    async def ingest_directory(
+        self,
+        *,
+        staged_dir: str,
+        kind: str,
+        run_id: str,
+        graph_id: str,
+        node_id: str,
+        tool_name: str,
+        tool_version: str,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        index_children: bool = False,
+        pin: bool = False,
+        labels: dict | None = None,
+        metrics: dict | None = None,
+        suggested_uri: str | None = None,
+        archive: bool = False,
+        archive_name: str = "bundle.tar.gz",
+        cleanup: bool = True,
+        store: str | None = None,
+    ) -> Artifact: ...
+    async def load_artifact(self, uri: str) -> Any: ...
+    async def load_artifact_bytes(self, uri: str) -> bytes: ...
+    async def load_artifact_dir(self, uri: str) -> str: ...
+    async def cleanup_tmp(self, max_age_hours: int = 24) -> None: ...
+    async def save_text(self, payload: str, suggested_uri: str | None = None) -> Artifact: ...
+    async def save_json(self, payload: dict, suggested_uri: str | None = None) -> Artifact: ...
+    @property
+    def base_uri(self) -> str: ...
+
+
+class AsyncArtifactIndex(Protocol):
+    async def upsert(self, a: Artifact) -> None: ...
+    async def list_for_run(self, run_id: str) -> list[Artifact]: ...
+    async def search(
+        self,
+        *,
+        kind: str | None = None,
+        labels: dict | None = None,
+        metric: str | None = None,
+        mode: str | None = None,
+    ) -> list[Artifact]: ...
+    async def best(
+        self, *, kind: str, metric: str, mode: str, filters: dict | None = None
+    ) -> Artifact | None: ...
+    async def pin(self, artifact_id: str, pinned: bool = True) -> None: ...
+    async def record_occurrence(self, a: Artifact, extra_labels: dict | None = None) -> None: ...

aethergraph/contracts/services/channel.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol, TypedDict
+
+EventType = Literal[
+    "agent.message",
+    "agent.message.update",  # simple text messages
+    "agent.stream.start",
+    "agent.stream.delta",
+    "agent.stream.end",  # streaming messages
+    "agent.progress.start",
+    "agent.progress.update",
+    "agent.progress.end",  # progress bar
+    "session.need_input",
+    "session.need_approval",
+    "session.waiting",
+    "file.upload",
+    "link.buttons",  # link preview with buttons
+]
+
+
+class FileRef(TypedDict, total=False):
+    id: str  # platform file id (e.g., Slack file ID)
+    name: str  # suggested filename
+    mimetype: str  # MIME type, e.g., "image/png", "application/pdf"
+    size: int  # size in bytes
+    uri: str  # URL to download the file (artifact storage or platform URL)
+    url_private: str  # private URL if applicable (e.g., Slack private URL)
+    platform: str  # platform name, e.g., "slack", "telegram", "console"
+    channel_key: str  # normalized channel key where the file was sent, e.g., "slack:team/T:chan/C"
+    ts: str | float  # timestamp of the file upload
+
+
+@dataclass
+class Button:
+    label: str
+    value: str | None = None
+    url: str | None = None
+    style: Literal["primary", "danger", "default"] | None = None  # for slack buttons
+
+
+@dataclass
+class OutEvent:
+    type: EventType  # "agent.message", "session.need_input", "session.need_approval", "agent.stream.*"
+    channel: str  # routing key, e.g., "console:stdout" or "slack:team/T:chan/C[:thread/TS]"
+    text: str | None = None
+    rich: dict[str, Any] | None = None
+    meta: dict[str, Any] | None = None
+    # Optional structured extras most adapters can use, e.g., for buttons, attachments, files, etc.
+    buttons: dict[str, Button] | None = None  # for approvals or link actions
+    image: dict[str, Any] | None = None  # e.g., {"url": "...", "alt": "...", "title": "..."}
+    file: dict[str, Any] | None = (
+        None  # e.g., {"bytes" b"...", "filename": "...", "mimetype": "..."} or {"url": "...", "filename": "...", "mimetype": "..."}
+    )
+    upsert_key: str | None = None  # for idempotent upserts, e.g., message ID to update same message
+
+    def to_printable(self) -> str:
+        """Only contains printable parts of the event."""
+        return (
+            f"Event(type={self.type}, channel={self.channel}, text={self.text}, meta={self.meta})"
+        )
+
+
+class ChannelAdapter(Protocol):
+    # Capabilities helper
+    capabilities: set[str]  # e.g. {"text", "image", "file", "buttons", "rich"}
+
+    async def send(self, event: OutEvent) -> None:
+        """
+        Send an outgoing event to the appropriate channel.
+        E.g., print to console, post to Slack, enqueue in UI, etc.
+        """
+        pass

aethergraph/contracts/services/continuations.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class AsyncContinuationStore(Protocol):
+    async def mint_token(self, run_id: str, node_id: str, attempts: int) -> str: ...
+    async def save(self, cont: Any) -> None: ...
+    async def get(self, run_id: str, node_id: str) -> Any | None: ...
+    async def delete(self, run_id: str, node_id: str) -> None: ...
+
+    async def get_by_token(self, token: str) -> Any | None: ...
+    async def mark_closed(self, token: str) -> None: ...
+    async def verify_token(self, run_id: str, node_id: str, token: str) -> bool: ...
+
+    async def bind_correlator(self, *, token: str, corr: Any) -> None: ...
+    async def find_by_correlator(self, *, corr: Any) -> Any | None: ...
+
+    # Optional helpers
+    async def last_open(self, *, channel: str, kind: str) -> Any | None: ...
+    async def list_waits(self) -> list[dict[str, Any]]: ...
+    async def clear(self) -> None: ...
+    async def alias_for(self, token: str) -> str | None: ...

aethergraph/contracts/services/eventbus.py

@@ -0,0 +1,12 @@
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol
+
+Handler = Callable[[dict[str, Any]], Awaitable[None]]
+
+
+class EventBus(Protocol):
+    """Protocol for an event bus service."""
+
+    async def publish(self, topic: str, event: dict[str, Any]) -> None: ...
+
+    def subscribe(self, topic: str, handler: Handler) -> None: ...

aethergraph/contracts/services/kv.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol
+
+
+class AsyncKV(Protocol):
+    async def get(self, key: str, default: Any = None) -> Any: ...
+    async def set(self, key: str, value: Any, *, ttl_s: int | None = None) -> None: ...
+    async def delete(self, key: str) -> None: ...
+
+    # list helpers (JSON list values)
+    async def list_append_unique(
+        self, key: str, items: list, *, id_key: str = "id", ttl_s: int | None = None
+    ) -> list: ...
+    async def list_pop_all(self, key: str) -> list: ...
+
+    # optional but useful
+    async def mget(self, keys: Iterable[str]) -> dict[str, Any]: ...
+    async def mset(self, items: dict[str, Any], *, ttl_s: int | None = None) -> None: ...
+    async def incr(self, key: str, amount: int = 1, *, ttl_s: int | None = None) -> int: ...
+    async def exists(self, key: str) -> bool: ...
+    async def expire(self, key: str, ttl_s: int) -> bool: ...
+    async def scan_prefix(self, prefix: str, limit: int = 1000) -> Iterable[str]: ...

aethergraph/contracts/services/llm.py

@@ -0,0 +1,17 @@
+from typing import Any, Protocol
+
+
+class LLMClientProtocol(Protocol):
+    async def chat(self, messages: list[dict[str, Any]], **kw) -> tuple[str, dict[str, int]]: ...
+    async def embed(self, texts: list[str], **kw) -> list[list[float]]: ...
+    async def raw(
+        self,
+        *,
+        method: str = "POST",
+        path: str | None = None,
+        url: str | None = None,
+        json: Any | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        return_response: bool = False,
+    ) -> Any: ...

aethergraph/contracts/services/mcp.py

@@ -0,0 +1,22 @@
+from typing import Any, TypedDict
+
+
+class MCPTool(TypedDict):
+    name: str
+    description: str | None
+    input_schema: dict[str, Any] | None
+
+
+class MCPResource(TypedDict):
+    uri: str
+    mime: str | None
+    description: str | None
+
+
+class MCPClientProtocol:
+    async def open(self): ...
+    async def close(self): ...
+    async def list_tools(self) -> list[MCPTool]: ...
+    async def call(self, tool: str, params: dict[str, Any] | None = None) -> dict[str, Any]: ...
+    async def list_resources(self) -> list[MCPResource]: ...
+    async def read_resource(self, uri: str) -> dict[str, Any]: ...