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

aethergraph/api/v1/graphs.py

@@ -0,0 +1,259 @@
+# /graphs
+
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from aethergraph.core.graph.graph_fn import GraphFunction
+from aethergraph.core.graph.task_graph import TaskGraph
+from aethergraph.core.runtime.runtime_registry import current_registry
+from aethergraph.services.registry.unified_registry import UnifiedRegistry
+
+from .deps import RequestIdentity, get_identity
+from .schemas import GraphDetail, GraphListItem
+
+router = APIRouter(tags=["graphs"])
+
+
+GRAPH_NS = "graph"
+GRAPHFN_NS = "graphfn"
+
+
+def _is_task_graph(obj: Any) -> bool:
+    if isinstance(obj, TaskGraph):
+        return True
+    # Fallback check -- used in tests
+    return hasattr(obj, "spec")
+
+
+def _is_graph_function(obj: Any) -> bool:
+    if isinstance(obj, GraphFunction):
+        return True
+    # Fallback check -- used in tests
+    return hasattr(obj, "fn") and hasattr(obj, "name")
+
+
+@router.get("/graphs", response_model=list[GraphListItem])
+async def list_graphs(
+    flow_id: Annotated[str | None, Query()] = None,
+    identity: RequestIdentity = Depends(get_identity),  # noqa: B008
+) -> list[GraphListItem]:
+    """
+    List available graphs (TaskGraphs and GraphFunctions).
+
+    Optional:
+      - flow_id: filter to graphs whose registry metadata has this flow_id.
+    """
+    reg: UnifiedRegistry = current_registry()
+
+    items: list[GraphListItem] = []
+
+    # ---- 1) Static TaskGraphs (ns="graph") ----
+    latest_graphs = reg.list(nspace=GRAPH_NS)
+    for key, version in latest_graphs.items():
+        ns, name = key.split(":", 1)
+        if ns != GRAPH_NS:
+            continue
+
+        graph_obj = reg.get_graph(name=name, version=version)
+        spec = getattr(graph_obj, "spec", None)
+
+        meta = reg.get_meta(nspace=GRAPH_NS, name=name, version=version) or {}
+        meta_flow_id: str | None = meta.get("flow_id")
+        meta_entrypoint: bool = bool(meta.get("entrypoint", False))
+        meta_tags = list(meta.get("tags", []))
+
+        # flow filter
+        if flow_id is not None and meta_flow_id != flow_id:
+            continue
+
+        if spec is None:
+            items.append(
+                GraphListItem(
+                    graph_id=name,
+                    name=name,
+                    description=None,
+                    inputs=[],
+                    outputs=[],
+                    tags=meta_tags or ["graph"],
+                    kind="graph",
+                    flow_id=meta_flow_id,
+                    entrypoint=meta_entrypoint,
+                )
+            )
+            continue
+
+        inputs = list(spec.io.required.keys()) + list(spec.io.optional.keys())
+        outputs = list(spec.io.outputs.keys())
+
+        desc = spec.meta.get("description") if hasattr(spec, "meta") else None
+        spec_tags = list(spec.meta.get("tags", [])) if hasattr(spec, "meta") else []
+
+        tags = meta_tags or spec_tags or ["graph"]
+
+        items.append(
+            GraphListItem(
+                graph_id=name,
+                name=name,
+                description=desc,
+                inputs=inputs,
+                outputs=outputs,
+                tags=tags,
+                kind="graph",
+                flow_id=meta_flow_id,
+                entrypoint=meta_entrypoint,
+            )
+        )
+
+    # ---- 2) Imperative GraphFunctions (ns="graphfn") ----
+    latest_graphfns = reg.list(nspace=GRAPHFN_NS)
+    for key, version in latest_graphfns.items():
+        ns, name = key.split(":", 1)
+        if ns != GRAPHFN_NS:
+            continue
+
+        gf = reg.get_graphfn(name=name, version=version)
+        if not _is_graph_function(gf):
+            continue
+
+        meta = reg.get_meta(nspace=GRAPHFN_NS, name=name, version=version) or {}
+        meta_flow_id: str | None = meta.get("flow_id")
+        meta_entrypoint: bool = bool(meta.get("entrypoint", False))
+        meta_tags = list(meta.get("tags", []))
+
+        if flow_id is not None and meta_flow_id != flow_id:
+            continue
+
+        inputs = list(getattr(gf, "inputs", []) or [])
+        outputs = list(getattr(gf, "outputs", []) or [])
+        desc = getattr(gf, "description", None)
+
+        items.append(
+            GraphListItem(
+                graph_id=name,
+                name=name,
+                description=desc,
+                inputs=inputs,
+                outputs=outputs,
+                tags=meta_tags or ["graphfn"],
+                kind="graphfn",
+                flow_id=meta_flow_id,
+                entrypoint=meta_entrypoint,
+            )
+        )
+
+    return items
+
+
+@router.get("/graphs/{graph_id}", response_model=GraphDetail)
+async def get_graph_detail(
+    graph_id: str,
+    identity: RequestIdentity = Depends(get_identity),  # noqa: B008
+) -> GraphDetail:
+    """
+    Get detailed information about a specific graph (structure only).
+    """
+    reg: UnifiedRegistry = current_registry()
+
+    # 1) Try TaskGraph
+    try:
+        graph_obj = reg.get_graph(name=graph_id, version=None)
+        spec = getattr(graph_obj, "spec", None)
+        meta = reg.get_meta(nspace=GRAPH_NS, name=graph_id, version=None) or {}
+
+        flow_id = meta.get("flow_id")
+        entrypoint = bool(meta.get("entrypoint", False))
+        meta_tags = list(meta.get("tags", []))
+
+        if spec is None:
+            return GraphDetail(
+                graph_id=graph_id,
+                name=graph_id,
+                description=None,
+                inputs=[],
+                outputs=[],
+                tags=meta_tags or ["graph"],
+                kind="graph",
+                flow_id=flow_id,
+                entrypoint=entrypoint,
+                nodes=[],
+                edges=[],
+            )
+
+        # ---- Nodes from TaskNodeSpec ----
+        nodes_list: list[dict[str, Any]] = []
+        for node_id, node_spec in spec.nodes.items():
+            node_info: dict[str, Any] = {
+                "id": node_id,
+                "type": str(getattr(node_spec, "type", "")),
+                "tool_name": getattr(node_spec, "tool_name", None),
+                "tool_version": getattr(node_spec, "tool_version", None),
+                "expected_inputs": list(getattr(node_spec, "expected_input_keys", []) or []),
+                "expected_outputs": list(getattr(node_spec, "expected_output_keys", []) or []),
+                "output_keys": list(getattr(node_spec, "output_keys", []) or []),
+            }
+            nodes_list.append(node_info)
+
+        # ---- Edges from dependencies ----
+        edge_set: set[tuple[str, str]] = set()
+        for node_id, node_spec in spec.nodes.items():
+            for dep_id in getattr(node_spec, "dependencies", []):
+                edge_set.add((str(dep_id), str(node_id)))
+
+        edges_list: list[dict[str, Any]] = [
+            {"source": src, "target": dst} for (src, dst) in sorted(edge_set)
+        ]
+
+        inputs = list(spec.io.required.keys()) + list(spec.io.optional.keys())
+        outputs = list(spec.io.outputs.keys())
+        desc = spec.meta.get("description") if hasattr(spec, "meta") else None
+        spec_tags = list(spec.meta.get("tags", [])) if hasattr(spec, "meta") else []
+
+        tags = meta_tags or spec_tags or ["graph"]
+
+        return GraphDetail(
+            graph_id=graph_id,
+            name=graph_id,
+            description=desc,
+            inputs=inputs,
+            outputs=outputs,
+            tags=tags,
+            kind="graph",
+            flow_id=flow_id,
+            entrypoint=entrypoint,
+            nodes=nodes_list,
+            edges=edges_list,
+        )
+
+    except KeyError:
+        pass
+
+    # 2) Try GraphFunction
+    try:
+        gf = reg.get_graphfn(name=graph_id, version=None)
+    except KeyError as e:
+        raise HTTPException(status_code=404, detail="Graph not found") from e
+
+    meta = reg.get_meta(nspace=GRAPHFN_NS, name=graph_id, version=None) or {}
+    flow_id = meta.get("flow_id")
+    entrypoint = bool(meta.get("entrypoint", False))
+    meta_tags = list(meta.get("tags", []))
+
+    inputs = list(getattr(gf, "inputs", []) or [])
+    outputs = list(getattr(gf, "outputs", []) or [])
+    desc = getattr(gf, "description", None)
+
+    return GraphDetail(
+        graph_id=graph_id,
+        name=graph_id,
+        description=desc,
+        inputs=inputs,
+        outputs=outputs,
+        tags=meta_tags or ["graphfn"],
+        kind="graphfn",
+        flow_id=flow_id,
+        entrypoint=entrypoint,
+        nodes=[],  # GraphFunction has no static node DAG
+        edges=[],
+    )

