reactifact 0.6.0__py3-none-any.whl

reactifact/recipes/memory.py

@@ -0,0 +1,166 @@
+"""recipes — bounded conversation memory: periodic summarization + pruning.
+
+Long-running chat memory is just state (§27, §37): message artifacts
+accumulate, a `WindowSummarizer` condenses the recent window into a summary
+artifact every N messages, and a `WindowPruner` keeps the window bounded by
+deleting the oldest messages. Both are plain `Produce`s — drop them into an
+`Agent.produces` list next to whatever else reacts to the message type.
+
+Domain owns *how* to summarize (the `summarize` callback) and *what* the
+summary artifact looks like (`build`); this recipe only owns the window size,
+cadence, and idempotency bookkeeping — the same split as `materialize_doc`
+owning provenance while the caller owns the document factory.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from ..artifacts import Artifact
+from ..context import Context
+from ..events import Event
+from ..produce import Produce
+from ..structured import OnStructuredError, llm_reply
+
+MsgT = TypeVar("MsgT", bound=BaseModel)
+SummaryT = TypeVar("SummaryT", bound=BaseModel)
+
+
+def _default_render(messages: list[Artifact[Any]]) -> str:
+    lines = []
+    for a in messages:
+        role = getattr(a.data, "role", None)
+        text = getattr(a.data, "text", None)
+        lines.append(
+            f"{role}: {text}" if role is not None and text is not None else str(a.data)
+        )
+    return "\n".join(lines)
+
+
+def _default_fallback(history: str) -> str:
+    return f"(offline memory) {history[:140]}"
+
+
+class WindowSummarizer(Produce[SummaryT], Generic[MsgT, SummaryT]):
+    """Condenses the recent window of `message_type` artifacts into a summary
+    artifact every `every` messages (§27).
+
+    Idempotent by construction: the summary id is derived from the message
+    count, so re-running the same generation never produces a duplicate.
+    """
+
+    def __init__(
+        self,
+        message_type: type[MsgT],
+        artifact_type: type[SummaryT],
+        *,
+        summarize: Callable[[Context, str], Awaitable[str | None]],
+        build: Callable[[int, str], SummaryT],
+        window: int = 8,
+        every: int = 4,
+        render: Callable[[list[Artifact[MsgT]]], str] = _default_render,
+        fallback: Callable[[str], str] = _default_fallback,
+        order_key: Callable[[Artifact[MsgT]], Any] = lambda a: a.created_at,
+        id_of: Callable[[int], str] = lambda round_no: f"summary:{round_no}",
+    ):
+        super().__init__(artifact_type=artifact_type)
+        self.message_type = message_type
+        self.summarize = summarize
+        self.build = build
+        self.window = window
+        self.every = every
+        self.render = render
+        self.fallback = fallback
+        self.order_key = order_key
+        self.id_of = id_of
+
+    async def produce(
+        self,
+        context: Context,
+        inputs: list[Artifact[Any]],
+        event: Event | None = None,
+    ) -> None:
+        messages = context.list_artifacts(self.message_type)
+        count = len(messages)
+        if count == 0 or count % self.every != 0:
+            return None
+        round_no = count // self.every
+        summary_id = self.id_of(round_no)
+        if context.get(summary_id) is not None:
+            return None  # this round's summary already exists (§42)
+        recent = sorted(messages, key=self.order_key)[-self.window :]
+        history = self.render(recent)
+        text = await self.summarize(context, history)
+        if text is None:
+            text = self.fallback(history)
+        self.effects.create(self.build(round_no, text), id=summary_id)
+        return None
+
+
+class WindowPruner(Produce[MsgT], Generic[MsgT]):
+    """Deletes `message_type` artifacts older than `keep` (ordered by
+    `order_key`, default `created_at`). Standalone-useful — pair it with
+    `WindowSummarizer` for full sliding-window memory, or use it alone to
+    just bound how many messages a context keeps.
+    """
+
+    def __init__(
+        self,
+        message_type: type[MsgT],
+        *,
+        keep: int = 8,
+        order_key: Callable[[Artifact[MsgT]], Any] = lambda a: a.created_at,
+    ):
+        super().__init__(artifact_type=message_type)
+        self.message_type = message_type
+        self.keep = keep
+        self.order_key = order_key
+
+    async def produce(
+        self,
+        context: Context,
+        inputs: list[Artifact[Any]],
+        event: Event | None = None,
+    ) -> None:
+        messages = sorted(context.list_artifacts(self.message_type), key=self.order_key)
+        # `max(0, ...)`: a plain negative slice bound wraps from the end in
+        # Python (`messages[:-1]` means "all but the last"), which would prune
+        # the wrong messages while the window hasn't filled up yet.
+        old = messages[: max(0, len(messages) - self.keep)]
+        if not old:
+            return None
+        for message in old:
+            self.effects.delete(message.id)
+        return None
+
+
+def llm_summarizer(
+    system: str,
+    *,
+    attempts: int = 2,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    on_error: OnStructuredError | None = None,
+) -> Callable[[Context, str], Awaitable[str | None]]:
+    """Builds a `WindowSummarizer(summarize=...)` callback from a system
+    prompt, via `llm_reply` — the common case, no custom schema class needed.
+    """
+
+    async def _summarize(context: Context, history: str) -> str | None:
+        return await llm_reply(
+            context,
+            system=system,
+            user=history,
+            attempts=attempts,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            on_error=on_error,
+        )
+
+    return _summarize
+
+
+__all__ = ["WindowSummarizer", "WindowPruner", "llm_summarizer"]

reactifact/recipes/resolve.py

@@ -0,0 +1,51 @@
+"""recipes — lazy reference materialization (§6, §34).
+
+Effects-based: resolves a ref into a document and writes the create + the
+provenance link into the current produce's `effects` slot. Returns the produced
+document (or None on a failure), so the caller can react to the outcome.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pydantic import BaseModel
+
+from ..artifacts import Artifact
+from ..context import Context
+from ..sources import SourceRef
+from .search import _active_effects
+
+
+async def materialize_doc(
+    context: Context,
+    ref_artifact: Artifact[SourceRef],
+    doc_factory: Callable[[Context, Artifact[SourceRef], str], BaseModel],
+    *,
+    relation: str = "materialized_from",
+) -> BaseModel | None:
+    """Resolves a ref into a document (lazily, §6) with provenance (§34).
+
+    `doc_factory(context, ref_artifact, content)` builds the domain document;
+    the produced document is created with a stable id and linked
+    `relation → SourceRef` (default `materialized_from`, pass `resolved_from`
+    to match the demos) in the current effect slot. Returns None on a missing
+    source / resolve failure — the failure is a None, not a crash.
+    """
+    effects = _active_effects(context)
+    ref = ref_artifact.data
+    source = context.resources.get_source(ref.source_id)
+    if source is None:
+        return None
+    try:
+        content = await source.resolve(ref)
+    except Exception:
+        return None
+    doc = doc_factory(context, ref_artifact, content)
+    doc_id = f"resolved:{ref_artifact.id}"
+    handle = effects.create(doc, id=doc_id)
+    handle.link(relation, ref_artifact)
+    return doc
+
+
+__all__ = ["materialize_doc"]

