capt-hook 0.2.0__py3-none-any.whl

captain_hook/primitives/llm.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable, Sequence
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Literal
+
+from loguru import logger
+from pydantic import BaseModel
+
+from captain_hook import state
+from captain_hook.app import on
+from captain_hook.primitives.audit import session_id_for
+from captain_hook.prompt import Prompt, PromptMessage
+from captain_hook.state import PrimitiveState, fired_this_turn, hook_name, record_fire
+from captain_hook.types import (
+    Action,
+    Event,
+    HookResult,
+    InlineTests,
+    Signal,
+    Signals,
+    TCondition,
+)
+
+FAILURE_ROOT = state.CACHE_ROOT / "failures"
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+    from captain_hook.llm import TModel, TSpecialty
+    from captain_hook.signals.nlp import NlpSignal
+
+from captain_hook.signals import extract_signal_context, resolve_signals, transcript_texts
+
+
+class GateVerdict(BaseModel):
+    """LLM response model for ``llm_gate``. The LLM sets ``block=True`` to deny."""
+
+    block: bool
+    reasoning: str
+
+
+class NudgeVerdict(BaseModel):
+    """LLM response model for ``llm_nudge``. The LLM sets ``fire=True`` to trigger the nudge."""
+
+    fire: bool
+    reasoning: str
+
+
+class PromptCheckVerdict(BaseModel):
+    """LLM response model for ``prompt_check``. Action is ``"ok"``, ``"warning"``, or ``"block"``."""
+
+    action: Literal["ok", "warning", "block"]
+    reason: str
+
+
+def llm_evaluate[M: BaseModel](
+    evt: BaseHookEvent,
+    prompt: str,
+    response_model: type[M],
+    *,
+    signals: Sequence[Signal | NlpSignal] | Signals | None = None,
+    when: Callable[[BaseHookEvent], bool] | None = None,
+    max_context: int = 2000,
+    specialty: TSpecialty = "review",
+    model: TModel = "small",
+    agent: bool = False,
+    transcript: bool = False,
+) -> M | None:
+    if fired_this_turn(evt):
+        return None
+
+    if sig := resolve_signals(signals):
+        ps = evt.ctx.s[PrimitiveState].get(PrimitiveState())
+        texts = transcript_texts(evt, sig.window)
+        old_consumed = ps.consumed.copy()
+        if not (contributing_texts := ps.match_signals(sig, texts)):
+            evt.ctx.s[PrimitiveState].set(ps)
+            return None
+        ps.consumed = old_consumed
+        evt.ctx.s[PrimitiveState].set(ps)
+    elif when is not None and not when(evt):
+        return None
+    else:
+        contributing_texts = transcript_texts(evt, 5)
+
+    context = "\n".join(
+        [line for text in contributing_texts for line in extract_signal_context(sig.patterns, text)]
+        if sig
+        else contributing_texts
+    )[:max_context]
+
+    built = Prompt().system(prompt).context("context", context or None)
+
+    try:
+        return evt.ctx.call_llm(
+            built,
+            specialty=specialty,
+            model=model,
+            agent=agent,
+            transcript=transcript,
+            response_model=response_model,
+        )
+    except Exception:
+        logger.bind(prompt=prompt).opt(exception=True).warning("llm evaluate failed")
+        return None
+
+
+def consume_signals(evt: BaseHookEvent, sig: Signals | None) -> None:
+    if not sig:
+        return
+    ps = evt.ctx.s[PrimitiveState].get(PrimitiveState())
+    texts = transcript_texts(evt, sig.window)
+    ps.match_signals(sig, texts)
+    evt.ctx.s[PrimitiveState].set(ps)
+
+
+def llm_primitive[M: BaseModel](
+    prompt: str,
+    *,
+    action: Action,
+    label: str,
+    message: str | Callable[[M], str],
+    response_model: type[M],
+    verdict: Callable[[M], bool],
+    default_events: Event,
+    default_max_fires: int,
+    signals: Sequence[Signal | NlpSignal] | Signals | None = None,
+    when: Callable[[BaseHookEvent], bool] | None = None,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    events: Event | None = None,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    async_: bool = False,
+    max_context: int = 2000,
+    specialty: TSpecialty = "review",
+    model: TModel = "small",
+    agent: bool = False,
+    transcript: bool = False,
+) -> None:
+    sig = resolve_signals(signals)
+
+    def handler(evt: BaseHookEvent) -> HookResult | None:
+        if not (
+            result := llm_evaluate(
+                evt,
+                prompt,
+                response_model,
+                signals=signals,
+                when=when,
+                max_context=max_context,
+                specialty=specialty,
+                model=model,
+                agent=agent,
+                transcript=transcript,
+            )
+        ):
+            return None
+        if not verdict(result):
+            return None
+        consume_signals(evt, sig)
+        record_fire(evt)
+        return HookResult(
+            action=action,
+            message=message(result) if callable(message) else message,
+        )
+
+    handler.__name__ = handler.__qualname__ = hook_name(label, None, prompt)
+
+    on(
+        events or default_events,
+        only_if=only_if,
+        skip_if=skip_if,
+        max_fires=max_fires if max_fires is not None else default_max_fires,
+        tests=tests,
+        async_=async_,
+    )(handler)
+
+
+def llm_gate(
+    prompt: str,
+    *,
+    message: str | Callable[[GateVerdict], str],
+    response_model: type[GateVerdict] = GateVerdict,
+    verdict: Callable[[GateVerdict], bool] = lambda r: r.block,
+    signals: Sequence[Signal | NlpSignal] | Signals | None = None,
+    when: Callable[[BaseHookEvent], bool] | None = None,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    events: Event | None = None,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    max_context: int = 2000,
+    specialty: TSpecialty = "review",
+    model: TModel = "small",
+    agent: bool = True,
+    transcript: bool = True,
+) -> None:
+    """Register an LLM-powered blocking gate.
+
+    Defaults are tuned for the common case: ``agent=True`` and ``transcript=True``
+    so the gate has tool access and full transcript context. Pass
+    ``agent=False, transcript=False`` for cheap, stateless yes/no checks.
+
+    Example:
+        >>> llm_gate("Is the agent making excuses?",
+        ...          message=lambda r: f"Excuse detected: {r.reasoning}",
+        ...          signals=Signals([Signal(r"external.*service", weight=2)], threshold=2))
+    """
+    llm_primitive(
+        prompt,
+        action=Action.block,
+        label="llm_gate",
+        message=message,
+        response_model=response_model,
+        verdict=verdict,
+        default_events=Event.Stop | Event.SubagentStop,
+        default_max_fires=1,
+        signals=signals,
+        when=when,
+        only_if=only_if,
+        skip_if=skip_if,
+        events=events,
+        max_fires=max_fires,
+        tests=tests,
+        max_context=max_context,
+        specialty=specialty,
+        model=model,
+        agent=agent,
+        transcript=transcript,
+    )
+
+
+def llm_nudge(
+    prompt: str,
+    *,
+    message: str | Callable[[NudgeVerdict], str],
+    response_model: type[NudgeVerdict] = NudgeVerdict,
+    verdict: Callable[[NudgeVerdict], bool] = lambda r: r.fire,
+    signals: Sequence[Signal | NlpSignal] | Signals | None = None,
+    when: Callable[[BaseHookEvent], bool] | None = None,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    events: Event | None = None,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    async_: bool = False,
+    max_context: int = 2000,
+    specialty: TSpecialty = "review",
+    model: TModel = "small",
+    agent: bool = True,
+    transcript: bool = True,
+) -> None:
+    """Register an LLM-powered advisory nudge.
+
+    Defaults are tuned for the common case: ``agent=True`` and ``transcript=True``
+    so the nudge has tool access and full transcript context. Pass
+    ``agent=False, transcript=False`` for cheap, stateless yes/no checks.
+
+    Example:
+        >>> llm_nudge("Is the agent speculating instead of observing?",
+        ...           message="Observe, don't infer -- check traces first",
+        ...           signals=Signals([Signal(r"should contain", weight=2)], threshold=3))
+    """
+    llm_primitive(
+        prompt,
+        action=Action.warn,
+        label="llm_nudge",
+        message=message,
+        response_model=response_model,
+        verdict=verdict,
+        default_events=Event.PostToolUse,
+        default_max_fires=3,
+        signals=signals,
+        when=when,
+        only_if=only_if,
+        skip_if=skip_if,
+        events=events,
+        max_fires=max_fires,
+        tests=tests,
+        async_=async_,
+        max_context=max_context,
+        specialty=specialty,
+        model=model,
+        agent=agent,
+        transcript=transcript,
+    )
+
+
+def record_prompt_check_failure(
+    evt: BaseHookEvent,
+    prefix: str,
+    prompt: str,
+    exc: BaseException,
+) -> None:
+    timestamp = datetime.now(UTC).isoformat().replace(":", "-")
+    match exc:
+        case subprocess.CalledProcessError(cmd=cmd, returncode=rc, output=out, stderr=err):
+            argv = list(cmd) if isinstance(cmd, list | tuple) else str(cmd)
+            exit_code, stdout, stderr = rc, out or "", err or ""
+        case _:
+            argv, exit_code, stdout, stderr = None, None, "", ""
+
+    failure_path = FAILURE_ROOT / (session_id_for(evt) or "unknown") / f"{timestamp}.json"
+    failure_path.parent.mkdir(parents=True, exist_ok=True)
+    failure_path.write_text(
+        json.dumps(
+            {
+                "timestamp": timestamp,
+                "prefix": prefix,
+                "argv": argv,
+                "exit_code": exit_code,
+                "stdout": stdout,
+                "stderr": stderr,
+                "prompt": prompt,
+                "exception_type": type(exc).__name__,
+                "exception_str": str(exc),
+            },
+            indent=2,
+        )
+    )
+
+    logger.opt(exception=exc).warning(
+        f"prompt_check failed for {prefix}\n"
+        f"  argv: {argv}\n"
+        f"  exit_code: {exit_code}\n"
+        f"  stderr: {stderr}\n"
+        f"  stdout (tail 4KB): {stdout[-4096:]}\n"
+        f"  prompt (tail 1KB): {prompt[-1024:]}\n"
+        f"  failure_record: {failure_path}",
+    )
+
+
+def prompt_check(
+    evt: BaseHookEvent,
+    template: str | PromptMessage,
+    fmt: dict[str, Any] | None = None,
+    *,
+    prefix: str,
+    suffix: str = "",
+    timeout: int = 45,
+    include_reasoning: bool = True,
+    response_model: type[PromptCheckVerdict] = PromptCheckVerdict,
+) -> HookResult | None:
+    """Run an LLM check with a formatted prompt and return block/warn/None."""
+    reasoning = ""
+    if include_reasoning:
+        reasoning = evt.ctx.t.recent(50).assistant_text() if hasattr(evt.ctx.t, "recent") else ""
+
+    base = template if isinstance(template, PromptMessage) else Prompt().system(template.format(**(fmt or {})))
+    built = base.context("agent_reasoning", reasoning or None)
+    prompt_str = str(built)
+
+    try:
+        verdict = evt.ctx.call_llm(
+            built,
+            timeout=timeout,
+            response_model=response_model,
+        )
+    except Exception as exc:
+        record_prompt_check_failure(evt, prefix, prompt_str, exc)
+        return None
+
+    if not verdict:
+        return None
+
+    assert isinstance(verdict, response_model)
+    match verdict.action:
+        case "block":
+            return HookResult(action=Action.block, message=f"{prefix}: {verdict.reason}{suffix}")
+        case "warning":
+            return HookResult(action=Action.warn, message=f"{prefix}: {verdict.reason}{suffix}")
+        case _:
+            return None