aethergraph/api/v1/identity.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from aethergraph.api.v1.deps import RequestIdentity, get_identity
+
+router = APIRouter()
+
+
+class IdentityResponse(BaseModel):
+    mode: str
+    user_id: str | None
+    org_id: str | None
+    roles: list[str]
+    client_id: str | None
+
+
+@router.get("/whoami", response_model=IdentityResponse)
+def whoami(identity: RequestIdentity = Depends(get_identity)):  # noqa: B008
+    return IdentityResponse(
+        mode=identity.mode,
+        user_id=identity.user_id,
+        org_id=identity.org_id,
+        roles=identity.roles,
+        client_id=identity.client_id,
+    )

aethergraph/api/v1/memory.py

@@ -0,0 +1,353 @@
+# memory-related inspection
+
+from contextlib import suppress
+from datetime import datetime
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Query
+
+from aethergraph.api.v1.pagination import decode_cursor, encode_cursor
+from aethergraph.contracts.services.memory import Event
+from aethergraph.core.runtime.runtime_services import current_services
+
+from .deps import RequestIdentity, get_identity
+from .schemas import (
+    MemoryEvent,
+    MemoryEventListResponse,
+    MemorySearchHit,
+    MemorySearchRequest,
+    MemorySearchResponse,
+    MemorySummaryEntry,
+    MemorySummaryListResponse,
+)
+
+# NOTE: since hotlog is bounded in memory, it is fine to filter and rank in-memory for now.
+# In future, if we need to process large volumes of memory data, we should look into changing the
+# backend memory storage to support indexed queries (not changing the API contracts).
+
+router = APIRouter(tags=["memory"])
+
+
+# ------------ helpers / stubs ------------ #
+def _parse_ts(ts: str) -> datetime:
+    """Parse ISO8601 timestamp string to datetime."""
+    if ts.endswith("Z"):
+        ts = ts[:-1] + "+00:00"
+    return datetime.fromisoformat(ts)
+
+
+def _event_to_api_event(evt: Event) -> MemoryEvent:
+    created_at = _parse_ts(evt.ts)
+
+    data: dict[str, Any] | None = None
+    if evt.data is not None:
+        data = evt.data
+    elif evt.text:
+        data = {"text": evt.text}
+
+    # Fallback: if old events had no scope_id, use run_id so UI still works.
+    scope = evt.scope_id or evt.run_id
+
+    return MemoryEvent(
+        event_id=evt.event_id,
+        scope_id=scope,
+        kind=evt.kind,
+        tags=evt.tags or [],
+        created_at=created_at,
+        data=data or {},
+    )
+
+
+def _doc_to_summary_entry(doc_id: str, doc: dict[str, Any]) -> MemorySummaryEntry:
+    ts_str = doc.get("ts") or doc.get("created_at") or ""
+    created_at = _parse_ts(ts_str) if ts_str else datetime.utcnow()
+
+    tw = doc.get("time_window") or {}  # expected to have 'from' and 'to'
+    from_str = tw.get("from") or tw.get("start") or ""
+    to_str = tw.get("to") or tw.get("end") or ""
+    time_from = _parse_ts(from_str) if from_str else created_at
+    time_to = _parse_ts(to_str) if to_str else created_at
+
+    # prefer 'summary' field, fallback to text if present
+    text = doc.get("summary") or doc.get("text") or ""
+
+    # Strip out the core fields from metadata
+    meta_keys = {
+        "summary",
+        "text",
+        "scope_id",
+        "run_id",
+        "summary_tag",
+        "ts",
+        "time_window",
+    }
+    metadata = {k: v for k, v in doc.items() if k not in meta_keys}
+
+    return MemorySummaryEntry(
+        summary_id=doc_id,
+        scope_id=doc.get("scope_id") or doc.get("run_id") or "",
+        summary_tag=doc.get("summary_tag"),
+        created_at=created_at,
+        time_from=time_from,
+        time_to=time_to,
+        text=text,
+        metadata=metadata,
+    )
+
+
+def _string_score(haystack: str, needle: str) -> float:
+    """
+    Very simple scoring: 0.0 if no match, 1.0 if case-insensitive substring match.
+    Placeholder until a real semantic index is wired in.
+    """
+    if not needle:
+        return 0.0
+    h = haystack.lower()
+    n = needle.lower()
+    return 1.0 if n in h else 0.0
+
+
+# ------------ API endpoints ------------ #
+@router.get("/memory/events", response_model=MemoryEventListResponse)
+async def list_memory_events(
+    scope_id: str,
+    kinds: Annotated[
+        str | None, Query(description="Comma-separated list of kinds to filter")
+    ] = None,  # noqa: B008
+    tags: Annotated[str | None, Query(description="Comma-separated list of tags to filter")] = None,  # noqa: B008
+    after: Annotated[datetime | None, Query()] = None,  # noqa: B008
+    before: Annotated[datetime | None, Query()] = None,  # noqa: B008
+    cursor: Annotated[str | None, Query()] = None,  # noqa: B008
+    limit: Annotated[int, Query(ge=1, le=200)] = 50,  # noqa: B008
+    identity: RequestIdentity = Depends(get_identity),  # noqa: B008
+) -> MemoryEventListResponse:
+    """
+    List raw memory events for a scope.
+
+    Currently:
+      - Treats `scope_id` as the underlying `run_id` used by HotLog/Persistence.
+      - Reads from HotLog only (recent in-memory events).
+      - Applies basic filters by kind, tag, and time.
+
+    TODO:
+      - Integrate with a long-term event store (Persistence queries).
+      - Implement cursor-based pagination.
+      - Optionally map scope_id → multiple runs.
+      - Filter by identity.user_id / org_id when multi-tenant.
+
+    NOTE:
+      - Currently reads from HotLog only (recent in-memory events),
+        NOT the long-term persistence/event log.
+      - Fetches up to hot_limit+10 and applies filters + cursor (offset) in Python.
+      - Pagination is therefore limited to the hot buffer; older events are not visible.
+    In the future, we may want to:
+      - Integrate with EventLog-based persistence for full history,
+      - Move filtering + pagination closer to the store layer.
+    """
+    container = current_services()
+    mem_factory = getattr(container, "memory_factory", None)
+    if mem_factory is None:
+        # No memory configured
+        return MemoryEventListResponse(events=[], next_cursor=None)
+
+    hotlog = mem_factory.hotlog
+
+    # Parse filters
+    kinds_list: list[str] | None = None
+    if kinds:
+        kinds_list = [k.strip() for k in kinds.split(",") if k.strip()]
+    tags_list: list[str] | None = None
+    if tags:
+        tags_list = [t.strip() for t in tags.split(",") if t.strip()]
+
+    # Fetch slightly more than limit to determine if there's a next page and
+    # we can filter in python
+    raw_events: list[Event] = await hotlog.recent(
+        scope_id,
+        kinds=kinds_list,
+        limit=mem_factory.hot_limit + 10,
+    )
+
+    filtered: list[Event] = []
+    for evt in raw_events:
+        dt = _parse_ts(evt.ts)
+        if after and dt <= after:
+            continue
+        if before and dt >= before:
+            continue
+        if tags_list:
+            evt_tags = evt.tags or []
+            if not any(t in evt_tags for t in tags_list):
+                continue
+        filtered.append(evt)
+
+    # Apply offset and limit
+    offset = decode_cursor(cursor)
+    page = filtered[offset : offset + limit]
+    api_events = [_event_to_api_event(e) for e in page]
+
+    next_cursor = encode_cursor(offset + limit) if len(filtered) > offset + limit else None
+    return MemoryEventListResponse(events=api_events, next_cursor=next_cursor)
+
+
+@router.get("/memory/summaries", response_model=MemorySummaryListResponse)
+async def list_memory_summaries(
+    scope_id: Annotated[str, Query()],
+    summary_tag: Annotated[str | None, Query()] = None,
+    cursor: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=200)] = 50,
+    identity: RequestIdentity = Depends(get_identity),  # noqa: B008
+) -> MemorySummaryListResponse:
+    """
+    List long-term memory summaries for a scope.
+
+    Currently:
+      - Scans the DocStore (memory_factory.docs) and filters docs where:
+          doc["scope_id"] == scope_id
+          and (summary_tag is None or doc["summary_tag"] == summary_tag)
+      - Converts each summary doc into MemorySummaryEntry.
+
+    TODO:
+      - Avoid full scan for large DocStores (add indexed queries).
+      - Implement cursor-based pagination.
+      - Optionally filter by identity.user_id / org_id.
+    """
+    container = current_services()
+    mem_factory = getattr(container, "memory_factory", None)
+    if mem_factory is None:
+        return MemorySummaryListResponse(summaries=[], next_cursor=None)
+
+    docs = mem_factory.docs
+
+    # DocStore.list() returns a list of doc_ids; we load and filter them
+    try:
+        doc_ids = await docs.list()
+    except TypeError:
+        # If the concrete DocStore doesn't support list(), return empty
+        return MemorySummaryListResponse(summaries=[], next_cursor=None)
+
+    entries: list[MemorySummaryEntry] = []
+
+    for doc_id in doc_ids:
+        doc = await docs.get(doc_id)
+        if not doc:
+            continue
+
+        if doc.get("scope_id") != scope_id:
+            continue
+
+        if summary_tag is not None and doc.get("summary_tag") != summary_tag:
+            continue
+
+        entries.append(_doc_to_summary_entry(doc_id, doc))
+
+    # Sort by created_at descending
+    entries.sort(key=lambda e: e.created_at, reverse=True)
+
+    if len(entries) > limit:
+        entries = entries[:limit]
+    return MemorySummaryListResponse(summaries=entries, next_cursor=None)
+
+
+@router.post("/memory/search", response_model=MemorySearchResponse)
+async def search_memory(
+    req: MemorySearchRequest,
+    identity: RequestIdentity = Depends(get_identity),  # noqa: B008
+) -> MemorySearchResponse:
+    """
+    Semantic/keyword memory search.
+
+    Current behavior:
+      - Uses a naive substring match over:
+          • recent HotLog events for the given scope_id (treated as run_id)
+          • all summary docs for that scope_id
+      - Returns MemorySearchHit with either `event` or `summary` populated.
+
+    TODO:
+      - Plug into a real semantic index / RAG backend (mem_factory.rag_facade).
+      - Support more advanced filters (kinds, tags, summary_tag) on the request.
+    """
+    container = current_services()
+    mem_factory = getattr(container, "memory_factory", None)
+    if mem_factory is None:
+        return MemorySearchResponse(hits=[])
+
+    scope_id = req.scope_id or ""
+    query = req.query or ""
+    top_k = getattr(req, "top_k", 10) or 10
+
+    hotlog = mem_factory.hotlog
+    docs = mem_factory.docs
+
+    hits: list[MemorySearchHit] = []
+
+    # 1) Search recent HotLog events
+    if scope_id:
+        raw_events: list[Event] = await hotlog.recent(
+            scope_id,
+            kinds=None,
+            limit=mem_factory.hot_limit,
+        )
+        for evt in raw_events:
+            text_parts: list[str] = []
+            if evt.text:
+                text_parts.append(evt.text)
+            if evt.data:
+                with suppress(Exception):
+                    text_parts.append(str(evt.data))
+            haystack = " ".join(text_parts)
+            score = _string_score(haystack, query)
+            if score <= 0.0:
+                continue
+
+            api_evt = _event_to_api_event(evt)
+            hits.append(
+                MemorySearchHit(
+                    score=score,
+                    event=api_evt,
+                    summary=None,
+                )
+            )
+
+    # 2) Search summary docs
+    try:
+        doc_ids = await docs.list()
+    except TypeError:
+        doc_ids = []
+
+    for doc_id in doc_ids:
+        doc = await docs.get(doc_id)
+        if not doc:
+            continue
+
+        if scope_id and doc.get("scope_id") != scope_id:
+            continue
+
+        text_parts: list[str] = []
+        if doc.get("summary"):
+            text_parts.append(str(doc.get("summary")))
+
+        if doc.get("key_facts"):
+            with suppress(Exception):
+                text_parts.append(" ".join(map(str, doc["key_facts"])))
+
+        haystack = " ".join(text_parts)
+        score = _string_score(haystack, query)
+        if score <= 0.0:
+            continue
+
+        summary_entry = _doc_to_summary_entry(doc_id, doc)
+        hits.append(
+            MemorySearchHit(
+                score=score,
+                event=None,
+                summary=summary_entry,
+            )
+        )
+
+    # Sort by score (desc) and truncate
+    hits.sort(key=lambda h: h.score, reverse=True)
+    if len(hits) > top_k:
+        hits = hits[:top_k]
+
+    return MemorySearchResponse(hits=hits)

