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

aethergraph/services/memory/facade/results.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from aethergraph.contracts.services.memory import Event
+
+if TYPE_CHECKING:
+    from .types import MemoryFacadeInterface
+
+
+class ResultMixin:
+    """Methods for recording tool execution results.
+    NOTE: there are many potentially overlapping methods here. We will deprecate most of them
+    over time in favor of a smaller, clearer set.
+
+    Include methods:
+    - write_result (general)
+    - write_tool_result (deprecated, use record_tool_result)
+    - record_result (general alias)
+    - record_tool_result (dedicated to tools)
+    - last_tool_result
+    - recent_tool_result_data
+
+    The following are convenience wrappers. TODO: standardize naming
+    - last_by_name
+    - last_output_by_name
+    - last_outputs_by_topic
+    - last_tool_result_outputs
+    - latest_refs_by_kind
+    """
+
+    async def record_tool_result(
+        self: MemoryFacadeInterface,
+        *,
+        tool: str,
+        inputs: list[dict[str, Any]] | None = None,
+        outputs: list[dict[str, Any]] | None = None,
+        tags: list[str] | None = None,
+        metrics: dict[str, float] | None = None,
+        message: str | None = None,
+        severity: int = 3,
+    ) -> Event:
+        """
+        Record the result of a tool execution in a normalized format.
+
+        This method provides the method to log tool execution results with standardized metadata.
+        Interally, it constructs an `Event` object encapsulating details about the tool execution,
+        including inputs, outputs, tags, metrics, and a descriptive message.
+
+        Examples:
+            Recording a tool result with inputs and outputs:
+            ```python
+            await context.memory().record_tool_result(
+                tool="data_cleaner",
+                inputs=[{"raw_data": "some raw input"}],
+                outputs=[{"cleaned_data": "processed output"}],
+                tags=["data", "cleaning"],
+                metrics={"execution_time": 1.23},
+                message="Tool executed successfully.",
+                severity=2,
+            )
+            ```
+
+            Logging a tool result with minimal metadata:
+            ```python
+            await context.memory().record_tool_result(
+                tool="simple_logger",
+                message="Logged an event.",
+            )
+            ```
+
+        Args:
+            tool: The name of the tool that generated the result.
+            inputs: A list of dictionaries representing the tool's input data.
+            outputs: A list of dictionaries representing the tool's output data.
+            tags: A list of string labels for categorization.
+            metrics: A dictionary of numerical metrics (e.g., execution time, accuracy).
+            message: A descriptive message about the tool's execution or result.
+            severity: An integer (1-5) indicating the importance or severity of the result.
+            (1=Lowest, 5=Highest).
+
+        Returns:
+            Event: The fully persisted `Event` object containing the generated ID and timestamp.
+        """
+        return await self.write_tool_result(
+            tool=tool,
+            inputs=inputs,
+            outputs=outputs,
+            tags=tags,
+            metrics=metrics,
+            message=message,
+            severity=severity,
+        )
+
+    async def recent_tool_results(
+        self,
+        *,
+        tool: str,
+        limit: int = 10,
+    ) -> list[Event]:
+        """
+        Retrieve recent tool execution results for a specific tool.
+
+        This method filters and returns the most recent `tool_result` events
+        associated with the specified tool, allowing you to analyze or process
+        the results of tool executions.
+
+        Examples:
+            Fetching the 5 most recent results for a tool:
+            ```python
+            recent_results = await context.memory().recent_tool_results(
+                tool="data_cleaner",
+                limit=5,
+            )
+            for result in recent_results:
+                print(result)
+            ```
+
+            Retrieving all available results for a tool (up to the default limit):
+            ```python
+            recent_results = await context.memory().recent_tool_results(
+                tool="simple_logger",
+            )
+            ```
+
+        Args:
+            tool: The name of the tool whose results are being queried.
+            limit: The maximum number of results to return (default is 10).
+
+        Returns:
+            list[Event]: A list of `Event` objects representing the recent
+            `tool_result` events for the specified tool, ordered by recency.
+        """
+        events = await self.recent(kinds=["tool_result"], limit=100)
+        tool_events = [e for e in events if e.tool == tool]
+        return tool_events[:limit]
+
+    async def recent_tool_result_data(
+        self,
+        *,
+        tool: str,
+        limit: int = 10,
+    ) -> list[dict[str, Any]]:
+        """
+        Return a simplified view over recent tool_result events.
+
+        This method provides a developer-friendly way to retrieve recent tool execution results
+        in a normalized format, including metadata such as timestamps, inputs, outputs, and tags.
+
+        Examples:
+            Fetching recent tool result data:
+            ```python
+            recent_data = await context.memory().recent_tool_result_data(
+                tool="data_cleaner",
+                limit=5,
+            )
+            for entry in recent_data:
+                print(entry)
+            ```
+
+        Args:
+            tool: The name of the tool whose results are being queried.
+            limit: The maximum number of recent results to retrieve.
+
+        Returns:
+            list[dict[str, Any]]: A list of dictionaries, each containing:
+                - "ts": The timestamp of the event.
+                - "tool": The name of the tool.
+                - "message": A descriptive message about the tool's execution.
+                - "inputs": The input data provided to the tool.
+                - "outputs": The output data generated by the tool.
+                - "tags": A list of string labels associated with the event.
+        """
+        events = await self.recent_tool_results(tool=tool, limit=limit)
+        out: list[dict[str, Any]] = []
+        for e in events:
+            out.append(
+                {
+                    "ts": getattr(e, "ts", None),
+                    "tool": e.tool,
+                    "message": e.text,
+                    "inputs": getattr(e, "inputs", None),
+                    "outputs": getattr(e, "outputs", None),
+                    "tags": list(e.tags or []),
+                }
+            )
+        return out
+
+    async def write_result(
+        self: MemoryFacadeInterface,
+        *,
+        tool: str | None = None,  # back compatibility with 'topic'
+        inputs: list[dict[str, Any]] | None = None,
+        outputs: list[dict[str, Any]] | None = None,
+        tags: list[str] | None = None,
+        metrics: dict[str, float] | None = None,
+        message: str | None = None,
+        severity: int = 3,
+        topic: str | None = None,  # alias for tool, backwards compatibility
+    ) -> Event:
+        """
+        Convenience for recording a “tool/agent/flow result” with typed I/O.
+
+        `tool`    : tool/agent/flow identifier (also used by KVIndices.last_outputs_by_topic)
+        `inputs`  : List[Value]-like dicts
+        `outputs` : List[Value]-like dicts
+        `tags`    : labels like ["rag","qa"] for filtering/search
+        """
+        if tool is None and topic is not None:
+            tool = topic
+        if tool is None:
+            raise ValueError("write_result requires a 'tool' (or legacy 'topic') name")
+
+        inputs = inputs or []
+        outputs = outputs or []
+
+        evt = await self.record_raw(
+            base=dict(
+                tool=tool,
+                kind="tool_result",
+                severity=severity,
+                tags=tags or [],
+                inputs=inputs,
+                outputs=outputs,
+            ),
+            text=message,
+            metrics=metrics,
+        )
+        await self.indices.update(self.timeline_id, evt)
+        return evt
+
+    async def write_tool_result(
+        self: MemoryFacadeInterface,
+        *,
+        tool: str,
+        inputs: list[dict[str, Any]] | None = None,
+        outputs: list[dict[str, Any]] | None = None,
+        tags: list[str] | None = None,
+        metrics: dict[str, float] | None = None,
+        message: str | None = None,
+        severity: int = 3,
+    ) -> Event:
+        """
+        Convenience wrapper around write_result() for tool results.
+        """
+        return await self.write_result(
+            tool=tool,
+            inputs=inputs,
+            outputs=outputs,
+            tags=tags,
+            metrics=metrics,
+            message=message,
+            severity=severity,
+        )
+
+    async def record_result(
+        self: MemoryFacadeInterface,
+        *,
+        tool: str | None = None,
+        inputs: list[dict[str, Any]] | None = None,
+        outputs: list[dict[str, Any]] | None = None,
+        tags: list[str] | None = None,
+        metrics: dict[str, float] | None = None,
+        message: str | None = None,
+        severity: int = 3,
+    ) -> Event:
+        """
+        Alias for write_result(); symmetric with record_tool_result().
+
+        Use this when you conceptually have a "result" but don't care whether
+        it's a tool vs agent vs flow.
+        """
+        return await self.write_result(
+            tool=tool,
+            inputs=inputs,
+            outputs=outputs,
+            tags=tags,
+            metrics=metrics,
+            message=message,
+            severity=severity,
+        )
+
+    async def last_tool_result(self, tool: str) -> Event | None:
+        """
+        Convenience: return the most recent tool_result Event for a given tool.
+        """
+        events = await self.recent_tool_results(tool=tool, limit=1)
+        return events[-1] if events else None
+
+    async def last_by_name(self, name: str):
+        """Return the last output value by `name` from Indices (fast path)."""
+        return await self.indices.last_by_name(self.timeline_id, name)
+
+    async def last_output_by_name(self, name: str):
+        """Return the last output value (Value.value) by `name` from Indices (fast path)."""
+        out = await self.indices.last_by_name(self.timeline_id, name)
+        if out is None:
+            return None
+        return out.get("value")  # type: ignore
+
+    async def last_outputs_by_topic(self, topic: str):
+        """Return the last output map for a given topic (tool/flow/agent) from Indices."""
+        return await self.indices.last_outputs_by_topic(self.timeline_id, topic)
+
+    # replace last_tool_result_outputs
+    async def last_tool_result_outputs(self, tool: str) -> dict[str, Any] | None:
+        """
+        Convenience wrapper around KVIndices.last_outputs_by_topic for this run.
+        Returns the last outputs map for a given tool, or None.
+        """
+        return await self.indices.last_outputs_by_topic(self.timeline_id, tool)
+
+    async def latest_refs_by_kind(self, kind: str, *, limit: int = 50):
+        """Return latest ref outputs by ref.kind (fast path, KV-backed)."""
+        return await self.indices.latest_refs_by_kind(self.timeline_id, kind, limit=limit)