captain_hook/primitives/nudge.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from captain_hook.app import on
+from captain_hook.signals import cite_message, resolve_signals, transcript_texts
+from captain_hook.state import EchoTracker, PrimitiveState, fired_this_turn, hook_name, record_fire
+from captain_hook.types import (
+    Action,
+    Event,
+    HookResult,
+    InlineTests,
+    Signal,
+    Signals,
+    TCondition,
+)
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+    from captain_hook.signals.nlp import NlpSignal
+
+
+def nudge(
+    message: str,
+    *,
+    when: Callable[[BaseHookEvent], bool] | None = None,
+    signals: Sequence[Signal | NlpSignal] | Signals | None = None,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    block: bool = False,
+    events: Event | None = None,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    async_: bool = False,
+) -> None:
+    """Register a nudge that warns (or blocks) when conditions or signals match.
+
+    Example:
+        >>> nudge("Remember to run tests", only_if=[TouchedFile("**/*.py")])
+
+        With signal scoring:
+            >>> nudge("Stop retrying",
+            ...       signals=Signals([Signal(r"retry", weight=2)], threshold=2, window=5))
+    """
+    sig = resolve_signals(signals)
+
+    def handler(evt: BaseHookEvent) -> HookResult | None:
+        if block and fired_this_turn(evt):
+            return None
+
+        if sig:
+            ps = evt.ctx.s[PrimitiveState].get(PrimitiveState())
+            tracker = EchoTracker()
+            candidates = [t for t in transcript_texts(evt, sig.window) if not tracker.saw(t, evt=evt)]
+            if not (triggering := ps.match_signals(sig, candidates)):
+                evt.ctx.s[PrimitiveState].set(ps)
+                return None
+            ps.last_fired_at = len(evt.ctx.t)
+            evt.ctx.s[PrimitiveState].set(ps)
+            tracker.record(message, triggering=triggering, evt=evt)
+            cited = cite_message(sig, triggering, message)
+        elif when is not None and not when(evt):
+            return None
+        else:
+            cited = message
+
+        if block:
+            record_fire(evt)
+            return HookResult.of(Action.block, cited)
+        return HookResult.of(Action.warn, cited)
+
+    handler.__name__ = handler.__qualname__ = hook_name(
+        "gate" if block else "nudge",
+        None,
+        message,
+    )
+
+    on(
+        events or ((Event.Stop | Event.SubagentStop) if block else Event.PostToolUse if sig else Event.PreToolUse),
+        only_if=only_if,
+        skip_if=skip_if,
+        max_fires=max_fires if max_fires is not None else (3 if sig else 1),
+        tests=tests,
+        async_=async_,
+    )(handler)
+
+
+def gate(message: str, **kwargs: Any) -> None:
+    """Register a blocking gate — shorthand for ``nudge(message, block=True, ...)``.
+
+    Example:
+        >>> gate("Run tests before committing", when=lambda evt: not has_tests(evt))
+    """
+    nudge(message, block=True, **kwargs)

