@gralkor/openclaw 4.0.0

package/server/server/pipelines/capture_buffer.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable
+
+from google.genai.errors import APIError as _GenaiAPIError
+from graphiti_core.llm_client.errors import RateLimitError as _GraphitiRateLimitError
+
+from .messages import Message
+
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_RETRY_DELAYS: tuple[float, ...] = (1.0, 2.0, 4.0)
+
+
+# Exceptions raised by the Vertex-upstream path. These are NOT retried
+# at the buffer layer — see gralkor/TEST_TREES.md > Retry ownership:
+# 429 retry is owned by /recall only, and retrying upstream failures
+# here would amplify load on an already-struggling upstream without
+# a meaningful chance of success. `APIError` covers the SDK's
+# 408/429/5xx/4xx path; graphiti's `RateLimitError` is what its
+# GeminiClient raises on rate-limit classification.
+_UPSTREAM_ERROR: tuple[type[BaseException], ...] = (
+    _GenaiAPIError,
+    _GraphitiRateLimitError,
+)
+
+
+class CaptureClientError(Exception):
+    """Raised when a downstream client returned a non-retryable 4xx response."""
+
+
+FlushCallback = Callable[[str, str, list[list[Message]]], Awaitable[None]]
+
+
+@dataclass
+class _Entry:
+    group_id: str
+    agent_name: str
+    turns: list[list[Message]] = field(default_factory=list)
+
+
+class CaptureBuffer:
+    def __init__(
+        self,
+        flush_callback: FlushCallback,
+        retry_delays: tuple[float, ...] = DEFAULT_RETRY_DELAYS,
+    ) -> None:
+        self._entries: dict[str, _Entry] = {}
+        self._flush_callback = flush_callback
+        self._retry_delays = retry_delays
+        self._pending_flushes: set[asyncio.Task[None]] = set()
+
+    def append(
+        self,
+        session_id: str,
+        group_id: str,
+        agent_name: str,
+        messages: list[Message],
+    ) -> None:
+        if agent_name is None or not str(agent_name).strip():
+            raise ValueError("agent_name is required and must be non-blank")
+        entry = self._entries.get(session_id)
+        if entry is None:
+            entry = _Entry(group_id=group_id, agent_name=agent_name)
+            self._entries[session_id] = entry
+        else:
+            if entry.group_id != group_id:
+                raise ValueError(
+                    f"session_id {session_id!r} already bound to group_id "
+                    f"{entry.group_id!r}; refusing to rebind to {group_id!r}"
+                )
+            if entry.agent_name != agent_name:
+                raise ValueError(
+                    f"session_id {session_id!r} already bound to agent_name "
+                    f"{entry.agent_name!r}; refusing to rebind to {agent_name!r}"
+                )
+        entry.turns.append(list(messages))
+
+    def turns_for(self, session_id: str) -> list[list[Message]]:
+        entry = self._entries.get(session_id)
+        return [list(turn) for turn in entry.turns] if entry is not None else []
+
+    async def _flush_with_retry(
+        self,
+        session_id: str,
+        group_id: str,
+        agent_name: str,
+        turns: list[list[Message]],
+    ) -> None:
+        attempt = 0
+        while True:
+            try:
+                await self._flush_callback(group_id, agent_name, turns)
+                return
+            except CaptureClientError as err:
+                logger.error(
+                    "capture dropped (4xx) session=%s group=%s turns=%d err=%s",
+                    session_id,
+                    group_id,
+                    len(turns),
+                    err,
+                )
+                return
+            except _UPSTREAM_ERROR as err:
+                logger.error(
+                    "capture dropped (upstream error — see Retry ownership) "
+                    "session=%s group=%s turns=%d err=%s",
+                    session_id,
+                    group_id,
+                    len(turns),
+                    err,
+                )
+                return
+            except Exception as err:
+                if attempt >= len(self._retry_delays):
+                    logger.error(
+                        "capture exhausted session=%s group=%s turns=%d err=%s",
+                        session_id,
+                        group_id,
+                        len(turns),
+                        err,
+                    )
+                    return
+                logger.warning(
+                    "capture retry session=%s group=%s attempt=%d err=%s",
+                    session_id,
+                    group_id,
+                    attempt + 1,
+                    err,
+                )
+                await asyncio.sleep(self._retry_delays[attempt])
+                attempt += 1
+
+    def flush(self, session_id: str) -> None:
+        entry = self._entries.pop(session_id, None)
+        if entry is None:
+            return
+        task = asyncio.create_task(
+            self._flush_with_retry(session_id, entry.group_id, entry.agent_name, entry.turns)
+        )
+        self._pending_flushes.add(task)
+        task.add_done_callback(self._pending_flushes.discard)
+
+    async def flush_all(self) -> None:
+        for session_id in list(self._entries.keys()):
+            entry = self._entries.pop(session_id, None)
+            if entry is None:
+                continue
+            if entry.turns:
+                task = asyncio.create_task(
+                    self._flush_with_retry(
+                        session_id, entry.group_id, entry.agent_name, entry.turns
+                    )
+                )
+                self._pending_flushes.add(task)
+                task.add_done_callback(self._pending_flushes.discard)
+        if self._pending_flushes:
+            await asyncio.gather(*self._pending_flushes, return_exceptions=True)
+
+    @property
+    def pending_count(self) -> int:
+        return sum(len(entry.turns) for entry in self._entries.values())
+
+    def has(self, session_id: str) -> bool:
+        return session_id in self._entries

