power-loop 0.2.0__py3-none-any.whl

power_loop/runtime/compact.py

@@ -0,0 +1,300 @@
+"""Context compaction — protocol + default implementation (M1.7a).
+
+Design contract (from ROADMAP §M1.7a / README §1):
+
+* Triggered every ``round.start`` when estimated tokens >=
+  ``max_tokens × trigger_ratio`` (or absolute ``CONTEXT_COMPACT_THRESHOLD``
+  env override). Idempotent within a round.
+* **Preserve** the first ``role=system`` message (the original system_prompt)
+	and ``memory_*`` messages. Old ``compact_note`` messages are foldable —
+	the new summary merges them so at most one compact_note ever exists.
+* **Preserve** the last ``keep_last_n`` exchanges. An exchange is a
+  ``user / assistant(+optional tool_calls) / tool*`` triple — never split
+  the atomic ``assistant(tool_calls)`` ↔ matching ``tool(tool_call_id=…)``
+  pair.
+* Summarize the cuttable middle via a separate LLM call (default = main
+  LLM; injectable ``summary_llm`` for cheaper models).
+* Insert one ``system / name=compact_note`` message in place of the cut
+  range.
+* Fail-soft: on summary error, return ``None`` plan → caller continues with
+  uncompacted history; the pipeline then escalates to ``loop.degraded``
+  only if the main LLM rejects on context-overflow.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from llm_client.interface import LLMRequest
+from power_loop.runtime.budget import estimate_tokens
+
+
+@dataclass(frozen=True)
+class CompactionPlan:
+    """The output of a successful compaction round.
+
+    ``fold_start_idx`` and ``fold_end_idx`` are **inclusive** indices into
+    the pipeline's in-memory ``history`` list; everything between them is
+    replaced by one ``compact_note`` message at ``fold_start_idx``.
+    """
+
+    fold_start_idx: int
+    fold_end_idx: int
+    summary_text: str
+    before_tokens: int
+    after_tokens: int
+
+
+@runtime_checkable
+class Compactor(Protocol):
+    """A pluggable strategy that decides whether and how to compact."""
+
+    async def maybe_compact(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        llm: Any,
+        max_tokens: int,
+        round_index: int,
+    ) -> CompactionPlan | None: ...
+
+
+# ── default implementation ──────────────────────────────────────────────
+
+
+class DefaultCompactor:
+    """Vendor-neutral compactor matching the M1.7a contract."""
+
+    def __init__(
+        self,
+        *,
+        trigger_ratio: float = 0.75,
+        keep_last_n: int = 4,
+        summary_max_tokens: int = 5000,
+        summary_llm: Any | None = None,
+        absolute_threshold: int | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        trigger_ratio
+            Fire when ``estimate_tokens(history) ≥ max_tokens × trigger_ratio``.
+            Default 0.75 leaves headroom for the next round's prompt + reply.
+        keep_last_n
+            Preserve the last N **user-bounded exchanges** verbatim (not
+            summarized). This is the freshest context the model needs to
+            answer the next turn well; folding it hurts reply quality
+            dramatically. ``keep_last_n=1`` ≈ "aggressive — summarize
+            everything but the last user turn"; the default 4 follows
+            Anthropic's compaction guide.
+        summary_max_tokens
+            Token cap for the summary LLM call. Since at most one compact_note
+            exists at any time (each compaction merges the old note into the
+            new one), this can be generous — 5000 is a good default for
+            preserving detailed context across many compaction rounds.
+        summary_llm
+            Optional cheaper LLM dedicated to the summary call. Defaults
+            to the main loop's LLM.
+        absolute_threshold
+            Absolute token count that overrides ``trigger_ratio`` when
+            non-None. Env ``CONTEXT_COMPACT_THRESHOLD`` always wins over
+            this if set.
+        """
+        self.trigger_ratio = float(trigger_ratio)
+        self.keep_last_n = int(keep_last_n)
+        self.summary_max_tokens = int(summary_max_tokens)
+        self.summary_llm = summary_llm
+        self.absolute_threshold = absolute_threshold
+
+    # ── public ──────────────────────────────────────────────────────────
+
+    async def maybe_compact(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        llm: Any,
+        max_tokens: int,
+        round_index: int,
+    ) -> CompactionPlan | None:
+        before = estimate_tokens(messages)
+        if not self._should_trigger(before, max_tokens):
+            return None
+        span = self._compactable_span(messages)
+        if span is None:
+            return None
+        start, end = span
+        summary = await self._summarize_async(messages[start : end + 1], llm=llm)
+        if summary is None:
+            return None  # soft-fail; caller continues uncompacted
+        after = estimate_tokens(
+            [*messages[:start], _note(summary), *messages[end + 1 :]]
+        )
+        return CompactionPlan(
+            fold_start_idx=start,
+            fold_end_idx=end,
+            summary_text=summary,
+            before_tokens=before,
+            after_tokens=after,
+        )
+
+    # ── trigger ─────────────────────────────────────────────────────────
+
+    def _should_trigger(self, before_tokens: int, max_tokens: int) -> bool:
+        # Env override (read lazily so monkeypatch in tests works).
+        env = os.environ.get("CONTEXT_COMPACT_THRESHOLD")
+        absolute = int(env) if env else self.absolute_threshold
+        if absolute is not None:
+            return before_tokens >= absolute
+        if max_tokens <= 0:
+            return False
+        return before_tokens >= int(max_tokens * self.trigger_ratio)
+
+    # ── span selection ──────────────────────────────────────────────────
+
+    def _compactable_span(
+        self, messages: list[dict[str, Any]]
+    ) -> tuple[int, int] | None:
+        """Return the inclusive index range we can safely fold, or None.
+
+        Preserves the first ``system`` message (the original system_prompt)
+        and ``memory_*`` messages. Old ``compact_note`` messages are foldable
+        so at most one compact_note ever exists.
+        """
+        n = len(messages)
+        if n == 0:
+            return None
+        # Find end of preserved system block: first system msg + memory_* msgs.
+        sys_end = 0
+        # Always preserve the first system message (the original system_prompt).
+        if sys_end < n and messages[sys_end].get("role") == "system":
+            sys_end = 1
+            # Preserve subsequent memory_* messages (they share system-region protection).
+            while sys_end < n and messages[sys_end].get("role") == "system":
+                name = messages[sys_end].get("name") or ""
+                if name.startswith("memory_"):
+                    sys_end += 1
+                else:
+                    break
+        # Decide the tail boundary by counting exchanges from the end.
+        tail_start = self._tail_start(messages, sys_end)
+        if tail_start <= sys_end:
+            return None
+        # Don't split a pending pair.
+        tail_start = self._expand_back_to_atomic(messages, tail_start)
+        if tail_start <= sys_end:
+            return None
+        end = tail_start - 1
+        while end > sys_end and messages[end].get("role") == "tool":
+            end -= 1
+        if end < sys_end:
+            return None
+        return (sys_end, end)
+
+    def _tail_start(self, messages: list[dict[str, Any]], sys_end: int) -> int:
+        """Count exchanges from the tail; return the index of the start of
+        the kept tail. An "exchange" begins at a ``user`` message."""
+        n = len(messages)
+        if n == sys_end:
+            return n
+        kept = 0
+        i = n - 1
+        boundary = n
+        while i >= sys_end:
+            if messages[i].get("role") == "user":
+                kept += 1
+                if kept >= self.keep_last_n:
+                    boundary = i
+                    break
+            i -= 1
+        else:
+            boundary = sys_end  # not enough exchanges → keep everything after sys
+        return boundary
+
+    @staticmethod
+    def _expand_back_to_atomic(
+        messages: list[dict[str, Any]], tail_start: int
+    ) -> int:
+        """If ``messages[tail_start]`` is a ``tool`` and the corresponding
+        ``assistant(tool_calls)`` is below the boundary, pull the boundary
+        back so the pair stays together."""
+        if tail_start >= len(messages):
+            return tail_start
+        msg = messages[tail_start]
+        if msg.get("role") != "tool":
+            return tail_start
+        # walk back to the matching assistant
+        j = tail_start - 1
+        while j >= 0:
+            m = messages[j]
+            if m.get("role") == "assistant" and m.get("tool_calls"):
+                return j
+            j -= 1
+        return tail_start
+
+    # ── summarization ───────────────────────────────────────────────────
+
+    async def _summarize_async(
+        self, slice_msgs: list[dict[str, Any]], *, llm: Any
+    ) -> str | None:
+        if not slice_msgs:
+            return None
+        summary_llm = self.summary_llm or llm
+        prompt = (
+            "You are a conversation summarizer. Below is a slice of an "
+            "agent's working transcript that needs to be compressed for "
+            "context-window economy. The slice may include prior compact_notes — "
+            "merge their content into your summary so there is at most ONE "
+            "compact note at any time. Preserve: (1) decisions made, "
+            "(2) facts established, (3) errors and how they were handled, "
+            "(4) any pending intent the assistant was about to act on. "
+            "Do NOT call tools. Wrap your summary in <summary>…</summary>.\n\n"
+            "--- transcript slice ---\n"
+            + _stringify_slice(slice_msgs)
+        )
+        try:
+            response = await summary_llm.complete(
+                LLMRequest(
+                    messages=[{"role": "user", "content": prompt}],
+                    max_tokens=self.summary_max_tokens,
+                    temperature=0.0,
+                )
+            )
+        except Exception:
+            return None
+        text = (
+            getattr(response, "raw_text", "")
+            or getattr(response, "content_text", "")
+            or ""
+        ).strip()
+        if not text:
+            return None
+        # Strip <summary>…</summary> if present.
+        if text.startswith("<summary>") and "</summary>" in text:
+            text = text[len("<summary>") :].split("</summary>")[0].strip()
+        return text or None
+
+
+# ── helpers ─────────────────────────────────────────────────────────────
+
+
+def _stringify_slice(slice_msgs: list[dict[str, Any]]) -> str:
+    lines: list[str] = []
+    for m in slice_msgs:
+        role = m.get("role", "?")
+        content = m.get("content")
+        text = content if isinstance(content, str) else str(content or "")
+        head = f"[{role}]"
+        tool_calls = m.get("tool_calls")
+        if tool_calls:
+            head += f" tool_calls={len(tool_calls)}"
+        lines.append(f"{head}\n{text}")
+    return "\n\n".join(lines)
+
+
+def _note(text: str) -> dict[str, Any]:
+    return {"role": "system", "name": "compact_note", "content": text}
+
+
+__all__ = ["Compactor", "CompactionPlan", "DefaultCompactor"]