captain_hook/prompt.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import inspect
+import textwrap
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def dedent_text(text: str) -> str:
+    return textwrap.dedent(text).strip()
+
+
+_FRAMEWORK_DIR = Path(__file__).resolve().parent
+
+
+def _caller_dir() -> Path:
+    frame = inspect.currentframe()
+    while frame and Path(frame.f_code.co_filename).resolve().is_relative_to(_FRAMEWORK_DIR):
+        frame = frame.f_back
+    return Path(frame.f_code.co_filename).resolve().parent if frame else Path.cwd()
+
+
+@dataclass(frozen=True, kw_only=True)
+class PromptMessage:
+    """Fluent builder for structured LLM prompts with system text, XML context sections, and a question.
+
+    Chain ``.system()``, ``.context(tag, content)``, and ``.ask()`` to build prompts.
+    ``str()`` renders the full prompt with XML-wrapped context blocks.
+    """
+
+    system_text: str = ""
+    contexts: tuple[tuple[str, str], ...] = ()
+    ask_text: str = ""
+
+    def system(self, text: str) -> PromptMessage:
+        return PromptMessage(
+            system_text=dedent_text(text),
+            contexts=self.contexts,
+            ask_text=self.ask_text,
+        )
+
+    def context(self, tag: str, content: str | None) -> PromptMessage:
+        if content is None or not (normalized := dedent_text(content)):
+            return self
+        return PromptMessage(
+            system_text=self.system_text,
+            contexts=(*self.contexts, (tag, normalized)),
+            ask_text=self.ask_text,
+        )
+
+    def ask(self, text: str) -> PromptMessage:
+        return PromptMessage(
+            system_text=self.system_text,
+            contexts=self.contexts,
+            ask_text=dedent_text(text),
+        )
+
+    @classmethod
+    def from_template(cls, text: str, **vars: object) -> PromptMessage:
+        try:
+            return cls(system_text=textwrap.dedent(text).strip().format_map(vars))
+        except KeyError as exc:
+            raise KeyError(f"template variable {exc.args[0]!r} not supplied") from exc
+
+    @classmethod
+    def load(cls, name: str, *, base: str | Path | None = None, **vars: object) -> PromptMessage:
+        """Load a prompt from a ``.md`` file and render it via :meth:`from_template`.
+
+        Resolution searches directories in order, returning the first existing file:
+        the ``base`` directory if given (otherwise a ``prompts/`` directory beside the
+        calling module), then the framework's bundled ``captain_hook/prompts/``. The
+        file path is ``<dir>/<name>.md``; ``name`` may contain ``/`` to nest.
+
+        Args:
+            name: Prompt name without the ``.md`` suffix; may include ``/`` for nesting.
+            base: Optional directory to search instead of the caller-relative ``prompts/``.
+            **vars: Template variables substituted into the file via ``str.format_map``.
+
+        Returns:
+            A :class:`PromptMessage` whose system text is the rendered file contents.
+
+        Raises:
+            FileNotFoundError: If no matching file exists in any searched directory.
+            KeyError: If the file references a placeholder not supplied in ``**vars``.
+        """
+        dirs = [Path(base) if base else _caller_dir() / "prompts", _FRAMEWORK_DIR / "prompts"]
+        for path in (d / f"{name}.md" for d in dirs):
+            if path.is_file():
+                return cls.from_template(path.read_text(), **vars)
+        raise FileNotFoundError(f"prompt {name!r} not found; searched: {', '.join(str(d) for d in dirs)}")
+
+    def __str__(self) -> str:
+        parts: list[str] = []
+        if self.system_text:
+            parts.append(self.system_text)
+        for tag, content in self.contexts:
+            parts.append(f"<{tag}>\n{content}\n</{tag}>")
+        if self.ask_text:
+            parts.append(self.ask_text)
+        return "\n\n".join(parts)
+
+
+Prompt = PromptMessage

captain_hook/py.typed

@@ -0,0 +1 @@
+