activegraph 1.0.0rc2__py3-none-any.whl

activegraph/llm/errors.py

@@ -0,0 +1,257 @@
+"""LLM-side errors. v1.0 PR-D — migrated to ExecutionError.
+
+Two surface types in the LLM layer:
+
+- :class:`MissingProviderError` — raised at registration time when an
+  ``@llm_behavior`` is invoked but no provider is wired. Stays a
+  ``RuntimeError`` subclass through PR-D; PR-E (RegistrationError)
+  re-parents it.
+
+- :class:`LLMBehaviorError` — structured failure from inside an
+  ``@llm_behavior`` wrapper. Carries a ``reason`` code from CONTRACT
+  v0.6 #11 plus a free-form ``message``. The runtime's ``_invoke``
+  catch reads ``reason`` and ``payload_extras`` off this exception and
+  includes them in the emitted ``behavior.failed`` event.
+
+PR-D re-parents ``LLMBehaviorError`` under
+:class:`activegraph.errors.ExecutionError` so it joins the v1.0
+hierarchy and produces a structured-format message when rendered to a
+user. The ``(reason, message, payload_extras)`` constructor signature
+is preserved so the ~8 internal raise sites in providers do not
+change. The structured fields are auto-derived from ``reason`` via a
+per-reason prose table — same pattern as PR-B's
+``_KEYWORD_WORKAROUNDS``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from activegraph.errors import ExecutionError, RegistrationError
+
+
+# Per-reason prose for LLMBehaviorError. The voice principle from
+# CONTRACT v1.0 #3: explain the invariant being protected, not the
+# mechanism of the check. Each entry produces what_failed / why /
+# how_to_fix triples that the constructor uses to build the
+# structured-format body.
+#
+# `message` from the call site is interpolated into what_failed; `why`
+# and `how_to_fix` are reason-specific and stable across instances.
+
+
+def _llm_prose_parse_error(message: str) -> tuple[str, str, str]:
+    return (
+        f"The LLM provider returned a response that the framework could not "
+        f"parse as JSON:\n  {message}",
+        "LLM behaviors with a structured `output_schema` expect the model to "
+        "return JSON that matches the schema; the framework parses the "
+        "response and constructs typed objects from it. A response that "
+        "isn't valid JSON breaks the contract that downstream behaviors "
+        "depend on — they receive typed objects, not raw strings — so the "
+        "framework fails the call rather than guess at structure.",
+        "If the provider is real, the model's response is non-deterministic; "
+        "try raising the prompt's emphasis on JSON-only output, or lowering "
+        "temperature. If the provider is a fixture (RecordedLLMProvider), "
+        "the recorded response is malformed — re-record from a clean run.\n"
+        "\n"
+        "The full response is in the `behavior.failed` event's `payload_extras`; "
+        "inspect it with:\n"
+        "    activegraph inspect <store> --event <behavior.failed-id>",
+    )
+
+
+def _llm_prose_schema_violation(message: str) -> tuple[str, str, str]:
+    return (
+        f"The LLM provider returned valid JSON, but the JSON did not match "
+        f"the behavior's declared `output_schema`:\n  {message}",
+        "Pydantic validates every LLM response against the schema declared on "
+        "`@llm_behavior(output_schema=...)`. Schema-violating responses are "
+        "refused at the boundary so downstream behaviors receive only objects "
+        "that obey the schema — replay determinism depends on this.",
+        "Check whether the schema's required fields match what the model "
+        "actually produces. Common causes: a required field is missing in "
+        "the response, an enum value is out-of-range, or a list field "
+        "contains items of the wrong type. Add the missing fields to the "
+        "prompt's example output, or relax the schema (e.g. `Optional[X]`) "
+        "if the field genuinely can be absent.",
+    )
+
+
+def _llm_prose_fixture_missing(message: str) -> tuple[str, str, str]:
+    return (
+        f"The RecordedLLMProvider has no fixture for this prompt:\n  {message}",
+        "RecordedLLMProvider replays a directory of recorded LLM responses keyed "
+        "by prompt content hash. A missing fixture means the live prompt's hash "
+        "doesn't match any recorded response — either the prompt changed since "
+        "the fixtures were recorded (a behavior edit, a template change, a "
+        "tool input difference), or this is a new prompt that was never "
+        "recorded.",
+        "Re-record the fixture from a live run with the current prompt:\n"
+        "    1. Switch to AnthropicProvider (set ANTHROPIC_API_KEY)\n"
+        "    2. Run the goal once to produce live LLM responses\n"
+        "    3. The provider records each response to the fixture directory\n"
+        "    4. Subsequent runs against RecordedLLMProvider replay them\n"
+        "\n"
+        "Or diff the prompt against the recorded version to find the drift.",
+    )
+
+
+def _llm_prose_rate_limited(message: str) -> tuple[str, str, str]:
+    return (
+        f"The LLM provider rejected the request as rate-limited:\n  {message}",
+        "Providers cap requests per minute / tokens per minute. When the cap "
+        "is hit, retries within the rate-limit window will fail again — the "
+        "framework refuses to silently retry-loop without an explicit "
+        "operator decision, because a long retry loop can quietly exhaust "
+        "the behavior's budget.",
+        "Wait until the rate-limit window resets (provider-specific — usually "
+        "60 seconds), then re-run. For long-running goals, set a higher "
+        "`max_seconds` budget so the runtime tolerates intermittent "
+        "rate-limits. If this happens during fork/replay, the cache hit "
+        "should normally prevent the live call — check whether the prompt "
+        "hash matches the recorded one.",
+    )
+
+
+def _llm_prose_network_error(message: str) -> tuple[str, str, str]:
+    return (
+        f"The LLM provider call failed with a network error:\n  {message}",
+        "The framework treats network failures as transient but not "
+        "automatically retryable: a silent retry could mask a real outage "
+        "or burn budget on a flaky network. The error escapes to the caller "
+        "so the operator decides what to do.",
+        "If the network is unreliable, re-run the goal — fork-and-replay "
+        "from the last successful event:\n"
+        "    activegraph fork <run> --at-event <last-good> --record\n"
+        "For systematic outages, the provider's status page is the canonical "
+        "source. Switching to RecordedLLMProvider with previously-recorded "
+        "fixtures lets the run complete offline.",
+    )
+
+
+_LLM_REASON_PROSE: dict[str, Any] = {
+    "llm.parse_error": _llm_prose_parse_error,
+    "llm.schema_violation": _llm_prose_schema_violation,
+    "llm.fixture_missing": _llm_prose_fixture_missing,
+    "llm.rate_limited": _llm_prose_rate_limited,
+    "llm.network_error": _llm_prose_network_error,
+}
+
+
+def _llm_fallback_prose(reason: str, message: str) -> tuple[str, str, str]:
+    """Default prose for a reason code the table doesn't enumerate. The
+    voice still names the invariant ("the framework surfaces structured
+    failures from @llm_behavior wrappers"); recovery prose is generic
+    and points the operator at the trace.
+    """
+    return (
+        f"An @llm_behavior wrapper failed with reason {reason!r}:\n  {message}",
+        f"The runtime catches structured failures from @llm_behavior bodies "
+        f"and merges them into the emitted `behavior.failed` event, where "
+        f"downstream code can read `reason={reason!r}` and decide how to "
+        f"proceed. The exception you're seeing is the underlying carrier.",
+        f"Inspect the `behavior.failed` event in the trace:\n"
+        f"    activegraph inspect <store> --tail 50\n"
+        f"\n"
+        f"The full message is preserved verbatim above; check the LLM "
+        f"provider's documentation for reason {reason!r}.",
+    )
+
+
+class MissingProviderError(RegistrationError, RuntimeError):
+    """Raised when an @llm_behavior is invoked but no LLM provider is
+    wired on the Runtime.
+
+    Fires at registration / startup, not at every invocation — the
+    runtime validates the configuration once. Multi-inherits
+    :class:`RuntimeError` for back-compat with user code catching the
+    builtin around runtime construction.
+    """
+
+    _doc_slug = "missing-provider-error"
+
+    def __init__(self, behavior_name: Optional[str] = None) -> None:
+        self.behavior_name = behavior_name
+        what = (
+            f"An LLM-backed behavior ({behavior_name!r}) was registered, "
+            f"but Runtime(...) was constructed without an `llm_provider=` "
+            f"argument."
+            if behavior_name
+            else (
+                "An @llm_behavior was registered, but Runtime(...) was "
+                "constructed without an `llm_provider=` argument."
+            )
+        )
+        ctx: dict[str, Any] = {}
+        if behavior_name:
+            ctx["behavior_name"] = behavior_name
+        RegistrationError.__init__(
+            self,
+            "no LLM provider configured for @llm_behavior",
+            what_failed=what,
+            why=(
+                "@llm_behavior dispatches LLM calls through the provider "
+                "attached to the runtime at construction. Failing loud at "
+                "registration rather than at first invocation is the v0.6 "
+                "contract — silently no-op'ing the behavior would corrupt "
+                "the audit trail (behaviors fire and produce events; a "
+                "missing provider would produce events that claim to "
+                "depend on an LLM call that never happened)."
+            ),
+            how_to_fix=(
+                "Pass `llm_provider=` to the Runtime constructor:\n"
+                "    from activegraph.llm.anthropic import AnthropicProvider\n"
+                "    rt = Runtime(graph, llm_provider=AnthropicProvider())\n"
+                "\n"
+                "For offline replay or tests, use a recorded or scripted "
+                "provider:\n"
+                "    from activegraph.llm.recorded import RecordedLLMProvider\n"
+                "    rt = Runtime(graph, llm_provider=RecordedLLMProvider(...))"
+            ),
+            context=ctx,
+        )
+
+
+class LLMBehaviorError(ExecutionError, Exception):
+    """Structured failure from inside an @llm_behavior wrapper.
+
+    The runtime's ``_invoke`` catch reads ``reason`` and ``payload_extras``
+    off this exception and includes them in the emitted
+    ``behavior.failed`` event. Other exception types fall through to
+    the existing CONTRACT v0.6 #13 path unchanged.
+
+    Constructor signature ``(reason, message, *, payload_extras=)`` is
+    preserved from v0.6 so the ~8 internal raise sites in providers do
+    not change. The structured-format fields are auto-derived from
+    ``reason`` via the per-reason prose table above.
+    """
+
+    _doc_slug = "llm-behavior-error"
+
+    def __init__(
+        self,
+        reason: str,
+        message: str,
+        *,
+        payload_extras: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self.reason = reason
+        self.payload_extras = dict(payload_extras or {})
+        prose_fn = _LLM_REASON_PROSE.get(reason)
+        if prose_fn is None:
+            what_failed, why, how_to_fix = _llm_fallback_prose(reason, message)
+        else:
+            what_failed, why, how_to_fix = prose_fn(message)
+        ExecutionError.__init__(
+            self,
+            f"{reason}: {message}",
+            what_failed=what_failed,
+            why=why,
+            how_to_fix=how_to_fix,
+            context={
+                "reason": reason,
+                "message": message,
+                "payload_extras": self.payload_extras,
+            },
+        )

activegraph/llm/prompt.py

@@ -0,0 +1,420 @@
+"""Prompt assembler + view serializer.
+
+CONTRACT v0.6 #6, #13, #20. This is the load-bearing module of v0.6:
+
+  * Developers don't write prompts in user code. The runtime assembles
+    every prompt from four locked sources, in this order:
+
+        1. system     — frame goal, frame constraints, behavior role
+                        description, output-schema reminder
+        2. view       — serialized scoped graph view (objects + relations
+                        + recent events)
+        3. event      — the triggering event, serialized as JSON
+        4. instruction — a single sentence derived from `creates=` and
+                        `output_schema=`
+
+  * The format of (2), the view serialization, is part of the public
+    contract per decision #13. It is snapshot-tested. Changing it is a
+    breaking change to the framework.
+
+  * `AssembledPrompt.hash()` returns a stable SHA-256 over the
+    canonical JSON of {model, system, messages, output_schema_name,
+    temperature, max_tokens, top_p, deterministic}. This is the cache
+    key used by the replay layer. Hash stability matters; tests
+    snapshot it.
+
+  * `behavior.build_prompt(event, graph)` is public for debugging
+    (decision #20). A developer should be able to inspect the exact
+    bytes that would have gone to the model, without making a call.
+
+`prompt_template=` (str.format-style with {system}, {view}, {event},
+{instruction}) is the only escape hatch — and it still receives the
+same four runtime-assembled inputs. There is no raw string-concat
+path in user code.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from activegraph.core.event import Event
+from activegraph.core.view import View
+from activegraph.frame import Frame
+from activegraph.llm.types import LLMMessage
+
+
+# ---------- AssembledPrompt -------------------------------------------------
+
+
+@dataclass
+class AssembledPrompt:
+    """A fully-assembled prompt + provider-call parameters.
+
+    Returned by `assemble_prompt(...)` and by
+    `LLMBehavior.build_prompt(event, graph)`. The runtime hashes this
+    to look up a cached response before deciding to call the provider.
+    """
+
+    system: str
+    messages: list[LLMMessage]
+    model: str
+    max_tokens: int
+    temperature: float
+    top_p: float
+    output_schema_name: Optional[str]
+    output_schema_json: Optional[dict[str, Any]]
+    deterministic: bool
+
+    # Source-by-source breakdown — useful for debugging and for
+    # snapshot tests that target a single section.
+    sections: dict[str, str] = field(default_factory=dict)
+
+    def to_hashable(self) -> dict[str, Any]:
+        """Canonical content used for hashing. Recorded-at timestamps,
+        latencies, and other run-specific data are NOT included."""
+
+        return {
+            "model": self.model,
+            "system": self.system,
+            "messages": [m.to_dict() for m in self.messages],
+            "output_schema_name": self.output_schema_name,
+            "output_schema_json": self.output_schema_json,
+            "max_tokens": int(self.max_tokens),
+            "temperature": float(self.temperature),
+            "top_p": float(self.top_p),
+            "deterministic": bool(self.deterministic),
+        }
+
+    def canonical_json(self) -> str:
+        return json.dumps(
+            self.to_hashable(), sort_keys=True, separators=(",", ":")
+        )
+
+    def hash(self) -> str:
+        return hashlib.sha256(self.canonical_json().encode("utf-8")).hexdigest()
+
+
+# ---------- view serialization (CONTRACT v0.6 #13 — format is locked) -------
+
+
+def serialize_view(
+    view: View,
+    *,
+    around: Optional[str] = None,
+    depth: Optional[int] = None,
+) -> str:
+    """Render a scoped view as the prompt-ready Markdown block.
+
+    Format is locked — snapshot-tested in `tests/test_llm_prompt.py`.
+    Changing this is a breaking change to the v0.6 contract.
+    """
+
+    header_bits: list[str] = []
+    if depth is not None:
+        header_bits.append(f"depth={depth}")
+    if around:
+        header_bits.append(f"around={around}")
+    header_suffix = f" ({', '.join(header_bits)})" if header_bits else ""
+
+    lines: list[str] = [f"## Graph context{header_suffix}", ""]
+
+    objects = view.objects()
+    lines.append("### Objects")
+    if not objects:
+        lines.append("- (none)")
+    else:
+        for o in objects:
+            lines.append(f"- {o.id} ({o.type}): {_canonical(o.data)}")
+    lines.append("")
+
+    relations = view.relations()
+    lines.append("### Relations")
+    if not relations:
+        lines.append("- (none)")
+    else:
+        for r in relations:
+            lines.append(f"- {r.source} --{r.type}--> {r.target}")
+    lines.append("")
+
+    events = view.events()
+    lines.append("### Recent events")
+    if not events:
+        lines.append("- (none)")
+    else:
+        for e in events:
+            summary = _event_summary(e)
+            lines.append(f"- {e.id} {e.type}{summary}")
+
+    return "\n".join(lines)
+
+
+def _event_summary(e: Event) -> str:
+    """One-line tail for an event in the view block.
+
+    Stays short on purpose — the prompt should expose enough for the
+    model to reason about recent activity without becoming a transcript.
+    """
+
+    p = e.payload or {}
+    if e.type == "object.created":
+        oid = (p.get("object") or {}).get("id", "?")
+        return f" {oid}"
+    if e.type == "relation.created":
+        r = p.get("relation") or {}
+        return f' {r.get("source", "?")} --{r.get("type", "?")}--> {r.get("target", "?")}'
+    if e.type == "patch.applied":
+        return f' {p.get("target", "?")}'
+    if e.type == "goal.created":
+        return f' "{p.get("goal", "")}"'
+    return ""
+
+
+def _canonical(value: Any) -> str:
+    """Stable JSON for embedding inside the view block."""
+    return json.dumps(value, sort_keys=True, default=str)
+
+
+# ---------- system prompt ---------------------------------------------------
+
+
+def build_system_prompt(
+    *,
+    behavior_name: str,
+    description: str,
+    frame: Optional[Frame],
+    output_schema_name: Optional[str],
+    output_schema_json: Optional[dict[str, Any]],
+) -> str:
+    """The system prompt is assembled — never hand-written by the user.
+
+    Source order: frame.goal → frame.constraints → behavior.description
+    → output schema reminder. If a section is absent it is omitted; the
+    section headers themselves are stable so snapshot tests are tight.
+    """
+
+    blocks: list[str] = []
+
+    blocks.append(
+        f'You are an active-graph behavior named "{behavior_name}".'
+    )
+
+    if frame is not None and frame.goal:
+        blocks.append(f"Mission: {frame.goal}")
+
+    if frame is not None and frame.constraints:
+        bullets = "\n".join(f"- {c}" for c in frame.constraints)
+        blocks.append(f"Constraints:\n{bullets}")
+
+    if description:
+        blocks.append(f"Role: {description}")
+
+    if output_schema_name and output_schema_json is not None:
+        schema_block = json.dumps(output_schema_json, indent=2, sort_keys=True)
+        blocks.append(
+            f"Respond with JSON that matches the `{output_schema_name}` "
+            f"schema:\n{schema_block}"
+        )
+
+    return "\n\n".join(blocks)
+
+
+# ---------- user message ----------------------------------------------------
+
+
+def build_user_message(
+    *,
+    view_block: str,
+    event: Event,
+    instruction: str,
+) -> str:
+    event_block = _serialize_event(event)
+    return (
+        f"{view_block}\n\n"
+        f"## Triggering event\n"
+        f"{event_block}\n\n"
+        f"## Task\n"
+        f"{instruction}"
+    )
+
+
+def _serialize_event(event: Event) -> str:
+    # Strip volatile fields (provenance, run-specific timestamps, run_id)
+    # so the prompt is content-stable across runs and forks. Without
+    # this, the cache would miss on every fork because the embedded
+    # object's provenance carries the parent's run_id.
+    clean_payload = _strip_volatile(event.payload)
+    payload_json = json.dumps(clean_payload, sort_keys=True, indent=2, default=str)
+    return (
+        f"- id: {event.id}\n"
+        f"- type: {event.type}\n"
+        f"- actor: {event.actor or '?'}\n"
+        f"- payload:\n```\n{payload_json}\n```"
+    )
+
+
+_VOLATILE_KEYS = frozenset({"provenance", "timestamp", "run_id"})
+
+
+def _strip_volatile(value: Any) -> Any:
+    """Recursively drop keys whose values vary across runs/forks.
+
+    Provenance carries `run_id` and `timestamp`; both leak into the
+    embedded object payload of `object.created` events and would
+    otherwise destabilize the prompt hash. Stable cache lookup
+    requires content-equivalence over the parts of the prompt the
+    model actually reasons about.
+    """
+
+    if isinstance(value, dict):
+        return {
+            k: _strip_volatile(v)
+            for k, v in value.items()
+            if k not in _VOLATILE_KEYS
+        }
+    if isinstance(value, list):
+        return [_strip_volatile(v) for v in value]
+    return value
+
+
+# ---------- task instruction ------------------------------------------------
+
+
+def build_instruction(
+    *,
+    creates: list[str],
+    output_schema_name: Optional[str],
+) -> str:
+    """One-sentence summary of what the LLM is supposed to produce.
+
+    Auto-derived from the decorator metadata so it cannot drift from
+    the runtime's expectations. If the developer is creating multiple
+    object types, list them; if there is a schema, name it.
+    """
+
+    if output_schema_name and creates:
+        creates_str = ", ".join(sorted(set(creates)))
+        return (
+            f"Return JSON matching the `{output_schema_name}` schema. "
+            f"Your output will be used to create objects of type: {creates_str}."
+        )
+    if output_schema_name:
+        return f"Return JSON matching the `{output_schema_name}` schema."
+    if creates:
+        creates_str = ", ".join(sorted(set(creates)))
+        return (
+            f"Describe what objects of type {creates_str} should be created "
+            f"in response to this event."
+        )
+    return "Describe what should happen in response to this event."
+
+
+# ---------- schema rendering ------------------------------------------------
+
+
+def schema_to_json(schema: Optional[type]) -> Optional[dict[str, Any]]:
+    """Serialize a Pydantic BaseModel class to a JSON schema dict.
+
+    Returns None if `schema` is None. Falls back to a name-only shell
+    if `schema` does not look like a Pydantic v2 model — that lets
+    third-party schema systems plug in without us hard-depending on
+    Pydantic at import time.
+    """
+
+    if schema is None:
+        return None
+    fn = getattr(schema, "model_json_schema", None)
+    if callable(fn):
+        return fn()
+    return {"type": "object", "title": getattr(schema, "__name__", "Unknown")}
+
+
+# ---------- top-level assembly ---------------------------------------------
+
+
+def assemble_prompt(
+    *,
+    behavior_name: str,
+    description: str,
+    model: str,
+    output_schema: Optional[type],
+    creates: list[str],
+    view: View,
+    event: Event,
+    frame: Optional[Frame],
+    around: Optional[str],
+    depth: Optional[int],
+    max_tokens: int,
+    temperature: float,
+    top_p: float,
+    deterministic: bool,
+    prompt_template: Optional[str] = None,
+) -> AssembledPrompt:
+    """Assemble a prompt for one behavior invocation.
+
+    Returns an `AssembledPrompt` containing the system prompt, the user
+    messages, and every provider-call parameter that contributes to the
+    prompt-hash cache key. Pure function over its arguments — no I/O,
+    no provider calls.
+    """
+
+    schema_json = schema_to_json(output_schema)
+    schema_name = (
+        getattr(output_schema, "__name__", None) if output_schema else None
+    )
+
+    system = build_system_prompt(
+        behavior_name=behavior_name,
+        description=description,
+        frame=frame,
+        output_schema_name=schema_name,
+        output_schema_json=schema_json,
+    )
+
+    view_block = serialize_view(view, around=around, depth=depth)
+    instruction = build_instruction(
+        creates=list(creates), output_schema_name=schema_name
+    )
+
+    if prompt_template is not None:
+        event_block = _serialize_event(event)
+        try:
+            user_text = prompt_template.format(
+                system=system,
+                view=view_block,
+                event=event_block,
+                instruction=instruction,
+            )
+        except KeyError as e:
+            raise ValueError(
+                f"prompt_template references unknown placeholder {e!r}. "
+                f"Allowed: {{system}}, {{view}}, {{event}}, {{instruction}}"
+            ) from e
+    else:
+        user_text = build_user_message(
+            view_block=view_block, event=event, instruction=instruction
+        )
+
+    eff_temperature = 0.0 if deterministic else float(temperature)
+    eff_top_p = 1.0 if deterministic else float(top_p)
+
+    return AssembledPrompt(
+        system=system,
+        messages=[LLMMessage(role="user", content=user_text)],
+        model=model,
+        max_tokens=int(max_tokens),
+        temperature=eff_temperature,
+        top_p=eff_top_p,
+        output_schema_name=schema_name,
+        output_schema_json=schema_json,
+        deterministic=bool(deterministic),
+        sections={
+            "system": system,
+            "view": view_block,
+            "event": _serialize_event(event),
+            "instruction": instruction,
+            "user": user_text,
+        },
+    )