power_loop/runtime/env.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+AGENT_DIR = Path(__file__).resolve().parent.parent.parent
+WORKSPACE_ENV_KEYS = (
+    "POWER_LOOP_WORKSPACE",
+    "ZERO_CODE_WORKSPACE",
+    "ZERO_CODE_WORKDIR",
+    "VSCODE_WORKSPACE_FOLDER",
+)
+
+
+def _resolve_workspace_dir() -> Path:
+    for key in WORKSPACE_ENV_KEYS:
+        value = (os.environ.get(key) or "").strip()
+        if value:
+            return Path(value).expanduser().resolve()
+    return Path.cwd().resolve()
+
+
+WORKSPACE_DIR = _resolve_workspace_dir()
+WORKDIR = WORKSPACE_DIR
+DEFAULT_SKILLS_DIR = AGENT_DIR / ".skills"
+
+
+def _resolve_skills_dir() -> Path:
+    raw = (os.environ.get("POWER_LOOP_SKILLS_DIR") or os.environ.get("ZERO_CODE_SKILLS_DIR") or "").strip()
+    if not raw:
+        return DEFAULT_SKILLS_DIR
+
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        candidate = (AGENT_DIR / candidate).resolve()
+    else:
+        candidate = candidate.resolve()
+
+    if candidate.exists() and candidate.is_dir():
+        return candidate
+    return DEFAULT_SKILLS_DIR
+
+
+SKILLS_DIR = _resolve_skills_dir()
+AGENT_RW_ALLOWLIST = (
+    AGENT_DIR / ".cache",
+    AGENT_DIR / "logs",
+    SKILLS_DIR,
+)
+
+
+def _is_in_agent_rw_allowlist(path: Path) -> bool:
+    resolved = path.resolve()
+    for allowed_root in AGENT_RW_ALLOWLIST:
+        try:
+            if resolved.is_relative_to(allowed_root.resolve()):
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def safe_path(p: str, purpose: str = "rw") -> Path:
+    raw_input = (p or "").strip()
+    if not raw_input:
+        raise ValueError("Path is required")
+
+    if raw_input.startswith("@workspace/"):
+        candidate = (WORKSPACE_DIR / raw_input[len("@workspace/") :]).resolve()
+    elif raw_input.startswith("@agent/"):
+        candidate = (AGENT_DIR / raw_input[len("@agent/") :]).resolve()
+    else:
+        raw = Path(raw_input).expanduser()
+        if raw.is_absolute():
+            candidate = raw.resolve()
+        else:
+            candidate = (WORKSPACE_DIR / raw).resolve()
+
+    if candidate.is_relative_to(WORKSPACE_DIR):
+        return candidate
+
+    if candidate.is_relative_to(AGENT_DIR):
+        if _is_in_agent_rw_allowlist(candidate):
+            return candidate
+        try:
+            rel_to_agent = candidate.relative_to(AGENT_DIR)
+            workspace_alt = WORKSPACE_DIR / rel_to_agent
+            hint = (
+                f" Did you mean the workspace file instead? "
+                f"Try: {rel_to_agent} (resolves to {workspace_alt})"
+            )
+        except ValueError:
+            hint = ""
+        raise ValueError(
+            f"Access to agent home is restricted.{hint} "
+            f"Workspace is at {WORKSPACE_DIR}, not {AGENT_DIR}. "
+            "Use relative paths (they default to workspace) or @workspace/<path>."
+        )
+
+    raise ValueError(
+        f"Path escapes allowed directories: {p}. "
+        f"Workspace: {WORKSPACE_DIR}. Use relative paths or @workspace/<path>."
+    )