package/server/server/pipelines/distill.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from .messages import Message
+
+if TYPE_CHECKING:
+    from graphiti_core.llm_client import LLMClient
+
+
+logger = logging.getLogger(__name__)
+
+
+DISTILL_SYSTEM_PROMPT = (
+    "You are a distillery for agentic thought and action. You will be given an agent's actions "
+    "during a turn, alongside the user's request and the agent's response for context. Write one "
+    "to two sentences in first person past tense capturing the reasoning, decisions, and actions "
+    "that drove the outcome — including dead ends and intermediary steps, not just the final "
+    "response. When the agent searched memory, do not restate the recalled facts — note only "
+    "that memory was consulted and what the agent concluded. Output only the distilled text."
+)
+
+
+class DistillResult(BaseModel):
+    behaviour: str
+
+
+def _require_agent_name(agent_name: str) -> None:
+    if agent_name is None or not str(agent_name).strip():
+        raise ValueError("agent_name is required and must be non-blank")
+
+
+def _render_label(role: str, agent_name: str) -> str:
+    if role == "user":
+        return "User"
+    if role == "assistant":
+        return agent_name
+    if role == "behaviour":
+        return agent_name
+    return role.capitalize()
+
+
+def _build_distill_input(messages: list[Message], agent_name: str) -> str:
+    has_behaviour = any(m.role == "behaviour" and m.content.strip() for m in messages)
+    if not has_behaviour:
+        return ""
+
+    lines: list[str] = []
+    for msg in messages:
+        text = msg.content.strip()
+        if not text:
+            continue
+        lines.append(f"{_render_label(msg.role, agent_name)}: {text}")
+    return "\n".join(lines)
+
+
+async def _distill_one(llm_client: "LLMClient", thinking: str) -> str:
+    from graphiti_core.prompts.models import Message as LLMMessage
+
+    prompt = [
+        LLMMessage(role="system", content=DISTILL_SYSTEM_PROMPT),
+        LLMMessage(role="user", content=thinking),
+    ]
+    response = await llm_client.generate_response(
+        prompt,
+        response_model=DistillResult,
+        max_tokens=150,
+    )
+    if isinstance(response, dict):
+        return (response.get("behaviour") or "").strip()
+    return ""
+
+
+async def safe_distill(llm_client: "LLMClient", thinking: str) -> str:
+    if not thinking.strip():
+        return ""
+    try:
+        return await _distill_one(llm_client, thinking)
+    except Exception as err:
+        logger.warning("behaviour distillation failed: %s", err)
+        return ""
+
+
+async def format_transcript(
+    turns: list[list[Message]],
+    llm_client: "LLMClient | None",
+    agent_name: str,
+) -> str:
+    _require_agent_name(agent_name)
+
+    distill_inputs = [(i, _build_distill_input(turn, agent_name)) for i, turn in enumerate(turns)]
+    distill_inputs = [(i, text) for i, text in distill_inputs if text]
+
+    summaries: dict[int, str] = {}
+    if distill_inputs and llm_client is not None:
+        results = await asyncio.gather(
+            *(safe_distill(llm_client, text) for _, text in distill_inputs)
+        )
+        for (i, _), summary in zip(distill_inputs, results):
+            if summary:
+                summaries[i] = summary
+
+    lines: list[str] = []
+    for i, turn in enumerate(turns):
+        user_texts = [m.content.strip() for m in turn if m.role == "user" and m.content.strip()]
+        for text in user_texts:
+            lines.append(f"User: {text}")
+
+        summary = summaries.get(i)
+        if summary:
+            lines.append(f"{agent_name}: (behaviour: {summary})")
+
+        answer_texts = [
+            m.content.strip() for m in turn if m.role == "assistant" and m.content.strip()
+        ]
+        for text in answer_texts:
+            lines.append(f"{agent_name}: {text}")
+    return "\n".join(lines)

