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

aethergraph/__main__.py

@@ -191,6 +191,9 @@ def main(argv: list[str] | None = None) -> int:
 
             # Export them to environment so the worker factory can read them
             os.environ["AETHERGRAPH_WORKSPACE"] = args.workspace
+            os.environ.setdefault(
+                "AETHERGRAPH_ROOT", args.workspace
+            )  # AETHERGRAPH_ROOT is the workspace root in env
             os.environ["AETHERGRAPH_PROJECT_ROOT"] = str(project_root)
             os.environ["AETHERGRAPH_LOAD_MODULES"] = ",".join(modules)
             os.environ["AETHERGRAPH_LOAD_PATHS"] = os.pathsep.join(paths)

aethergraph/api/v1/artifacts.py

@@ -128,6 +128,8 @@ def _artifact_to_meta(a: Artifact) -> ArtifactMeta:
 @router.get("/artifacts", response_model=ArtifactListResponse)
 async def list_artifacts(
     scope_id: Annotated[str | None, Query()] = None,
+    run_id: Annotated[str | None, Query()] = None,
+    session_id: Annotated[str | None, Query()] = None,
     kind: Annotated[str | None, Query()] = None,
     tags: Annotated[str | None, Query()] = None,
     cursor: Annotated[str | None, Query()] = None,
@@ -141,17 +143,34 @@ async def list_artifacts(
 
     offset = decode_cursor(cursor.strip() if cursor else None)
 
+    # label_filters: dict[str, Any] = {}
+
+    # if scope_id and scope_id.strip():
+    #     label_filters["scope_id"] = scope_id.strip()
+
+    # if tags and tags.strip():
+    #     tag_list = [t.strip() for t in tags.split(",") if t.strip()]
+    #     if tag_list:
+    #         label_filters["tags"] = tag_list
+
+    # # 🔹 Tenant scoping: org_id + user_id
+    # label_filters.update(_tenant_label_filters(identity))
+
     label_filters: dict[str, Any] = {}
 
+    # execution scopes
+    if run_id and run_id.strip():
+        label_filters["run_id"] = run_id.strip()
+    if session_id and session_id.strip():
+        label_filters["session_id"] = session_id.strip()
+
+    # memory scope (keep for “overview” / RAG-style scoping)
     if scope_id and scope_id.strip():
         label_filters["scope_id"] = scope_id.strip()
 
     if tags and tags.strip():
-        tag_list = [t.strip() for t in tags.split(",") if t.strip()]
-        if tag_list:
-            label_filters["tags"] = tag_list
+        label_filters["tags"] = [t.strip() for t in tags.split(",") if t.strip()]
 
-    # 🔹 Tenant scoping: org_id + user_id
     label_filters.update(_tenant_label_filters(identity))
 
     artifacts = await index.search(

aethergraph/api/v1/schemas.py

@@ -488,6 +488,11 @@ class SessionChatFile(BaseModel):
     mimetype: str | None = None
     size: int | None = None
     uri: str | None = None  # optional, useful for artifact URIs
+    renderer: Literal["image", "download", "vega", "plotly"] | None = None  # optional, for UI hints
+
+    class Config:
+        # Optional but nice: future-proof against extra keys
+        extra = "allow"
 
 
 class SessionChatEvent(BaseModel):
@@ -498,10 +503,12 @@ class SessionChatEvent(BaseModel):
     buttons: list[dict[str, Any]]
     file: SessionChatFile | None = None  # legacy/single
     files: list[SessionChatFile] | None = None  # NEW: multi
+    attachments: list[SessionChatFile] | None = None  # 🔹 placeholder for future richer usage
     meta: dict[str, Any]
     ts: float
     agent_id: str | None = None
     upsert_key: str | None = None  # for idempotent updates
+    rich: dict[str, Any] | None = None  # phase/progress payloads
 
 
 class SessionUpdateRequest(BaseModel):

aethergraph/api/v1/session.py

@@ -1,6 +1,17 @@
+import asyncio
+from contextlib import suppress
 from datetime import datetime, timezone
-
-from fastapi import APIRouter, Depends, HTTPException, Query, Request
+import logging
+
+from fastapi import (
+    APIRouter,
+    Depends,
+    HTTPException,
+    Query,
+    Request,
+    WebSocket,
+    WebSocketDisconnect,
+)
 
 from aethergraph.api.v1.deps import RequestIdentity, get_identity
 from aethergraph.api.v1.pagination import decode_cursor, encode_cursor
@@ -19,6 +30,7 @@ from aethergraph.core.runtime.runtime_registry import current_registry
 from aethergraph.core.runtime.runtime_services import current_services
 
 router = APIRouter(tags=["sessions"])
+logger = logging.getLogger(__name__)
 
 
 @router.post("/sessions", response_model=Session)
@@ -74,8 +86,6 @@ async def list_sessions(
         limit=limit,
         offset=offset,
     )
-    # print(f"Listed {len(sessions)} sessions for user_id={identity.user_id} org_id={identity.org_id} offset={offset} limit={limit}")
-    # print(f"Sessions: {[s for s in sessions]}")
     next_cursor = encode_cursor(offset + limit) if len(sessions) == limit else None
     return SessionListResponse(items=sessions, next_cursor=next_cursor)
 
@@ -206,6 +216,109 @@ async def get_session_runs(
     return SessionRunsResponse(items=summaries)
 
 
+def _row_to_session_chat_event(row: dict, session_id: str) -> SessionChatEvent:
+    payload = row.get("payload", {}) or {}
+    return SessionChatEvent(
+        id=row.get("id"),
+        session_id=session_id,
+        ts=row.get("ts"),
+        type=payload.get("type") or "agent.message",
+        text=payload.get("text"),
+        buttons=payload.get("buttons", []),
+        file=payload.get("file"),
+        files=payload.get("files") or None,
+        rich=payload.get("rich") or None,
+        meta=payload.get("meta", {}) or {},
+        agent_id=payload.get("agent_id"),
+        upsert_key=payload.get("upsert_key"),
+    )
+
+
+@router.websocket("/ws/sessions/{session_id}/chat")
+async def ws_session_chat(websocket: WebSocket, session_id: str):
+    DROP_FROM_HISTORY = {"agent.stream.start", "agent.stream.delta"}
+
+    container = current_services()
+    event_log = container.eventlog
+    hub = getattr(container, "eventhub", None)
+
+    if hub is None or event_log is None:
+        await websocket.close(code=1011)
+        return
+
+    await websocket.accept()
+
+    async def send_snapshot() -> None:
+        events = await event_log.query(
+            scope_id=session_id,
+            kinds=["session_chat"],
+            since=None,
+            limit=200,
+        )
+        filtered = []
+        for ev in events:
+            payload = ev.get("payload") or {}
+            t = payload.get("type") or "agent.message"
+            if t in DROP_FROM_HISTORY:
+                continue
+            filtered.append(ev)
+
+        filtered.sort(key=lambda ev: ev.get("ts") or 0)
+        initial_payload = [
+            _row_to_session_chat_event(ev, session_id).model_dump() for ev in filtered
+        ]
+        await websocket.send_json({"kind": "snapshot", "events": initial_payload})
+
+    async def recv_until_disconnect() -> None:
+        # Blocks until disconnect; does not require the client to send meaningful messages.
+        while True:
+            msg = await websocket.receive()
+            if msg.get("type") == "websocket.disconnect":
+                return
+
+    async def send_live() -> None:
+        # If you kept old hub shape, you'd do async for row in hub.subscribe(scope_id=session_id)
+        async for row in hub.subscribe(scope_id=session_id, kind="session_chat"):
+            ev = _row_to_session_chat_event(row, session_id)
+            await websocket.send_json({"kind": "event", "event": ev.model_dump()})
+
+    recv_task = send_task = None
+    try:
+        await send_snapshot()
+
+        recv_task = asyncio.create_task(recv_until_disconnect())
+        send_task = asyncio.create_task(send_live())
+
+        done, pending = await asyncio.wait(
+            {recv_task, send_task},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        # Cancel the other task (this is what prevents idle hangs)
+        for t in pending:
+            t.cancel()
+            with suppress(asyncio.CancelledError):
+                await t
+
+    except WebSocketDisconnect:
+        # can happen from send_json
+        return
+    except asyncio.CancelledError:
+        # critical for uvicorn --reload
+        with suppress(Exception):
+            await websocket.close(code=1001)
+        raise
+    except Exception as e:
+        with suppress(Exception):
+            await websocket.close(code=1011, reason=str(e)[:120])
+    finally:
+        for t in (recv_task, send_task):
+            if t and not t.done():
+                t.cancel()
+                with suppress(asyncio.CancelledError):
+                    await t
+
+
 @router.get("/sessions/{session_id}/chat/events", response_model=list[SessionChatEvent])
 async def get_session_chat_events(
     session_id: str,
@@ -213,6 +326,8 @@ async def get_session_chat_events(
     since_ts: float | None = Query(None),  # noqa: B008
     identity: RequestIdentity = Depends(get_identity),  # noqa: B008
 ) -> list[SessionChatEvent]:
+    DROP_FROM_HISTORY = {"agent.stream.start", "agent.stream.delta"}
+
     container = current_services()
     event_log = container.eventlog
 
@@ -234,6 +349,9 @@ async def get_session_chat_events(
         # make cursor exclusive -- only return events after since_ts to avoid duplicates
         events = [ev for ev in events if (ev.get("ts") or 0) > since_ts]
 
+    # Filter legacy persisted deltas/start
+    events = [ev for ev in events if (ev.get("payload") or {}).get("type") not in DROP_FROM_HISTORY]
+
     out: list[SessionChatEvent] = []
     for ev in events:
         payload = ev.get("payload", {}) or {}
@@ -250,6 +368,7 @@ async def get_session_chat_events(
                 meta=payload.get("meta", {}) or {},
                 agent_id=payload.get("agent_id"),
                 upsert_key=payload.get("upsert_key"),  # forward idempotent key
+                rich=payload.get("rich") or None,  # forward rich content
             )
         )
     out.sort(key=lambda e: e.ts)

aethergraph/config/config.py

@@ -5,6 +5,7 @@ from pydantic import BaseModel, Field, SecretStr
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from .llm import LLMSettings
+from .search import SearchBackendSettings
 from .storage import StorageSettings
 
 
@@ -136,6 +137,7 @@ class AppSettings(BaseSettings):
     channels: ChannelSettings = ChannelSettings()
     rag: RAGSettings = RAGSettings()
     storage: StorageSettings = StorageSettings()
+    search: SearchBackendSettings = SearchBackendSettings()
 
     # Future fields:
     # authn: ...

aethergraph/config/search.py

@@ -0,0 +1,49 @@
+# search_settings.py (or wherever you keep config models)
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from .storage import FAISSVectorIndexSettings, SQLiteVectorIndexSettings
+
+# ^ or wherever those two are defined
+
+
+class SQLiteLexicalSearchSettings(BaseModel):
+    """
+    Settings for SQLite-based lexical search backend.
+    Paths are relative to AppSettings.root.
+    """
+
+    dir: str = "search/sqlite_lexical"
+    filename: str = "index.sqlite"
+
+
+class SearchBackendSettings(BaseModel):
+    """
+    Config for the high-level SearchBackend used by ScopedIndices.
+
+    backend:
+      - "none"          -> NullSearchBackend (no search at all)
+      - "sqlite_vector" -> VectorSearchBackend + SQLiteVectorIndex
+      - "faiss_vector"  -> VectorSearchBackend + FAISSVectorIndex
+      - "sqlite_lexical"-> SQLiteLexicalSearchBackend (no embeddings)
+    """
+
+    backend: Literal["none", "sqlite_vector", "faiss_vector", "sqlite_lexical"] = "sqlite_vector"
+
+    # Vector search backends (reuse your existing index settings types,
+    # but point them to search-specific directories by default).
+    sqlite_vector: SQLiteVectorIndexSettings = SQLiteVectorIndexSettings(
+        dir="search/vector_sqlite",
+        filename="index.sqlite",
+    )
+    faiss_vector: FAISSVectorIndexSettings = FAISSVectorIndexSettings(
+        dir="search/vector_faiss",
+        dim=None,
+    )
+
+    # Lexical search backend
+    sqlite_lexical: SQLiteLexicalSearchSettings = SQLiteLexicalSearchSettings()

aethergraph/contracts/services/channel.py

@@ -18,6 +18,23 @@ EventType = Literal[
 ]
 
 
+class PhaseRich(TypedDict, total=False):
+    kind: Literal["phase"]
+    phase: str  # "routing", "planning", "reasoning", "tools", "reply"
+    status: Literal["pending", "active", "done", "failed", "skipped"]
+    label: str | None  # short human label
+    detail: str | None  # optional extra text
+    code: str | None  # internal code like "routing.planning"
+
+
+class ProgressRich(TypedDict, total=False):
+    kind: Literal["progress"]
+    label: str | None
+    current: float | int | None
+    total: float | int | None
+    unit: str | None  # "%", "steps", etc.
+
+
 class FileRef(TypedDict, total=False):
     id: str  # platform file id (e.g., Slack file ID)
     name: str  # suggested filename
@@ -46,7 +63,7 @@ class OutEvent:
     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
+    buttons: list[Button] | None = None
     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": "..."}

aethergraph/contracts/services/execution.py

@@ -0,0 +1,58 @@
+# aethergraph/contracts/services/execution.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+Language = Literal["python"]  # later: "bash", "r", etc.
+
+
+@dataclass
+class CodeExecutionRequest:
+    """
+    Generic request to execute code.
+
+    For v0 we only support Python, but keep `language` so we can grow.
+    """
+
+    language: Language
+    code: str
+
+    # CLI-style args if you want to support them later
+    args: list[str] = field(default_factory=list)
+
+    # Execution constraints
+    timeout_s: float = 30.0
+
+    # Optional working directory and env (for future use)
+    workdir: str | None = None
+    env: dict[str, str] | None = None
+
+
+@dataclass
+class CodeExecutionResult:
+    """
+    Result of a code execution.
+
+    - stdout / stderr: what the script printed
+    - exit_code: OS-level exit code
+    - error: high-level error if our runner failed (timeout, spawn failure, etc.)
+    - metadata: free-form, e.g. timing info
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class ExecutionService(Protocol):
+    """
+    Abstract interface for code execution backends.
+
+    This lets us later plug in Docker, VM, remote HTTP, etc,
+    without changing NodeContext or node code.
+    """
+
+    async def execute(self, request: CodeExecutionRequest) -> CodeExecutionResult: ...

aethergraph/contracts/services/llm.py

@@ -1,3 +1,4 @@
+from collections.abc import Sequence
 from typing import Any, Protocol
 
 
@@ -15,3 +16,28 @@ class LLMClientProtocol(Protocol):
         headers: dict[str, str] | None = None,
         return_response: bool = False,
     ) -> Any: ...
+
+
+class EmbeddingClientProtocol(Protocol):
+    async def embed(
+        self,
+        texts: Sequence[str],
+        *,
+        model: str | None = None,
+        **kwargs,
+    ) -> list[list[float]]:
+        """
+        Batch-embed texts. Returns one vector per text.
+        """
+
+    async def embed_one(
+        self,
+        text: str,
+        *,
+        model: str | None = None,
+        **kwargs,
+    ) -> list[float]:
+        """
+        Convenience method: embed a single string.
+        Default implementation can call embed([text])[0].
+        """

aethergraph/contracts/services/memory.py

@@ -32,6 +32,7 @@ class Event:
     org_id: str | None = None
     client_id: str | None = None
     app_id: str | None = None
+    agent_id: str | None = None
     session_id: str | None = None
 
     # --------- Core semantics ---------
@@ -63,16 +64,21 @@ class Event:
 
 
 class HotLog(Protocol):
-    async def append(self, run_id: str, evt: Event, *, ttl_s: int, limit: int) -> None: ...
+    async def append(self, scope_id: str, evt: Event, *, ttl_s: int, limit: int) -> None: ...
     async def recent(
-        self, run_id: str, *, kinds: list[str] | None = None, limit: int = 50
+        self, scope_id: str, *, kinds: list[str] | None = None, limit: int = 50
     ) -> list[Event]: ...
 
 
 class Persistence(Protocol):
-    async def append_event(self, run_id: str, evt: Event) -> None: ...
+    async def append_event(self, scope_id: str, evt: Event) -> None: ...
     async def save_json(self, uri: str, obj: dict[str, Any]) -> None: ...
     async def load_json(self, uri: str) -> dict[str, Any]: ...
+    async def get_events_by_ids(
+        self,
+        scope_id: str,
+        event_ids: list[str],
+    ) -> list[Event]: ...
 
 
 class Indices(Protocol):
@@ -87,7 +93,7 @@ class Indices(Protocol):
 class Distiller(Protocol):
     async def distill(
         self,
-        run_id: str,
+        scope_id: str,
         *,
         hotlog: HotLog,
         persistence: Persistence,

aethergraph/contracts/services/planning.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+IntentMode = Literal["chat_only", "quick_action", "plan_and_execute"]
+
+
+@dataclass
+class RoutedIntent:
+    """
+    Result of routing a user turn:
+      - How should we handle this? (mode)
+      - If planning: which flows are in scope?
+      - If quick_action: which quick action?
+    """
+
+    mode: IntentMode
+
+    # For planning
+    flow_ids: list[str] | None = None
+
+    # For quick action, e.g. `list_recent_runs`
+    quick_action_id: str | None = None
+
+    # Freeform extention field.
+    # safety flags, strategy hints, etc. without changing the dataclass structure.
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SessionState:
+    # placeholder for future session-level state
+    last_flow_ids: list[str] | None = None
+
+
+class IntentRouter(Protocol):
+    async def route(
+        self,
+        *,
+        user_message: str,
+        session_state: SessionState,
+    ) -> RoutedIntent: ...
+
+
+class PlanningContextBuilderProtocol:
+    async def build(
+        self,
+        *,
+        user_message: str,
+        routed: RoutedIntent,
+        session_state: SessionState,
+    ) -> Any: ...

aethergraph/contracts/storage/event_log.py

@@ -29,3 +29,11 @@ class EventLog(Protocol):
         tags: list[str] | None = None,  # filter by tags
         offset: int = 0,  # pagination offset
     ) -> list[dict]: ...
+
+    async def get_many(
+        self,
+        scope_id: str,
+        event_ids: list[str],
+    ) -> list[dict]: ...
+
+    """Fetch events for a given scope_id (timeline) by event_id."""

aethergraph/contracts/storage/search_backend.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass
+class ScoredItem:
+    item_id: str
+    corpus: str
+    score: float
+    metadata: dict[str, Any]
+
+
+class SearchBackend(Protocol):
+    async def upsert(
+        self,
+        *,
+        corpus: str,
+        item_id: str,
+        text: str,
+        metadata: dict[str, Any],
+    ) -> None:
+        """
+        Insert or update an indexed item.
+
+        - corpus: logical collection ("event", "artifact", "run", "doc_*")
+        - item_id: stable identifier (event_id, artifact_id, run_id, etc.)
+        - text: main text used for embedding / lexical search
+        - metadata: arbitrary JSON metadata for filters and recency
+        """
+        ...
+
+    async def search(
+        self,
+        *,
+        corpus: str,
+        query: str,
+        top_k: int = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> list[ScoredItem]:
+        """
+        Semantic/lexical search.
+
+        - filters: AND filters over metadata (None values are treated as wildcards).
+        """
+        ...

aethergraph/contracts/storage/vector_index.py

@@ -1,3 +1,4 @@
+from dataclasses import dataclass, field
 from typing import Any, Protocol
 
 """
@@ -38,11 +39,83 @@ class VectorIndex(Protocol):
         corpus_id: str,
         query_vec: list[float],
         k: int,
+        where: dict[str, Any] | None = None,
+        max_candidates: int | None = None,
     ) -> list[dict[str, Any]]: ...
 
+    """
+    where: equality filters on *promoted* fields (org_id, user_id, scope_id, etc.)
+    max_candidates: limit number of candidate rows to score (after SQL WHERE, before cosine).
+    """
+
     # Each dict MUST look like:
     # {"chunk_id": str, "score": float, "meta": dict[str, Any]}
 
     # Optional
     async def list_corpora(self) -> list[str]: ...
     async def list_chunks(self, corpus_id: str) -> list[str]: ...
+
+
+PROMOTED_FIELDS = {
+    "scope_id",
+    "user_id",
+    "org_id",
+    "client_id",
+    "session_id",
+    "run_id",
+    "graph_id",
+    "node_id",
+    "kind",
+    "source",
+}
+
+
+@dataclass
+class IndexMeta:
+    """
+    NOTE: When used with ScopedIndices, identity fields (scope_id, user_id, org_id, etc.)
+    are usually left as None here and provided instead by scope.rag_labels(). In that
+    common path, this struct is primarily for type-specific metadata (kind, source, ts, ...).
+    """
+
+    # tenant / scope
+    scope_id: str | None = None
+    user_id: str | None = None
+    org_id: str | None = None
+    client_id: str | None = None
+    session_id: str | None = None
+
+    # run / graph context
+    run_id: str | None = None
+    graph_id: str | None = None
+    node_id: str | None = None
+
+    # content type
+    kind: str | None = None  # e.g. "artifact", "memory_event"
+    source: str | None = None  # e.g. "hotlog", "artifact_index"
+
+    # time
+    ts: str | None = None  # human-readable ISO
+    created_at_ts: float | None = None  # numeric, for DB index
+
+    # free-form / extra labels
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "scope_id": self.scope_id,
+            "user_id": self.user_id,
+            "org_id": self.org_id,
+            "client_id": self.client_id,
+            "session_id": self.session_id,
+            "run_id": self.run_id,
+            "graph_id": self.graph_id,
+            "node_id": self.node_id,
+            "kind": self.kind,
+            "source": self.source,
+            "ts": self.ts,
+            "created_at_ts": self.created_at_ts,
+        }
+        d.update(self.extra)
+        # Strip Nones so meta stays compact
+        return {k: v for k, v in d.items() if v is not None}