reactifact/recipes/rollback.py

@@ -0,0 +1,87 @@
+"""recipes.rollback — the "change → rebuild" model (§22, §24).
+
+Long multi-stage flows sometimes have to *go back*: the user edits a fact, the
+pipeline must rebuild from the earliest affected stage and reset every
+downstream artifact. The three helpers here are the deterministic mechanism;
+the workflow (stages, field→stage mapping) is the domain's own, passed in:
+
+    field_stages = {"room": "collect", "area": "plan", "budget": "estimate"}
+    order = ("collect", "design_choice", "plan", "estimate")
+
+    changed = changed_fields(old_info, new_info)      # which fields moved
+    target = earliest_stage(changed, field_stages=..., order=order)
+    reset = downstream_fields(target, field_stages=..., order=order)  # what to clear
+
+Nothing is guessed: the rebuild target is a pure function of what changed (§24).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping, Sequence
+
+from pydantic import BaseModel
+
+
+def changed_fields(
+    old: BaseModel,
+    new: BaseModel,
+    *,
+    ignore: Collection[str] = (),
+) -> set[str]:
+    """Fields whose value differs in `new` (unknown/`None` = not changed).
+
+    A field only counts when it was actually *set* in the new state — a `None`
+    (the model did not know) is not a change.
+    """
+    old_dump = old.model_dump()
+    new_dump = new.model_dump()
+    ignored = set(ignore)
+    return {
+        key
+        for key in old_dump
+        if key not in ignored
+        and new_dump.get(key) is not None
+        and new_dump.get(key) != old_dump.get(key)
+    }
+
+
+def earliest_stage(
+    changed: Collection[str],
+    *,
+    field_stages: Mapping[str, str],
+    order: Sequence[str],
+) -> str | None:
+    """The earliest stage (by `order`) that any changed field belongs to.
+
+    Returns None when nothing changed (the caller decides the no-op behavior).
+    """
+    for stage in order:
+        affected = {
+            field for field, maps_to in field_stages.items() if maps_to == stage
+        }
+        if affected & set(changed):
+            return stage
+    return None
+
+
+def downstream_fields(
+    target: str,
+    *,
+    field_stages: Mapping[str, str],
+    order: Sequence[str],
+) -> frozenset[str]:
+    """All fields to reset when rebuilding from `target` (target stage inclusive).
+
+    Everything produced at `target` or later belongs to the rebuild and must be
+    cleared; upstream artifacts stay untouched.
+    """
+    if target not in order:
+        return frozenset()
+    index = order.index(target)
+    rebuild_stages = set(order[index:])
+    return frozenset(
+        field for field, maps_to in field_stages.items() if maps_to in rebuild_stages
+    )
+
+
+__all__ = ["changed_fields", "downstream_fields", "earliest_stage"]

reactifact/recipes/search.py

@@ -0,0 +1,81 @@
+"""recipes — ready-made search fan-out (§8, §24, §42).
+
+Effects-based: fans out over every configured source and *writes* the ranked,
+idempotent `SourceRef`s into the current produce's `effects` slot instead of
+returning a patch to merge by hand. Returns the scoped refs so the caller can
+inspect/rank them and add its own marker effect (e.g. `SearchDone`).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from ..context import Context
+from ..sources import SourceRef
+
+if TYPE_CHECKING:
+    from ..effects import Effects
+
+
+def _active_effects(context: Context) -> Effects:
+    from ..effects import current_effects
+
+    effects = current_effects()
+    if effects is None:
+        raise RuntimeError(
+            "fan_out_sources/materialize_doc must run inside a produce "
+            "(the runtime provides `self.effects` for the turn)"
+        )
+    return effects
+
+
+async def fan_out_sources(
+    context: Context,
+    query: str,
+    owner_id: str,
+    *,
+    limit: int = 5,
+    query_id: str | None = None,
+    extra_metadata: dict[str, Any] | None = None,
+    on_start: Callable[[str], None] | None = None,
+    on_count: Callable[[str, int], None] | None = None,
+) -> list[SourceRef]:
+    """Fans out over every configured source and builds idempotent refs in `effects`.
+
+    Each `SourceRef` becomes a `create(ref, id=f"ref:{ref.stable_id()}:{owner_id}")`
+    in the current produce's effect slot (§42), so a repeated fan-out for the same
+    owner re-creates the same ids (create-or-refresh). `on_start` / `on_count`
+    receive each source's id and hit count for progress announces. The returned
+    list is the scoped, ranked refs — the caller may inspect them and add its
+    own "search done" marker effect.
+    """
+    effects = _active_effects(context)
+    refs: list[SourceRef] = []
+    for source in context.resources.sources.values():
+        if on_start is not None:
+            on_start(source.source_id)
+        found = await source.asearch(query, limit=limit)
+        if on_count is not None:
+            on_count(source.source_id, len(found))
+        refs.extend(found)
+    refs.sort(key=lambda r: r.score or 0.0, reverse=True)
+
+    scoped_refs: list[SourceRef] = []
+    for ref in refs[:limit]:
+        scoped = ref.model_copy(
+            update={
+                "metadata": {
+                    **ref.metadata,
+                    "owner_id": owner_id,
+                    **(extra_metadata or {}),
+                },
+                "query_id": query_id if query_id is not None else owner_id,
+            }
+        )
+        scoped_refs.append(scoped)
+        effects.create(scoped, id=f"ref:{ref.stable_id()}:{owner_id}")
+    return scoped_refs
+
+
+__all__ = ["fan_out_sources"]

