reactifact 0.6.0__py3-none-any.whl

reactifact/recipes/text.py

@@ -0,0 +1,202 @@
+"""recipes.text — deterministic text scoring without embeddings (§8, §67).
+
+Keyword coverage is the neutral fallback where vectors are optional: the English
+`knowledge` chat and the Russian `repair` demo rank documents/catalog rows by
+how much of the query is present in the text. Everything here is pure and
+LLM-free; `keyword_score` is stop-word- and (optionally) stem-aware.
+"""
+
+from __future__ import annotations
+
+import re
+
+_WORD = re.compile(r"[\wа-яё]{2,}")
+
+EN_STOPWORDS = frozenset(
+    {
+        "a",
+        "an",
+        "the",
+        "and",
+        "or",
+        "of",
+        "to",
+        "in",
+        "for",
+        "on",
+        "with",
+        "at",
+        "by",
+        "from",
+        "into",
+        "off",
+        "out",
+        "over",
+        "under",
+        "about",
+        "up",
+        "down",
+        "after",
+        "before",
+        "during",
+        "between",
+        "through",
+        "against",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        "has",
+        "have",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "can",
+        "could",
+        "should",
+        "how",
+        "what",
+        "why",
+        "which",
+        "who",
+        "whom",
+        "when",
+        "where",
+        "this",
+        "that",
+        "these",
+        "those",
+        "it",
+        "its",
+        "he",
+        "him",
+        "his",
+        "she",
+        "her",
+        "they",
+        "them",
+        "their",
+        "we",
+        "us",
+        "our",
+        "you",
+        "your",
+        "i",
+        "me",
+        "my",
+        "not",
+        "no",
+        "yes",
+        "but",
+        "so",
+        "then",
+        "than",
+        "too",
+        "very",
+        "just",
+        "also",
+        "because",
+        "as",
+        "if",
+        "much",
+        "many",
+        "more",
+        "most",
+    }
+)
+
+#: Russian inflectional suffixes (used when `use_stems=True`).
+_RU_SUFFIXES = (
+    "аться",
+    "иться",
+    "ами",
+    "ями",
+    "ой",
+    "ий",
+    "ый",
+    "ое",
+    "ее",
+    "ить",
+    "ать",
+    "ять",
+    "ом",
+    "ем",
+    "ам",
+    "ям",
+    "ия",
+    "ию",
+    "ией",
+    "ых",
+    "их",
+    "ая",
+    "яя",
+    "у",
+    "ю",
+    "о",
+    "а",
+    "е",
+    "ы",
+    "и",
+    "й",
+)
+
+
+def stem(word: str) -> str:
+    """Truncates common inflectional suffixes of a Russian word.
+
+    «аутентификацию» and «аутентификация» must match where embedders are not
+    needed. English words pass through unchanged (the suffix list is Cyrillic).
+    """
+    w = word.lower()
+    changed = True
+    while changed:
+        changed = False
+        for suffix in _RU_SUFFIXES:
+            if len(w) - len(suffix) >= 3 and w.endswith(suffix):
+                w = w[: -len(suffix)]
+                changed = True
+                break
+    return w
+
+
+def _tokens(text: str) -> list[str]:
+    """Lowercased word tokens; digit-only tokens never match a query term."""
+    lower = text.lower()
+    return [t for t in _WORD.findall(lower) if not t.isdigit()]
+
+
+def stem_words(text: str) -> frozenset[str]:
+    """Frozenset of word stems in the text (Latin and Cyrillic)."""
+    return frozenset(stem(t) for t in _tokens(text))
+
+
+def keyword_score(
+    text: str,
+    query: str,
+    *,
+    stopwords: frozenset[str] = EN_STOPWORDS,
+    use_stems: bool = False,
+) -> float:
+    """Coverage of the query terms by the text (0..1), without embedders.
+
+    `stopwords` are removed from both sides (English function words by default);
+    with `use_stems=True` both sides are stemmed (Russian morphology), so
+    «аутентификация» matches «аутентификацию». Returns 0.0 for an empty query.
+    """
+    text_terms = set(_tokens(text)) - set(stopwords)
+    query_terms = set(_tokens(query)) - set(stopwords)
+    if not query_terms:
+        return 0.0
+    if use_stems:
+        text_terms = {stem(t) for t in text_terms}
+        query_terms = {stem(t) for t in query_terms}
+    return sum(1 for term in query_terms if term in text_terms) / len(query_terms)
+
+
+__all__ = ["EN_STOPWORDS", "keyword_score", "stem", "stem_words"]

reactifact/relations.py