package/server/server/pipelines/formatting.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+_FRACTIONAL_SECONDS = re.compile(r"\.\d+")
+_TRAILING_Z = re.compile(r"Z$")
+_TZ_OFFSET = re.compile(r"([+-])(\d{2}):(\d{2})$")
+
+
+def format_timestamp(ts: str) -> str:
+    s = _FRACTIONAL_SECONDS.sub("", ts)
+    s = _TRAILING_Z.sub("+0", s)
+
+    def _compact(match: re.Match[str]) -> str:
+        sign, hours_str, minutes_str = match.group(1), match.group(2), match.group(3)
+        hours = str(int(hours_str))
+        if minutes_str == "00":
+            return f"{sign}{hours}"
+        return f"{sign}{hours}:{minutes_str}"
+
+    return _TZ_OFFSET.sub(_compact, s)
+
+
+def format_fact(fact: dict[str, Any]) -> str:
+    parts = [f"- {fact['fact']}"]
+    if fact.get("created_at"):
+        parts.append(f" (created {format_timestamp(fact['created_at'])})")
+    if fact.get("valid_at"):
+        parts.append(f" (valid from {format_timestamp(fact['valid_at'])})")
+    if fact.get("invalid_at"):
+        parts.append(f" (invalid since {format_timestamp(fact['invalid_at'])})")
+    if fact.get("expired_at"):
+        parts.append(f" (expired {format_timestamp(fact['expired_at'])})")
+    return "".join(parts)
+
+
+def format_facts(facts: list[dict[str, Any]]) -> str:
+    if not facts:
+        return "No graph facts found."
+    lines = "\n".join(format_fact(f) for f in facts)
+    return f"Facts:\n{lines}"
+
+
+def format_node(node: dict[str, Any]) -> str:
+    summary = node.get("summary") or "(no summary)"
+    return f"- {node['name']}: {summary}"