reactifact/recipes/skills.py

@@ -0,0 +1,108 @@
+"""recipes.skills — deterministic, keyword-triggered instruction snippets (§67).
+
+A "skill" here is the same shape popularized by Claude's Skills: a short
+markdown file with a `name`/`description` frontmatter and a body of
+procedural instructions. It differs from a `Source` in what it is *for* — a
+`Source` is retrieved to answer a question with facts; a skill is loaded to
+change *how* an LLM call for this turn is made (a rule to follow, a format to
+use) once its description matches the situation at hand.
+
+Matching is deterministic keyword overlap (`keyword_score`, §67) over
+name+description — no embeddings, no new core primitive (§61): a matched
+skill's `body` is just a string you prepend to a `structured_llm`/`llm_reply`
+prompt. Composition over abstraction.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .text import keyword_score
+
+_FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?(.*)\Z", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A named, described instruction snippet, loaded on demand (§67)."""
+
+    name: str
+    description: str
+    body: str
+
+
+def parse_skill(content: str, *, default_name: str = "") -> Skill:
+    """Parses `---\\nname: ...\\ndescription: ...\\n---\\n<body>` into a `Skill`.
+
+    Missing or malformed frontmatter is not an error: the whole content
+    becomes the body, `name` falls back to `default_name` (typically the file
+    stem) and `description` to `""` — a skill with no description simply
+    never matches (`match_skills` needs it to score above `threshold`).
+    """
+    match = _FRONTMATTER_RE.match(content)
+    if match is None:
+        return Skill(name=default_name, description="", body=content.strip())
+    header, body = match.groups()
+    fields: dict[str, str] = {}
+    for line in header.splitlines():
+        key, sep, value = line.partition(":")
+        if sep:
+            fields[key.strip().lower()] = value.strip()
+    return Skill(
+        name=fields.get("name", default_name),
+        description=fields.get("description", ""),
+        body=body.strip(),
+    )
+
+
+def load_skills(
+    directory: str | Path, *, extensions: tuple[str, ...] = (".md",)
+) -> list[Skill]:
+    """Parses every skill file under `directory` (honest empty list if absent)."""
+    root = Path(directory)
+    if not root.exists():
+        return []
+    skills: list[Skill] = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.suffix not in extensions:
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        skills.append(parse_skill(content, default_name=path.stem))
+    return skills
+
+
+def match_skills(
+    skills: list[Skill],
+    situation: str,
+    *,
+    threshold: float = 0.34,
+    limit: int = 1,
+) -> list[Skill]:
+    """The subset of `skills` whose name+description covers `situation` (§67).
+
+    `situation` is a short, code-written description of what is currently
+    being done ("assembling an answer backed by a computed total"), not
+    necessarily the user's raw question — the caller characterizes the
+    moment, the same way a skill's own description characterizes when to use
+    it. Ranked by `keyword_score`, highest first; only matches scoring at or
+    above `threshold` are returned, capped at `limit` — a skill should be a
+    precise trigger, not a grab-bag fallback that fires on every turn.
+    """
+    scored = [
+        (keyword_score(f"{skill.name} {skill.description}", situation), skill)
+        for skill in skills
+    ]
+    matched = sorted(
+        (item for item in scored if item[0] >= threshold),
+        key=lambda item: item[0],
+        reverse=True,
+    )
+    return [skill for _, skill in matched[:limit]]
+
+
+__all__ = ["Skill", "load_skills", "match_skills", "parse_skill"]