@@ -0,0 +1,104 @@
+"""reactifact.relations — the provenance/link graph (§15).
+
+Extracted out of `Context`: `RelationGraph` owns only the
+`(source, relation, target) → Relation` mapping and the query/mutation
+operations over it. It has no knowledge of artifacts, commits, or merge —
+`Context` still resolves "does this artifact exist" itself (`related()`
+needs the artifact store, so that method stays on `Context`, as a thin
+wrapper that filters `RelationGraph.relations()` against `self._artifacts`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .patches import Relation
+
+RelationKey = tuple[str, str, str]
+
+
+class RelationGraph:
+    """The live link graph: create/remove/query edges (§15)."""
+
+    __slots__ = ("_edges",)
+
+    def __init__(self) -> None:
+        self._edges: dict[RelationKey, Relation] = {}
+
+    def link(self, source_id: str, relation: str, target_id: str) -> Relation:
+        """Establishes a link `source_id —relation→ target_id` (idempotently, §42)."""
+        rel = Relation(source_id=source_id, relation=relation, target_id=target_id)
+        self._edges[(rel.source_id, rel.relation, rel.target_id)] = rel
+        return rel
+
+    def unlink(
+        self,
+        source_id: str,
+        relation: str | None = None,
+        target_id: str | None = None,
+    ) -> int:
+        """Removes edges; `relation`/`target_id` = None mean "any"."""
+        removed = 0
+        for key in [k for k in self._edges if k[0] == source_id]:
+            if relation is not None and key[1] != relation:
+                continue
+            if target_id is not None and key[2] != target_id:
+                continue
+            del self._edges[key]
+            removed += 1
+        return removed
+
+    def relations(
+        self,
+        source_id: str | None = None,
+        relation: str | None = None,
+        target_id: str | None = None,
+    ) -> list[Relation]:
+        """All edges, optionally filtered by any component."""
+        result: list[Relation] = []
+        for rel in self._edges.values():
+            if source_id is not None and rel.source_id != source_id:
+                continue
+            if relation is not None and rel.relation != relation:
+                continue
+            if target_id is not None and rel.target_id != target_id:
+                continue
+            result.append(rel)
+        return result
+
+    def __contains__(self, key: RelationKey) -> bool:
+        return key in self._edges
+
+    def __len__(self) -> int:
+        return len(self._edges)
+
+    def values(self) -> list[Relation]:
+        return list(self._edges.values())
+
+    def items(self) -> list[tuple[RelationKey, Relation]]:
+        return list(self._edges.items())
+
+    def copy(self) -> RelationGraph:
+        clone = RelationGraph()
+        clone._edges = dict(self._edges)
+        return clone
+
+    def to_dict(self) -> list[dict[str, Any]]:
+        return [rel.to_dict() for rel in self._edges.values()]
+
+    @classmethod
+    def from_dict(cls, items: list[dict[str, Any]]) -> RelationGraph:
+        graph = cls()
+        for d in items:
+            rel = Relation.from_dict(d)
+            graph._edges[(rel.source_id, rel.relation, rel.target_id)] = rel
+        return graph
+
+    @classmethod
+    def from_mapping(cls, mapping: dict[RelationKey, Relation]) -> RelationGraph:
+        graph = cls()
+        graph._edges = dict(mapping)
+        return graph
+
+
+__all__ = ["RelationGraph", "RelationKey"]

reactifact/replay.py

@@ -0,0 +1,187 @@
+"""reactifact.replay — deterministic reproduction of runs (§55).
+
+Two complementary halves:
+
+1. `ReplayLLM` — a provider-level recording studio. `mode="record"` wraps a real
+   provider and appends every `(request → response)` pair to a JSONL file;
+   `mode="replay"` answers *exactly* the recorded calls and raises `ReplayMiss`
+   when a call diverges from the recording — a divergent call must not be
+   answered with a wrong result (§59, §55).
+
+   Record once (real model), then re-run the runtime with the replaying LLM:
+   because every deterministic path is unchanged, the run reproduces the same
+   artifacts, and "why did the agent produce this answer?" (§55) can be answered
+   by walking the reproduced state.
+
+2. `replay_context` / `replay_summary` — reconstruct a saved session's state at
+   a specific commit (the commit chain is deterministic, §14), i.e. a cheap,
+   offline "what was the state when the agent said that".
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from .context import Context
+from .providers import LLMProvider, LLMRequest, LLMResponse, LLMResponseChunk
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from .session import SessionStore
+
+logger = logging.getLogger(__name__)
+
+
+class ReplayMiss(RuntimeError):
+    """A replaying call did not match the recording (§55)."""
+
+
+def _request_key(model: str, request: LLMRequest) -> str:
+    payload = {
+        "model": model,
+        "temperature": request.temperature,
+        "response_format": request.response_format,
+        "messages": [{"role": m.role, "content": m.content} for m in request.messages],
+    }
+    canonical = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+class ReplayLLM(LLMProvider):
+    """Records LLM calls to a JSONL file, or replays them exactly.
+
+        recorder = ReplayLLM("calls.jsonl", mode="record", inner=real_llm)
+        resources = RuntimeResources(llm=recorder)
+        runtime.run()                      # record pass
+
+        replay = ReplayLLM("calls.jsonl", mode="replay")
+        resources = RuntimeResources(llm=replay)
+        runtime.run()                      # deterministic reproduction (§55)
+
+    A recording also answers the "why" question: every call carries the exact
+    prompt and the exact response, so the product story is reproducible.
+    """
+
+    def __init__(
+        self,
+        recording: str | Path,
+        *,
+        mode: Literal["record", "replay"] = "replay",
+        inner: LLMProvider | None = None,
+        model: str = "",
+    ):
+        if mode == "record" and inner is None:
+            raise ValueError("mode='record' requires an `inner` provider")
+        self.recording = Path(recording)
+        self.mode = mode
+        self._inner = inner
+        self.model = model
+        self._cache: dict[str, dict[str, Any]] | None = None
+
+    # -- LLMProvider ---------------------------------------------------------
+
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        if self.mode == "replay":
+            return self._replay(request)
+        assert self._inner is not None
+        response = await self._inner.complete(request)
+        self._append(request, response)
+        return response
+
+    async def stream(self, request: LLMRequest) -> AsyncIterator[LLMResponseChunk]:
+        if self.mode == "record" and self._inner is not None:
+            async for chunk in self._inner.stream(request):
+                yield chunk
+            return
+        raise ReplayMiss(
+            "stream() is not replayed; record stream calls or use complete()"
+        )
+
+    # -- recording -----------------------------------------------------------
+
+    def _append(self, request: LLMRequest, response: LLMResponse) -> None:
+        entry = {
+            "key": _request_key(self.model, request),
+            "model": self.model,
+            "response": {
+                "text": response.text,
+                "finish_reason": response.finish_reason,
+            },
+            "usage": response.usage,
+        }
+        self.recording.parent.mkdir(parents=True, exist_ok=True)
+        with self.recording.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    # -- replaying -----------------------------------------------------------
+
+    def _load(self) -> dict[str, dict[str, Any]]:
+        if self._cache is not None:
+            return self._cache
+        cache: dict[str, dict[str, Any]] = {}
+        if self.recording.exists():
+            for line in self.recording.read_text(encoding="utf-8").splitlines():
+                entry = json.loads(line)
+                cache[entry["key"]] = entry
+        self._cache = cache
+        return cache
+
+    def _replay(self, request: LLMRequest) -> LLMResponse:
+        key = _request_key(self.model, request)
+        entry = self._load().get(key)
+        if entry is None:
+            logger.warning("replay miss for %r", key)
+            raise ReplayMiss(
+                "the run diverged from the recording — a call was not recorded. "
+                "Re-record with mode='record', or check whether the prompt "
+                "changed since the recording was made."
+            )
+        response = entry["response"]
+        return LLMResponse(
+            text=response["text"],
+            finish_reason=response.get("finish_reason"),
+            usage=dict(entry.get("usage") or {}),
+        )
+
+
+async def replay_context(
+    store: SessionStore,
+    session_id: str,
+    *,
+    version: int | None = None,
+) -> Context:
+    """Reconstructs a saved session's state, optionally at a past commit (§55).
+
+    The session checkpoint carries the full deterministic commit chain (§14), so
+    replaying to a version needs no agent execution — it is pure state recovery.
+    """
+    context = await store.load_session(session_id)
+    if context is None:
+        raise KeyError(f"session {session_id!r} not found")
+    if version is not None:
+        context.checkout(version)
+    return context
+
+
+def replay_summary(context: Context) -> dict[str, Any]:
+    """A compact "state at this point" summary for the replay CLI."""
+    artifacts = context.list_artifacts()
+    by_type: dict[str, int] = {}
+    for artifact in artifacts:
+        tname = artifact.data.__class__.__name__
+        by_type[tname] = by_type.get(tname, 0) + 1
+    return {
+        "version": context.version,
+        "artifacts": len(artifacts),
+        "by_type": by_type,
+        "relations": len(context.relations()),
+        "pending_questions": len(context.pending_questions()),
+    }
+
+
+__all__ = ["ReplayLLM", "ReplayMiss", "replay_context", "replay_summary"]