aethergraph/api/v1/misc.py

@@ -0,0 +1,47 @@
+# /health /config
+
+
+from fastapi import APIRouter, Depends
+
+from .deps import RequestIdentity, get_identity
+from .schemas import ConfigLLMProvider, ConfigResponse, HealthResponse
+
+router = APIRouter(tags=["misc"])
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    """
+    Simple health check endpoint.
+    """
+    # TODO: optionally include deeper checks (DB, Redis, etc.)
+    return HealthResponse(status="ok", version="0.1.0a1")
+
+
+@router.get("/config", response_model=ConfigResponse)
+async def config_info(
+    identity: RequestIdentity = Depends(get_identity),  # noqa: B008
+) -> ConfigResponse:
+    """
+    Return sanitized config info that's safe for UI.
+
+    TODO:
+      - Read from AppSettings.
+      - Mask secrets; only expose high-level info.
+    """
+    # Stub example
+    return ConfigResponse(
+        version="0.1.0a1",
+        storage_backends={
+            "memory": "fs_jsonl",
+            "artifacts": "fs",
+        },
+        llm_providers=[
+            ConfigLLMProvider(name="openai", model="gpt-4o-mini", enabled=True),
+        ],
+        features={
+            "ws_channels": True,
+            "artifact_search": True,
+            "memory_search": True,
+        },
+    )