power_loop/runtime/memory.py

@@ -0,0 +1,107 @@
+"""MemoryProvider — pluggable long-term / cross-session memory.
+
+Library scope
+-------------
+power-loop **does not implement a memory backend**. It defines:
+
+* the ``MemoryProvider`` Protocol callers implement,
+* a ``MemorySnapshot`` shape passed to ``remember``,
+* the pipeline integration points (``MEMORY_RECALLED`` hook +
+  ``MEMORY_RECALLED`` / ``MEMORY_FAILED`` events),
+* the **inject position** invariant (after existing system messages,
+  after compact_note, before the conversation history).
+
+Concrete backends live in callers' code or in ``examples/`` — SQLite
+fact store, HTTP API diary, vector DB RAG, etc. — none of them belong
+in the library.
+
+Failure model
+-------------
+* ``recall`` raises → treated as **no memory** (returns ``[]``) and emit
+  ``MEMORY_FAILED``. Loop continues.
+* ``remember`` raises → emit ``MEMORY_FAILED``. ``StatefulResult`` is
+  still returned unchanged. Persisting memory must never block the user
+  from getting a reply.
+* Hook ``MEMORY_RECALLED`` returning ``HookDirective.SKIP`` → drop the
+  recalled messages (do not inject).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+LoopMessage = dict[str, Any]
+
+
+@dataclass
+class MemorySnapshot:
+    """What ``remember`` receives at session end.
+
+    Includes the **full final history** (messages list as seen by the
+    pipeline at SESSION_END time, after any compaction). Providers
+    typically only persist a summary or selected facts; the full
+    snapshot is supplied so the provider can decide.
+    """
+
+    session_id: str
+    messages: list[LoopMessage] = field(default_factory=list)
+    final_text: str = ""
+    rounds: int = 0
+    status: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class MemoryProvider(Protocol):
+    """Caller-implemented memory backend.
+
+    ``recall`` is called **once per send** (at SESSION_START, before the
+    first round). The returned list is injected as ``role=system``
+    messages with ``name`` prefixed ``memory_*`` (the library tags them
+    automatically if you don't). Returning ``[]`` means "no memory this
+    session".
+
+    ``remember`` is called at SESSION_END regardless of status (including
+    ``cancelled`` and ``degraded``); callers that only want to persist
+    successful sessions should check ``snapshot.status`` themselves.
+    """
+
+    async def recall(
+        self,
+        *,
+        messages: list[LoopMessage],
+        session_id: str | None,
+        budget_tokens: int = 1500,
+    ) -> list[LoopMessage]:
+        ...
+
+    async def remember(
+        self,
+        *,
+        snapshot: MemorySnapshot,
+        session_id: str | None,
+    ) -> None:
+        ...
+
+
+def tag_as_memory(messages: list[LoopMessage], *, prefix: str = "memory_") -> list[LoopMessage]:
+    """Ensure every recalled message is a system message with a ``name``
+    starting ``memory_*``. Idempotent; non-destructive (returns new dicts).
+
+    The library calls this on the provider's output before injection so
+    downstream code (hooks, compactor, audit) can identify memory rows
+    by ``msg.get("name", "").startswith("memory_")``.
+    """
+    tagged: list[LoopMessage] = []
+    for i, m in enumerate(messages):
+        m2 = dict(m)
+        m2["role"] = "system"
+        name = str(m2.get("name") or "")
+        if not name.startswith(prefix):
+            m2["name"] = f"{prefix}{name or i}"
+        tagged.append(m2)
+    return tagged
+
+
+__all__ = ["LoopMessage", "MemorySnapshot", "MemoryProvider", "tag_as_memory"]

power_loop/runtime/provider.py

@@ -0,0 +1,176 @@
+"""Unified LLM provider configuration (M1.4).
+
+Why
+---
+The library wraps a **single** transport today —
+``OpenAICompatibleChatLLMService`` — but speaks to many actual providers
+through it (OpenAI, DashScope/Qwen, DeepSeek, OpenRouter, Together,
+Groq, local OpenAI-compatible servers). Each caller used to assemble an
+``OpenAICompatibleChatConfig`` by hand and read env vars in its own way,
+which made provider-swapping a per-call code change.
+
+``LLMProviderConfig`` is the single config shape callers should target.
+Two factories build an ``LLMService`` from it:
+
+* :func:`create_llm_service_from_config` — given an explicit config.
+* :func:`create_llm_service_from_env` — assembles from environment
+  variables (``POWER_LOOP_*``), falling back to legacy
+  ``OPENAI_COMPAT_*`` names so existing ``.env`` files keep working.
+
+The ``provider`` field is currently informational (a string tag) — when
+we add Anthropic-native transport in M3 it becomes the router key.
+Callers that want to pin to a specific provider can set it; today it
+does not affect the transport.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from llm_client.interface import LLMService, OpenAICompatibleChatConfig
+from llm_client.llm_factory import OpenAICompatibleChatLLMService
+
+DEFAULT_PREFIX = "POWER_LOOP"
+LEGACY_PREFIX = "OPENAI_COMPAT"
+
+
+@dataclass
+class LLMProviderConfig:
+    """Unified, provider-agnostic LLM config.
+
+    Required: ``base_url`` / ``api_key`` / ``model``. Everything else
+    has sensible defaults that match :class:`OpenAICompatibleChatConfig`.
+
+    ``provider`` is a free-form tag (``"openai"`` / ``"dashscope"`` /
+    ``"deepseek"`` / …) used today only for telemetry and human
+    readability; it becomes the routing key when multi-transport lands.
+    """
+
+    base_url: str
+    api_key: str
+    model: str
+    provider: str = "openai"
+    timeout_s: float = 180.0
+    max_tokens: int = 8000
+    temperature: float = 0.0
+    max_retries: int = 3
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Fail fast at config build time, not on the first complete() call.
+        missing = [
+            name for name, val in (("base_url", self.base_url),
+                                   ("api_key", self.api_key),
+                                   ("model", self.model))
+            if not val
+        ]
+        if missing:
+            raise ValueError(
+                f"LLMProviderConfig missing required field(s): {', '.join(missing)}"
+            )
+
+    # ── Factories ───────────────────────────────────────────────────────
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        prefix: str = DEFAULT_PREFIX,
+        fallback_prefix: str | None = LEGACY_PREFIX,
+        env: dict[str, str] | None = None,
+    ) -> LLMProviderConfig:
+        """Build a config from ``{PREFIX}_*`` environment variables.
+
+        Reads (in order of preference):
+
+        * ``{prefix}_BASE_URL`` / ``{prefix}_API_KEY`` / ``{prefix}_MODEL``
+          (required)
+        * ``{prefix}_PROVIDER`` / ``{prefix}_TIMEOUT_S`` /
+          ``{prefix}_MAX_TOKENS`` / ``{prefix}_TEMPERATURE`` /
+          ``{prefix}_MAX_RETRIES`` (optional)
+
+        If ``fallback_prefix`` is set and a primary var is missing, falls
+        back to the same suffix under the fallback prefix. Default
+        fallback is ``OPENAI_COMPAT`` so existing ``.env`` files
+        (``OPENAI_COMPAT_BASE_URL`` etc.) keep working without edits.
+
+        ``env`` argument is for tests; defaults to ``os.environ``.
+        """
+        src: dict[str, str] = dict(os.environ if env is None else env)
+
+        def _get(name: str, default: str | None = None) -> str | None:
+            primary = src.get(f"{prefix}_{name}")
+            if primary:
+                return primary
+            if fallback_prefix:
+                alt = src.get(f"{fallback_prefix}_{name}")
+                if alt:
+                    return alt
+            return default
+
+        base_url = _get("BASE_URL", "")
+        api_key = _get("API_KEY", "")
+        model = _get("MODEL", "")
+        provider = _get("PROVIDER", "openai") or "openai"
+        timeout_s = float(_get("TIMEOUT_S", "180") or 180)
+        max_tokens = int(_get("MAX_TOKENS", "8000") or 8000)
+        temperature = float(_get("TEMPERATURE", "0") or 0)
+        max_retries = int(_get("MAX_RETRIES", "3") or 3)
+
+        return cls(
+            base_url=base_url or "",
+            api_key=api_key or "",
+            model=model or "",
+            provider=provider,
+            timeout_s=timeout_s,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            max_retries=max_retries,
+        )
+
+    # ── Adaptation ──────────────────────────────────────────────────────
+
+    def to_openai_compatible(self) -> OpenAICompatibleChatConfig:
+        """Render into the transport-specific config the current backend
+        expects. New transports (Anthropic-native in M3) will add their
+        own adapter alongside this one.
+        """
+        return OpenAICompatibleChatConfig(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            model=self.model,
+            timeout_s=self.timeout_s,
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+            max_retries=self.max_retries,
+        )
+
+
+def create_llm_service_from_config(cfg: LLMProviderConfig) -> LLMService:
+    """Build an ``LLMService`` from an :class:`LLMProviderConfig`.
+
+    Today this always returns an ``OpenAICompatibleChatLLMService``;
+    when a second transport lands it will dispatch on ``cfg.provider``.
+    """
+    return OpenAICompatibleChatLLMService(cfg.to_openai_compatible())
+
+
+def create_llm_service_from_env(
+    *,
+    prefix: str = DEFAULT_PREFIX,
+    fallback_prefix: str | None = LEGACY_PREFIX,
+) -> LLMService:
+    """One-liner for the common case: read env, build, return service."""
+    cfg = LLMProviderConfig.from_env(prefix=prefix, fallback_prefix=fallback_prefix)
+    return create_llm_service_from_config(cfg)
+
+
+__all__ = [
+    "DEFAULT_PREFIX",
+    "LEGACY_PREFIX",
+    "LLMProviderConfig",
+    "create_llm_service_from_config",
+    "create_llm_service_from_env",
+]