package/server/server/pipelines/interpret.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .messages import Message
+
+if TYPE_CHECKING:
+    from graphiti_core.llm_client import LLMClient
+
+
+INTERPRET_SYSTEM_PROMPT = (
+    "You are reviewing recalled memory facts for an agent mid-conversation. "
+    "Each input fact is one line beginning with '- ' and may carry one or more "
+    "timestamp parentheticals such as '(created …)', '(valid from …)', "
+    "'(invalid since …)', '(expired …)'.\n\n"
+    "Return only the facts that bear on the current task. For each one, produce "
+    "a single string built from two parts joined by ' — ':\n"
+    "  1. The original fact copied verbatim WITHOUT the leading '- '. Preserve "
+    "every timestamp parenthetical exactly as given. Do not paraphrase, "
+    "summarise, merge facts, drop timestamps, or reformat them.\n"
+    "  2. One short sentence explaining why this fact is relevant to the "
+    "current task.\n\n"
+    "Example output entry: "
+    "'Alice works at Acme (valid from 2024-01-01) (expired 2025-06-01) — "
+    "confirms her former employer, which the user just asked about.'\n\n"
+    "Skip facts with no bearing on the current task. If no facts are relevant, "
+    "return an empty list. Do not return prose, prefixes, bullets, numbering, "
+    "or any wrapping object — only the list of strings in the schema."
+)
+
+INTERPRET_TOKEN_BUDGET = 250_000
+_CHARS_PER_TOKEN = 4
+INTERPRET_CHAR_BUDGET = INTERPRET_TOKEN_BUDGET * _CHARS_PER_TOKEN
+
+DEFAULT_OUTPUT_TOKEN_BUDGET = 2000
+
+
+class InterpretParseFailed(Exception):
+    """Raised when the LLM's interpret response cannot be parsed against the
+    InterpretResult schema — typically because output_token_budget was too
+    small and the response truncated mid-list. Distinct from generic
+    RuntimeError so callers can catch parse failure specifically."""
+
+    def __init__(self, message: str, raw_response: object = None) -> None:
+        super().__init__(message)
+        self.raw_response = raw_response
+
+
+class InterpretResult(BaseModel):
+    relevantFacts: list[str] = Field(
+        description=(
+            "List of relevant facts. Each entry is the original fact line "
+            "copied verbatim (without the leading '- ', preserving every "
+            "timestamp parenthetical such as '(valid from …)', '(invalid "
+            "since …)', '(expired …)', '(created …)'), followed by ' — ' "
+            "and one short sentence explaining why this fact is relevant. "
+            "Empty list if nothing is relevant. No prose, no bullets, no "
+            "numbering."
+        )
+    )
+
+
+def _require_agent_name(agent_name: str) -> None:
+    if agent_name is None or not str(agent_name).strip():
+        raise ValueError("agent_name is required and must be non-blank")
+
+
+def _require_positive_int(name: str, value: object) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise ValueError(f"{name} must be a positive integer, got {value!r}")
+    return value
+
+
+def _render_label(role: str, agent_name: str) -> str:
+    if role == "user":
+        return "User"
+    if role == "assistant":
+        return agent_name
+    if role == "behaviour":
+        return agent_name
+    return role.capitalize()
+
+
+def _budget_instruction(output_token_budget: int) -> str:
+    return (
+        f"Respond within {output_token_budget} tokens. Keep each relevance "
+        f"reason short so the full list fits."
+    )
+
+
+def build_interpretation_context(
+    messages: list[Message],
+    facts_text: str,
+    agent_name: str,
+    char_budget: int = INTERPRET_CHAR_BUDGET,
+) -> str:
+    _require_agent_name(agent_name)
+    lines: list[str] = []
+    for msg in messages:
+        text = msg.content.strip()
+        if not text:
+            continue
+        if msg.role == "behaviour":
+            lines.append(f"{agent_name}: (behaviour: {text})")
+        else:
+            lines.append(f"{_render_label(msg.role, agent_name)}: {text}")
+
+    budget = char_budget
+    trimmed: list[str] = []
+    for line in reversed(lines):
+        if budget <= 0:
+            break
+        trimmed.insert(0, line)
+        budget -= len(line)
+
+    return (
+        "Conversation context:\n"
+        + "\n".join(trimmed)
+        + "\n\nMemory facts to interpret:\n"
+        + facts_text
+    )
+
+
+async def interpret_facts(
+    messages: list[Message],
+    facts_text: str,
+    llm_client: "LLMClient",
+    agent_name: str,
+    output_token_budget: int = DEFAULT_OUTPUT_TOKEN_BUDGET,
+) -> list[str]:
+    _require_agent_name(agent_name)
+    _require_positive_int("output_token_budget", output_token_budget)
+    if llm_client is None:
+        raise RuntimeError(
+            "interpret_facts: llm_client is required (configure an LLM provider API key)"
+        )
+
+    from graphiti_core.prompts.models import Message as LLMMessage
+
+    context = build_interpretation_context(messages, facts_text, agent_name)
+    context_with_budget = context + "\n\n" + _budget_instruction(output_token_budget)
+    prompt = [
+        LLMMessage(role="system", content=INTERPRET_SYSTEM_PROMPT),
+        LLMMessage(role="user", content=context_with_budget),
+    ]
+
+    response = await llm_client.generate_response(
+        prompt,
+        response_model=InterpretResult,
+        max_tokens=output_token_budget,
+    )
+    if not isinstance(response, dict):
+        raise InterpretParseFailed(
+            "interpret_facts: response was not a dict (schema mismatch or truncation)",
+            raw_response=response,
+        )
+    raw = response.get("relevantFacts")
+    if not isinstance(raw, list):
+        raise InterpretParseFailed(
+            "interpret_facts: relevantFacts missing or not a list (schema mismatch or truncation)",
+            raw_response=response,
+        )
+    return [str(item).strip() for item in raw if str(item).strip()]

package/server/server/pipelines/messages.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+Role = Literal["user", "assistant", "behaviour"]
+
+
+class Message(BaseModel):
+    role: Role
+    content: str

package/server/server/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "gralkor-server"
+version = "0.0.0"
+requires-python = ">=3.12"
+dependencies = [
+    "graphiti-core[falkordb,anthropic,google-genai,groq]>=0.28.2",
+    "falkordblite",
+    "fastapi>=0.115",
+    "uvicorn>=0.34",
+    "pyyaml>=6.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-spec>=6.0",
+    "httpx>=0.27",
+]

package/server/server/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+asyncio_mode = auto
+addopts = --spec
+norecursedirs = mutants

package/server/server/requirements-dev.txt

@@ -0,0 +1,3 @@
+pytest>=8.0
+pytest-asyncio>=0.24
+httpx>=0.27

package/server/server/requirements.txt

@@ -0,0 +1,5 @@
+graphiti-core[falkordb]>=0.28
+falkordblite
+fastapi>=0.115
+uvicorn>=0.34
+pyyaml>=6.0