reactifact/resources.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .providers import EmbeddingProvider, LLMProvider
+from .sources import Source
+
+
+class RuntimeResources:
+    def __init__(
+        self,
+        llm: LLMProvider | None = None,
+        embedder: EmbeddingProvider | None = None,
+        sources: dict[str, Source] | None = None,
+        **additional: Any,
+    ):
+        self.llm = llm
+        self.embedder = embedder
+        self.sources = sources or {}
+        self.additional = additional
+
+    def get_source(self, source_id: str) -> Source | None:
+        return self.sources.get(source_id)
+
+    def set(self, name: str, value: Any) -> None:
+        self.additional[name] = value
+
+    def get(self, name: str) -> Any:
+        return self.additional.get(name)
+
+    async def aclose(self) -> None:
+        """Closes the llm/embedder clients if they support it.
+
+        Duck-typed: `LLMProvider`/`EmbeddingProvider` don't require `aclose`
+        (a fake/no-op test double doesn't need one), so it's called only when
+        present. Nothing in the runtime calls this automatically — resources
+        are typically shared across many turns/runtimes, and closing them
+        early would break whatever still holds a reference. Call it yourself
+        once, at real shutdown: a FastAPI `lifespan`, or the end of a script.
+        `ChatAssistant` is the one exception — see its docstring.
+        """
+        for provider in (self.llm, self.embedder):
+            aclose = getattr(provider, "aclose", None)
+            if aclose is not None:
+                await aclose()