reactifact/recipes/status.py

@@ -0,0 +1,79 @@
+"""recipes — deterministic artifact status lifecycles (§67, §69)."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from ..artifacts import Artifact
+from ..context import Context
+from ..events import Event
+from ..produce import Produce
+
+StatusT = TypeVar("StatusT", bound=BaseModel)
+
+
+class StatusMachine(Produce[StatusT], Generic[StatusT]):
+    """Deterministic `status` lifecycle for an artifact type (§67).
+
+    Subclass it, set `artifact_type`/`terminal`, implement `next_status` (and
+    override `owner_key` or tweak `query_id_field`/`status_field` when the
+    artifact uses a different key/status column). The runtime advances the
+    lifecycle in reaction to events — no manual transition graph (§21, §24).
+    """
+
+    artifact_type: type[StatusT] | None = None
+    terminal: frozenset[str] = frozenset()
+    #: Which field of the artifact data carries the lifecycle key / status.
+    query_id_field: str = "query_id"
+    status_field: str = "status"
+
+    def owner_key(self, artifact: Artifact[Any]) -> str | None:
+        """Which lifecycle the artifact belongs to (default: its `query_id_field`)."""
+        data = artifact.data
+        if isinstance(data, BaseModel):
+            key = getattr(data, self.query_id_field, None)
+            if isinstance(key, str):
+                return key
+        return artifact.id
+
+    @abstractmethod
+    def next_status(self, context: Context, key: str) -> str | None:
+        """The status the lifecycle should move to, or None (no change)."""
+
+    def on_transition(
+        self, context: Context, key: str, old_status: str, new_status: str
+    ) -> None:
+        """Hook called right before a transition (progress announces, §53)."""
+
+    async def produce(
+        self,
+        context: Context,
+        inputs: list[Artifact[Any]],
+        event: Event | None = None,
+    ) -> None:
+        artifact = context.get(event.artifact_id) if event is not None else None
+        if artifact is None:
+            return None
+        key = self.owner_key(artifact)
+        if key is None:
+            return None
+        targets = [
+            t
+            for t in context.list_artifacts(self.artifact_type)
+            if self.owner_key(t) == key
+        ]
+        if not targets:
+            return None
+        target = targets[0]
+        current = getattr(target.data, self.status_field, None)
+        if current in self.terminal:
+            return None
+        expected = self.next_status(context, key)
+        if expected is None or expected == current:
+            return None
+        self.on_transition(context, key, str(current), expected)
+        self.effects.update(target, **{self.status_field: expected})
+        return None