aethergraph/services/memory/facade/retrieval.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aethergraph.contracts.services.memory import Event
+
+    from .types import MemoryFacadeInterface
+
+
+class RetrievalMixin:
+    """Methods for retrieving events and values."""
+
+    async def recent(
+        self: MemoryFacadeInterface, *, kinds: list[str] | None = None, limit: int = 50
+    ) -> list[Event]:
+        """
+        Retrieve recent events.
+
+        This method fetches a list of recent events, optionally filtered by kinds.
+
+        Args:
+            kinds: A list of event kinds to filter by. Defaults to None.
+            limit: The maximum number of events to retrieve. Defaults to 50.
+
+        Returns:
+            list[Event]: A list of recent events.
+
+        Notes:
+            This method interacts with the underlying HotLog service to fetch events
+            associated with the current timeline. The events are returned in chronological order,
+            with the most recent events appearing last in the list. Memory out of the limit will be discarded
+            in the HotLog layer (but persistent in the Persistence layer). Memory in persistence cannot be retrieved
+            via this method.
+        """
+        return await self.hotlog.recent(self.timeline_id, kinds=kinds, limit=limit)
+
+    async def recent_data(
+        self: MemoryFacadeInterface,
+        *,
+        kinds: list[str] | None = None,
+        tags: list[str] | None = None,
+        limit: int = 50,
+    ) -> list[Any]:
+        """
+        Retrieve recent event data.
+
+        This method fetches the data or text of recent events, optionally filtered by kinds and tags.
+        Unlike `recent()`, which returns full Event objects, this method extracts and returns only the
+        data or text content of the events. This is useful for scenarios where only the event payloads are needed.
+
+        Args:
+            kinds: A list of event kinds to filter by. Defaults to None.
+            tags: A list of tags to filter events by. Defaults to None.
+            limit: The maximum number of events to retrieve. Defaults to 50.
+
+        Returns:
+            list[Any]: A list of event data or text.
+
+        Notes:
+            This method first retrieves recent events using the `recent()` method and then filters them
+            based on the provided tags. It extracts the `data` attribute if available; otherwise, it
+            attempts to parse the `text` attribute as JSON. If parsing fails, the raw text is returned.
+
+            Memory out of the limit will be discarded in the HotLog layer (but persistent in the Persistence layer).
+            Memory in persistence cannot be retrieved via this method.
+        """
+        evts = await self.recent(kinds=kinds, limit=limit)
+        if tags:
+            want = set(tags)
+            evts = [e for e in evts if want.issubset(set(e.tags or []))]
+
+        out: list[Any] = []
+        for e in evts:
+            if e.data is not None:
+                out.append(e.data)
+            elif e.text:
+                t = e.text.strip()
+                if (t.startswith("{") and t.endswith("}")) or (
+                    t.startswith("[") and t.endswith("]")
+                ):
+                    try:
+                        out.append(json.loads(t))
+                        continue
+                    except Exception:
+                        pass
+                out.append(e.text)
+        return out
+
+    async def search(
+        self: MemoryFacadeInterface,
+        *,
+        query: str,
+        kinds: list[str] | None = None,
+        tags: list[str] | None = None,
+        limit: int = 100,
+        use_embedding: bool = True,
+    ) -> list[Event]:
+        """
+        Search for events based on a query.
+
+        This method searches for events that match a query, optionally filtered by kinds and tags.
+        Note that this implementation currently performs a lexical search. Embedding-based search
+        is planned for future development.
+
+        Args:
+            query: The search query string.
+            kinds: A list of event kinds to filter by. Defaults to None.
+            tags: A list of tags to filter events by. Defaults to None.
+            limit: The maximum number of events to retrieve. Defaults to 100.
+            use_embedding: Whether to use embedding-based search. Defaults to True.
+
+        Returns:
+            list[Event]: A list of events matching the query.
+
+        Notes:
+            This method retrieves recent events using the `recent()` method and filters them
+            based on the provided tags. It performs a simple lexical search on the event text.
+            Embedding-based search functionality is not yet implemented.
+
+            Memory out of the limit will be discarded in the HotLog layer (but persistent in the Persistence layer).
+            Memory in persistence cannot be retrieved via this method.
+        """
+        events = await self.recent(kinds=kinds, limit=limit)
+        if tags:
+            want = set(tags)
+            events = [e for e in events if want.issubset(set(e.tags or []))]
+
+        query_l = query.lower()
+        lexical_hits = [e for e in events if (e.text or "").lower().find(query_l) >= 0]
+
+        if not use_embedding:
+            return lexical_hits or events
+
+        # Placeholder for future embedding search logic
+        # if not (self.llm and any(e.embedding for e in events)): return lexical_hits or events
+        # ... logic ...
+        return lexical_hits or events

