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

aethergraph/services/memory/facade/distillation.py

@@ -2,11 +2,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
-from aethergraph.contracts.services.memory import Event
-
 # Assuming this external util exists based on original imports
 from ..utils import _summary_prefix
-from .utils import now_iso, stable_event_id
 
 if TYPE_CHECKING:
     from .types import MemoryFacadeInterface
@@ -115,16 +112,55 @@ class DistillationMixin:
                 min_signal=min_signal if min_signal is not None else self.default_signal_threshold,
             )
 
-        return await d.distill(
+        result = await d.distill(
             run_id=self.run_id,
             timeline_id=self.timeline_id,
             scope_id=scope_id or self.memory_scope_id,
             hotlog=self.hotlog,
-            persistence=self.persistence,
-            indices=self.indices,
             docs=self.docs,
         )
 
+        # If nothing returned, return empty dict
+        if not result:
+            return {}
+
+        # Record the summary as a memory event via record_raw
+        preview = result.get("preview", "")
+        num_events = result.get("num_events", 0)
+        time_window = result.get("time_window", {})
+
+        # Use a different stage + tags depending on LLM or not
+        stage = "summary_llm" if use_llm else "summary"
+        tags = ["summary", summary_tag]
+        if use_llm:
+            tags.append("llm")
+
+        evt = await self.record_raw(
+            base={
+                "kind": summary_kind,  # e.g. "long_term_summary"
+                "stage": stage,  # "summary_llm" or "summary"
+                "tags": tags,
+                "data": {
+                    "summary_doc_id": result.get("summary_doc_id"),
+                    "summary_tag": summary_tag,
+                    "time_window": time_window,
+                    "num_events": num_events,
+                },
+                "scope_id": scope_id,
+                # run_id / graph_id / node_id / session_id / user/org/client
+                # etc. are filled in by record_raw from self.scope.
+                "severity": 2,
+                # optional: slight bias; record_raw will compute a default signal if None
+                "signal": 0.7 if use_llm else None,
+            },
+            text=preview,
+            metrics={"num_events": num_events},
+        )
+
+        # Optionally return the event_id with the result
+        result["event_id"] = evt.event_id
+        return result
+
     async def distill_meta_summary(
         self,
         scope_id: str | None = None,
@@ -217,16 +253,44 @@ class DistillationMixin:
             max_summaries=max_summaries,
             min_signal=min_signal if min_signal is not None else self.default_signal_threshold,
         )
-        return await d.distill(
+        result = await d.distill(
             run_id=self.run_id,
             timeline_id=self.timeline_id,
             scope_id=scope_id or self.memory_scope_id,
             hotlog=self.hotlog,
-            persistence=self.persistence,
-            indices=self.indices,
             docs=self.docs,
         )
 
+        # If nothing returned, return empty dict
+        if not result:
+            return {}
+        # Record the meta-summary as a memory event via record_raw
+        preview = result.get("preview", "")
+        num_summaries = result.get("num_source_summaries", 0)
+        time_window = result.get("time_window", {})
+        evt = await self.record_raw(
+            base={
+                "kind": summary_kind,  # e.g. "meta_summary"
+                "stage": "meta_summary_llm",
+                "tags": ["summary", "llm", summary_tag],
+                "data": {
+                    "summary_doc_id": result.get("summary_doc_id"),
+                    "summary_tag": summary_tag,
+                    "time_window": time_window,
+                    "num_source_summaries": num_summaries,
+                },
+                "scope_id": scope_id,
+                # run_id / graph_id / node_id / session_id / user/org/client
+                # etc. are filled in by record_raw from self.scope.
+                "severity": 2,
+                "signal": 0.8,
+            },
+            text=preview,
+            metrics={"num_source_summaries": num_summaries},
+        )
+        result["event_id"] = evt.event_id
+        return result
+
     async def load_last_summary(
         self,
         scope_id: str | None = None,
@@ -393,32 +457,23 @@ class DistillationMixin:
         if not summary:
             return None
 
-        text = summary.get("text") or ""
+        text = summary.get("text") or summary.get("summary") or ""  # try both fields
         preview = text[:2000] + (" …[truncated]" if len(text) > 2000 else "")
 
-        evt = Event(
-            scope_id=self.memory_scope_id or self.run_id,
-            event_id=stable_event_id(
-                {
-                    "ts": now_iso(),
-                    "run_id": self.run_id,
-                    "kind": f"{summary_kind}_hydrate",
-                    "summary_tag": summary_tag,
-                    "preview": preview[:200],
-                }
-            ),
-            ts=now_iso(),
-            run_id=self.run_id,
-            kind=f"{summary_kind}_hydrate",
-            stage="hydrate",
+        await self.record_raw(
+            base={
+                "kind": f"{summary_kind}_hydrate",
+                "stage": "hydrate",
+                "tags": ["summary", "hydrate", summary_tag],
+                "data": {"summary": summary},
+                "scope_id": scope_id,
+                # run_id / graph_id / node_id / session_id / user/org/client
+                # etc. are filled in by record_raw from self.scope.
+                "severity": 1,
+                "signal": 0.4,
+            },
             text=preview,
-            tags=["summary", "hydrate", summary_tag],
-            data={"summary": summary},
             metrics={"num_events": summary.get("num_events", 0)},
-            severity=1,
-            signal=0.4,
         )
 
-        await self.hotlog.append(self.timeline_id, evt, ttl_s=self.hot_ttl_s, limit=self.hot_limit)
-        await self.persistence.append_event(self.timeline_id, evt)
         return summary

aethergraph/services/memory/facade/retrieval.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import json
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from aethergraph.contracts.storage.search_backend import ScoredItem
 
 if TYPE_CHECKING:
     from aethergraph.contracts.services.memory import Event
@@ -9,9 +11,52 @@ if TYPE_CHECKING:
     from .types import MemoryFacadeInterface
 
 
+class EventSearchResult(NamedTuple):
+    item: ScoredItem
+    event: Event | None
+
+    @property
+    def score(self) -> float:
+        return self.item.score
+
+
 class RetrievalMixin:
     """Methods for retrieving events and values."""
 
+    async def get_event(self, event_id: str) -> Event | None:
+        """
+        Retrieve a specific event by its ID.
+
+        This method fetches an event corresponding to the provided event ID.
+
+        Args:
+            event_id: The unique identifier of the event to retrieve.
+
+        Returns:
+            Event | None: The event object if found; otherwise, None.
+
+        Notes:
+            This method interacts with the underlying Persistence service to fetch
+            the event associated with the current timeline. If no event is found
+            with the given ID, it returns None.
+        """
+        # 1) Try hotlog
+        recent = await self.hotlog.recent(
+            self.timeline_id,
+            kinds=None,
+            limit=self.hot_limit,
+        )
+        for e in recent:
+            if e.event_id == event_id:
+                return e
+
+        # 2) Fallback to persistence
+        if hasattr(self.persistence, "get_events_by_ids"):
+            events = await self.persistence.get_events_by_ids(self.timeline_id, [event_id])
+            return events[0] if events else None
+
+        return None
+
     async def recent(
         self: MemoryFacadeInterface, *, kinds: list[str] | None = None, limit: int = 50
     ) -> list[Event]:
@@ -36,6 +81,21 @@ class RetrievalMixin:
         """
         return await self.hotlog.recent(self.timeline_id, kinds=kinds, limit=limit)
 
+    async def recent_events(
+        self,
+        *,
+        kinds: list[str] | None = None,
+        tags: list[str] | None = None,
+        limit: int = 50,
+        overfetch: int = 5,
+    ) -> list[Event]:
+        fetch_n = limit if not tags else max(limit * overfetch, 100)
+        evts = await self.recent(kinds=kinds, limit=fetch_n)
+        if tags:
+            want = set(tags)
+            evts = [e for e in evts if want.issubset(set(e.tags or []))]
+        return evts[-limit:]
+
     async def recent_data(
         self: MemoryFacadeInterface,
         *,
@@ -137,3 +197,42 @@ class RetrievalMixin:
         # if not (self.llm and any(e.embedding for e in events)): return lexical_hits or events
         # ... logic ...
         return lexical_hits or events
+
+    async def fetch_events_for_search_results(
+        self,
+        scored_items: list[ScoredItem],
+        corpus: str = "event",
+    ) -> list[EventSearchResult]:
+        """
+        Given a list of ScoredItems from a search, fetch the corresponding Event objects.
+        """
+
+        # Filter to event corpus
+        event_items = [item for item in scored_items if item.corpus == corpus]
+        if not event_items:
+            return []
+
+        ids = [it.item_id for it in event_items]
+
+        # 1) Try hotlog first
+        recent = await self.hotlog.recent(
+            self.timeline_id,
+            kinds=None,
+            limit=1,
+            # limit=self.hot_limit,
+        )
+        by_id: dict[str, Event] = {e.event_id: e for e in recent if e.event_id in ids}
+
+        # 2) Fallback to persistence for misses
+        missing_ids = [eid for eid in ids if eid not in by_id]
+        if missing_ids and hasattr(self.persistence, "get_events_by_ids"):
+            persisted = await self.persistence.get_events_by_ids(self.timeline_id, missing_ids)
+            for e in persisted:
+                by_id[e.event_id] = e
+
+        # 3) Build results
+        results: list[EventSearchResult] = []
+        for item in event_items:
+            evt = by_id.get(item.item_id)
+            results.append(EventSearchResult(item=item, event=evt))
+        return results

aethergraph/services/memory/factory.py

@@ -6,6 +6,7 @@ from typing import Any
 from aethergraph.contracts.services.artifacts import AsyncArtifactStore  # generic protocol
 from aethergraph.contracts.services.memory import HotLog, Indices, Persistence
 from aethergraph.contracts.storage.doc_store import DocStore
+from aethergraph.services.indices.scoped_indices import ScopedIndices
 from aethergraph.services.memory.facade import MemoryFacade
 from aethergraph.services.scope.scope import Scope
 
@@ -63,6 +64,7 @@ class MemoryFactory:
         node_id: str | None = None,
         session_id: str | None = None,
         scope: Scope | None = None,
+        scoped_indices: ScopedIndices | None = None,
     ) -> MemoryFacade:
         return MemoryFacade(
             run_id=run_id,
@@ -72,7 +74,8 @@ class MemoryFactory:
             scope=scope,
             hotlog=self.hotlog,
             persistence=self.persistence,
-            indices=self.indices,
+            mem_indices=self.indices,
+            scoped_indices=scoped_indices,
             docs=self.docs,
             artifact_store=self.artifacts,
             hot_limit=self.hot_limit,

aethergraph/services/planning/action_catalog.py

@@ -0,0 +1,271 @@
+# aethergraph/services/planning/action_catalog.py
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from aethergraph.core.graph.action_spec import ActionSpec, IOSlot
+from aethergraph.services.planning.graph_io_adapter import graph_io_to_slots
+from aethergraph.services.registry.registry_key import Key
+from aethergraph.services.registry.unified_registry import UnifiedRegistry
+
+if TYPE_CHECKING:
+    from aethergraph.core.graph.graph_fn import GraphFunction
+
+
+@dataclass
+class ActionCatalog:
+    registry: UnifiedRegistry
+
+    # --- builders ---------------------------------------------------------
+
+    def _build_graphfn_spec(self, name: str, version: str | None = None) -> ActionSpec:
+        gf: GraphFunction = self.registry.get_graphfn(name, version=version)
+        meta = self.registry.get_meta("graphfn", name, version=version) or {}
+        io = gf.io_signature()
+
+        flow_id = meta.get("flow_id", None)
+        tags = meta.get("tags", []) or []
+        description = meta.get("description", None)
+
+        # io_signature from GraphFunction are already IOSlot
+        inputs: list[IOSlot] = io.get("inputs", [])
+        outputs: list[IOSlot] = io.get("outputs", [])
+
+        # resolve final version used
+        latest_version = self.registry.list_graphfns().get(
+            f"graphfn:{name}",
+            version or "0.0.0",
+        )
+
+        return ActionSpec(
+            name=name,
+            ref=Key(nspace="graphfn", name=name, version=latest_version).canonical(),
+            kind="graphfn",
+            version=latest_version,
+            inputs=inputs,
+            outputs=outputs,
+            description=description,
+            tags=tags,
+            flow_id=flow_id,
+        )
+
+    def _build_graph_spec(self, name: str, version: str | None = None) -> ActionSpec:
+        g = self.registry.get_graph(name, version=version)
+        meta = self.registry.get_meta("graph", name, version=version) or {}
+
+        flow_id = meta.get("flow_id")
+        tags = meta.get("tags") or []
+        description = meta.get("description") or name
+
+        # pass meta to adapter so it can use io_types
+        io_slots = graph_io_to_slots(g, meta=meta)
+        inputs = io_slots["inputs"]
+        outputs = io_slots["outputs"]
+
+        latest_version = self.registry.list_graphs().get(
+            f"graph:{name}",
+            version or "0.0.0",
+        )
+
+        return ActionSpec(
+            name=name,
+            ref=Key(nspace="graph", name=name, version=latest_version).canonical(),
+            kind="graph",
+            version=latest_version,
+            description=description,
+            tags=list(tags),
+            flow_id=flow_id,
+            inputs=inputs,
+            outputs=outputs,
+        )
+
+    # --- listing / filtering ---------------------------------------------
+
+    def _flow_filter(
+        self,
+        spec: ActionSpec,
+        *,
+        flow_ids: list[str] | None,
+        include_global: bool,
+    ) -> bool:
+        """
+        Decide whether to include this spec given flow_ids and include_global.
+        - spec.flow_id is a single string or None.
+        - flow_ids is the set of flows we care about, or None for 'no filtering'.
+        """
+        if flow_ids is None:
+            # no restriction → include everything
+            return True
+
+        if spec.flow_id in flow_ids:
+            return True
+
+        # allow "global" actions when requested
+        if include_global and spec.flow_id is None:  # noqa: SIM103
+            return True
+
+        return False
+
+    def list_actions(
+        self,
+        *,
+        flow_ids: list[str] | None = None,
+        kinds: Iterable[Literal["graph", "graphfn"]] | None = ("graph", "graphfn"),
+        include_global: bool = True,
+    ) -> list[ActionSpec]:
+        """
+        Return all ActionSpecs, optionally filtered by:
+          - kinds (graph vs graphfn)
+          - flow_ids (one or more flow ids)
+          - include_global: if True, also include actions with flow_id=None
+        """
+        specs: list[ActionSpec] = []
+
+        if kinds is None:
+            kinds = ("graph", "graphfn")
+
+        if "graphfn" in kinds:
+            for key, ver in self.registry.list_graphfns().items():
+                _, name = key.split(":", 1)
+                spec = self._build_graphfn_spec(name, version=ver)
+                if not self._flow_filter(spec, flow_ids=flow_ids, include_global=include_global):
+                    continue
+                specs.append(spec)
+
+        if "graph" in kinds:
+            for key, ver in self.registry.list_graphs().items():
+                _, name = key.split(":", 1)
+                spec = self._build_graph_spec(name, version=ver)
+                if not self._flow_filter(spec, flow_ids=flow_ids, include_global=include_global):
+                    continue
+                specs.append(spec)
+
+        # stable order
+        specs.sort(key=lambda s: (s.flow_id or "", s.name, s.version))
+        return specs
+
+    def iter_actions(
+        self,
+        *,
+        flow_ids: list[str] | None = None,
+        kinds: Iterable[Literal["graph", "graphfn"]] | None = ("graph", "graphfn"),
+        include_global: bool = True,
+    ) -> Iterator[ActionSpec]:
+        for spec in self.list_actions(  # noqa: UP028
+            flow_ids=flow_ids,
+            kinds=kinds,
+            include_global=include_global,
+        ):
+            yield spec
+
+    # --- lookups ---------------------------------------------------------
+
+    def get_action(self, ref: str) -> ActionSpec | None:
+        kind, rest = ref.split(":", 1)
+        name, sep, version = rest.partition("@")
+        version = version or None
+
+        if kind == "graphfn":
+            return self._build_graphfn_spec(name, version=version)
+        if kind == "graph":
+            return self._build_graph_spec(name, version=version)
+        raise ValueError(f"Unknown action kind in ref: {ref}")
+
+    def get_action_by_name(
+        self,
+        name: str,
+        *,
+        kind: Literal["graph", "graphfn"] | None = None,
+        flow_ids: list[str] | None = None,
+        include_global: bool = True,
+    ) -> ActionSpec | None:
+        """
+        Convenience lookup: find an ActionSpec by its logical name.
+        """
+        if kind is None:
+            kinds: Iterable[Literal["graph", "graphfn"]] = ("graph", "graphfn")
+        else:
+            kinds = (kind,)
+
+        for spec in self.list_actions(
+            flow_ids=flow_ids,
+            kinds=kinds,
+            include_global=include_global,
+        ):
+            if spec.name == name:
+                return spec
+        return None
+
+    # --- LLM-facing renderers -------------------------------------------
+
+    def to_llm_prompt(
+        self,
+        *,
+        flow_ids: list[str] | None = None,
+        kinds: Iterable[Literal["graph", "graphfn"]] | None = ("graph", "graphfn"),
+        include_global: bool = True,
+    ) -> str:
+        actions = self.list_actions(
+            flow_ids=flow_ids,
+            kinds=kinds,
+            include_global=include_global,
+        )
+        lines: list[str] = []
+        for a in actions:
+            lines.append(f"- {a.name} ({a.kind})")
+            lines.append(f"  ref: {a.ref}")
+            lines.append(f"  description: {a.description}")
+            if a.tags:
+                lines.append(f"  tags: {', '.join(a.tags)}")
+            if a.inputs:
+                lines.append("  inputs:")
+                for inp in a.inputs:
+                    t = inp.type or "any"
+                    req = "required" if inp.required else f"optional (default={inp.default!r})"
+                    lines.append(f"    - {inp.name}: {t}, {req}")
+            if a.outputs:
+                lines.append("  outputs:")
+                for out in a.outputs:
+                    t = out.type or "any"
+                    lines.append(f"    - {out.name}: {t}")
+            lines.append("")
+        return "\n".join(lines)
+
+    def pretty_print(
+        self,
+        *,
+        flow_ids: list[str] | None = None,
+        kinds: Iterable[Literal["graph", "graphfn"]] | None = ("graph", "graphfn"),
+        include_global: bool = True,
+    ) -> str:
+        """
+        Human-readable table for planner prompts.
+
+        Emphasizes the short action name to be used in the \"action\" field
+        of the plan JSON. The internal ref is shown only as secondary info.
+        """
+        actions = self.list_actions(
+            flow_ids=flow_ids,
+            kinds=kinds,
+            include_global=include_global,
+        )
+        lines: list[str] = []
+
+        for a in actions:
+            inputs = ", ".join(f"{s.name}:{s.type or 'any'}" for s in a.inputs)
+            outputs = ", ".join(f"{s.name}:{s.type or 'any'}" for s in a.outputs)
+            tag_str = ", ".join(a.tags or [])
+
+            lines.append(f"- action: {a.name}  [{a.kind}]")
+            lines.append(f"  description: {a.description or '-'}")
+            lines.append(f"  inputs: {inputs or 'none'}")
+            lines.append(f"  outputs: {outputs or 'none'}")
+            if tag_str:
+                lines.append(f"  tags: {tag_str}")
+            # keep ref but label as internal; this discourages the LLM from using it
+            lines.append(f"  internal_ref: {a.ref}")
+            lines.append("")  # blank line between actions
+
+        return "\n".join(lines)

aethergraph/services/planning/bindings.py

@@ -0,0 +1,56 @@
+# aethergraph/services/planning/bindings.py
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass
+class InputBinding:
+    kind: Literal["literal", "external", "step_output"]
+    value: Any
+    source_step_id: str | None = None
+    source_output_name: str | None = None
+    external_key: str | None = None
+
+
+def parse_binding(raw: Any) -> InputBinding:
+    """
+    Parses a raw binding representation into an InputBinding object.
+
+    Rules:
+    - If `raw` is not a string, it is treated as a literal value. (which may include numbers, booleans, lists, dicts, etc.)
+    - If `raw` is a string in the format `${user.key}`, it is treated as an external binding.
+    - If `raw` is a string in the format `${step_id.output_name}`, it is treated as a step output binding.
+
+    Args:
+        raw (Any): The raw binding representation, which can be a literal value or a dict specifying the binding type.
+
+    Returns:
+        InputBinding: The parsed InputBinding object.
+    """
+    if not isinstance(raw, str):
+        return InputBinding(kind="literal", value=raw)
+
+    if raw.startswith("${") and raw.endswith("}"):
+        inner = raw[2:-1].strip()
+        if inner.startswith("user."):
+            key = inner.split(".", 1)[1]
+            return InputBinding(kind="external", value=None, external_key=key)
+
+        # step_id.output_name
+        parts = inner.split(".", 1)
+        if len(parts) == 2:
+            step_id, output_name = parts
+            return InputBinding(
+                kind="step_output",
+                value=None,
+                source_step_id=step_id,
+                source_output_name=output_name,
+            )
+
+        # Fallback to literal if unrecognized
+        return InputBinding(kind="literal", value=raw)
+
+    return InputBinding(kind="literal", value=raw)