aethergraph/services/memory/facade/types.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from aethergraph.contracts.services.llm import LLMClientProtocol
+from aethergraph.contracts.services.memory import Event, HotLog, Indices, Persistence
+from aethergraph.contracts.storage.artifact_store import AsyncArtifactStore
+from aethergraph.contracts.storage.doc_store import DocStore
+from aethergraph.services.rag.facade import RAGFacade
+from aethergraph.services.scope.scope import Scope
+
+
+class MemoryFacadeInterface(Protocol):
+    """
+    Protocol defining the state and core methods available on the MemoryFacade.
+    Mixins use this to type-hint 'self'.
+    """
+
+    run_id: str
+    timeline_id: str
+    memory_scope_id: str
+
+    hotlog: HotLog
+    persistence: Persistence
+    indices: Indices
+    docs: DocStore
+    artifacts: AsyncArtifactStore
+    scope: Scope | None
+
+    rag: RAGFacade | None
+    llm: LLMClientProtocol | None
+    logger: Any
+
+    default_signal_threshold: float
+    hot_limit: int
+    hot_ttl_s: int
+
+    async def record_raw(
+        self,
+        *,
+        base: dict[str, Any],
+        text: str | None = None,
+        metrics: dict[str, float] | None = None,
+    ) -> Event: ...
+
+    async def record(
+        self,
+        kind: str,
+        data: Any,
+        tags: list[str] | None = None,
+        severity: int = 2,
+        stage: str | None = None,
+        inputs_ref=None,
+        outputs_ref=None,
+        metrics: dict[str, float] | None = None,
+        signal: float | None = None,
+    ) -> Event: ...
+
+    async def write_result(
+        self,
+        *,
+        tool: str,
+        inputs: list[dict[str, Any]] | None = None,
+        outputs: list[dict[str, Any]] | None = None,
+        tags: list[str] | None = None,
+        metrics: dict[str, float] | None = None,
+        message: str | None = None,
+        severity: int = 3,
+    ) -> Event: ...
+
+    # Required for RetrievalMixin to expose 'recent' to other mixins
+    async def recent(self, *, kinds: list[str] | None = None, limit: int = 50) -> list[Event]: ...
+
+    # Required for RAGMixin to expose 'rag_bind'
+    async def rag_bind(
+        self, *, key: str = "default", create_if_missing: bool = True, labels: dict | None = None
+    ) -> str: ...

aethergraph/services/memory/facade/utils.py

@@ -0,0 +1,43 @@
+import hashlib
+import json
+import os
+import re
+import time
+from typing import Any
+import unicodedata
+
+_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def stable_event_id(parts: dict[str, Any]) -> str:
+    blob = json.dumps(parts, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    return hashlib.sha256(blob).hexdigest()[:24]
+
+
+def short_hash(s: str, n: int = 8) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()[:n]
+
+
+def slug(s: str) -> str:
+    s = unicodedata.normalize("NFKC", str(s)).strip()
+    s = s.replace(" ", "-")
+    s = _SAFE.sub("-", s)
+    return s.strip("-") or "default"
+
+
+def load_sticky(path: str) -> dict:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def save_sticky(path: str, m: dict):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(m, f, ensure_ascii=False, indent=2)