reactifact 0.6.0__py3-none-any.whl

reactifact/llm_agent.py

@@ -0,0 +1,172 @@
+"""LLM agent containers: thin, without logic.
+
+- `LLMAgent` — ordinary: reactive/blocking? no — simple. Uses
+  `ToolUse` (blocking loop without HITL).
+- `HITLLMAgent` — can ask clarifying questions to a human through
+  `ToolUseHITL` (reactive loop, `PendingQuestion`).
+
+Both add boilerplate: `Consume.by_field(ToolAnswer, "agent", name)`,
+`ToolUse(...)`, and the HITL variant also `Consume(Observation)`,
+`Consume(PendingQuestion)` + produces Observation/PendingQuestion.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from pydantic import BaseModel
+
+from .agents import Agent
+from .artifacts import Artifact
+from .consume import Consume
+from .context import Context
+from .events import Event
+from .interrupt import PendingQuestion
+from .produce import Produce
+from .structured import SYSTEM_STRUCTURED, structured_llm
+from .tool_use import Observation, ToolAnswer, ToolUse, ToolUseHITL
+from .tools import Tool
+
+
+def _require_consumes(
+    cls_name: str, instance_name: str, user_consumes: list[Any]
+) -> None:
+    if not user_consumes:
+        raise ValueError(
+            f"{cls_name} {instance_name!r} has no consumes: the tool loop needs a "
+            "trigger. Specify at least one Consume(<question artifact>), e.g. "
+            "consumes=[Consume(Question)]."
+        )
+
+
+class StructuredGenerateAgent(Agent):
+    """Base agent: LLM → pydantic schema → Artifact (reads/commits as provenance).
+
+    Declare `schema`, override `build_prompt(inputs)`; optionally
+    `fallback(inputs)` for a deterministic fallback variant (§67).
+    """
+
+    schema: type[BaseModel] | None = None
+    system_prompt: str = SYSTEM_STRUCTURED
+    attempts: int = 2
+    temperature: float | None = None
+    max_tokens: int | None = None
+
+    def build_prompt(self, inputs: list[Artifact[Any]]) -> str:
+        raise NotImplementedError
+
+    def fallback(self, inputs: list[Artifact[Any]]) -> BaseModel | None:
+        return None
+
+    async def run(self, event: Event, context: Context) -> None:
+        inputs = self.collect_inputs(context)
+        if not inputs or self.schema is None:
+            return None
+        text = self.build_prompt(inputs)
+        result = await structured_llm(
+            context,
+            schema=self.schema,
+            system=self.system_prompt,
+            user=text,
+            attempts=self.attempts,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens,
+        )
+        if result is None:
+            result = self.fallback(inputs)
+        if result is None:
+            return None
+        from .effects import current_effects
+
+        effects = current_effects()
+        if effects is None:  # running outside the runtime — nothing to commit to
+            return None
+        effects.create(result)
+        return None
+
+
+class LLMAgent(Agent):
+    """Ordinary LLM agent with tools: blocking loop, no HITL.
+
+    In a subclass set: `system`, `tools`, `consumes` (questions), `produces`
+    (handling of the final answer).
+    """
+
+    system: str = ""
+    tools: Sequence[Tool] | dict[str, Tool] = ()
+    max_steps: int = 8
+    temperature: float | None = None
+    max_tokens: int | None = None
+
+    def __init__(self, *, name: str | None = None, **kwargs: Any):
+        llm_name = name or self.name or self.__class__.__name__.lower()
+        user_consumes = list(self.consumes) if self.consumes else []
+        _require_consumes(self.__class__.__name__, llm_name, user_consumes)
+        self.consumes = [
+            *user_consumes,
+            Consume.by_field(ToolAnswer, "agent", llm_name),
+        ]
+        user_produces = list(self.produces) if self.produces else []
+        self.produces = [
+            ToolUse(
+                name=llm_name,
+                system=self.system,
+                tools=self.tools,
+                max_steps=self.max_steps,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+            ),
+            Produce(ToolAnswer),
+            *user_produces,
+        ]
+        super().__init__(name=name, **kwargs)
+
+
+class HITLLMAgent(Agent):
+    """LLM agent with HITL: reactive loop that can ask a human.
+
+    Same as `LLMAgent`, plus: the LLM can return `type:"ask"` — a `PendingQuestion`
+    (kind="clarify") is created, the loop waits for the answer, and the answer is
+    returned as `Observation(source="user")` for the loop to continue.
+    """
+
+    system: str = ""
+    tools: Sequence[Tool] | dict[str, Tool] = ()
+    max_steps: int = 8
+    max_asks: int = 2
+    resume_announce: Callable[[str], str] | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+
+    def __init__(self, *, name: str | None = None, **kwargs: Any):
+        llm_name = name or self.name or self.__class__.__name__.lower()
+        user_consumes = list(self.consumes) if self.consumes else []
+        _require_consumes(self.__class__.__name__, llm_name, user_consumes)
+        self.consumes = [
+            *user_consumes,
+            Consume.by_field(ToolAnswer, "agent", llm_name),
+            Consume.by_field(Observation, "agent", llm_name),
+            Consume(
+                PendingQuestion,
+                condition=lambda a: a.data.notes.get("agent") == llm_name,
+            ),
+        ]
+        user_produces = list(self.produces) if self.produces else []
+        self.produces = [
+            ToolUseHITL(
+                name=llm_name,
+                system=self.system,
+                tools=self.tools,
+                max_steps=self.max_steps,
+                max_asks=self.max_asks,
+                resume_announce=self.resume_announce,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+            ),
+            Produce(ToolAnswer),
+            Produce(Observation),
+            Produce(PendingQuestion),
+            *user_produces,
+        ]
+        super().__init__(name=name, **kwargs)

reactifact/operations.py

@@ -0,0 +1,192 @@
+"""reactifact.operations — the runtime's compiled operations (§12, §15, §24).
+
+`Patch` (the container) and `Effects` (the authoring surface) both ultimately
+reduce to these dataclasses. They are what the runtime applies, validates,
+commits and replays — the *compiled* form of "what changed". Applications
+rarely touch them directly (they write `self.effects.*` instead).
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from typing import Any
+
+
+def _import_class(full_name: str) -> Any:
+    module_name, class_name = full_name.rsplit(".", 1)
+    module = importlib.import_module(module_name)
+    return getattr(module, class_name)
+
+
+@dataclass
+class Operation:
+    """Base operation in a patch."""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {}
+
+
+@dataclass
+class Create(Operation):
+    data: Any  # Pydantic model for the new artifact
+
+    data_type: str = ""
+    # Filled in by the runtime when the patch is applied: the real id of the created artifact.
+    # Required for replay and rebuilding state from commits.
+    artifact_id: str | None = None
+    # Stable id (§42): if an artifact with such an id already exists, create
+    # idempotently returns the existing one and does not create a duplicate.
+    # Used for re-resolving sources without multiplying evidence/links.
+    id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.data_type and hasattr(self.data, "__class__"):
+            self.data_type = (
+                f"{self.data.__class__.__module__}.{self.data.__class__.__qualname__}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": "create",
+            "data": self.data.model_dump(mode="json"),
+            "data_type": self.data_type,
+            "artifact_id": self.artifact_id,
+            "id": self.id,
+        }
+
+
+@dataclass
+class Update(Operation):
+    artifact_id: str
+    new_data: Any  # Pydantic model with updated data
+    data_type: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.data_type and hasattr(self.new_data, "__class__"):
+            self.data_type = f"{self.new_data.__class__.__module__}.{self.new_data.__class__.__qualname__}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": "update",
+            "artifact_id": self.artifact_id,
+            "data": self.new_data.model_dump(mode="json"),
+            "data_type": self.data_type,
+        }
+
+
+@dataclass
+class Delete(Operation):
+    artifact_id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": "delete",
+            "artifact_id": self.artifact_id,
+        }
+
+
+@dataclass(frozen=True)
+class Relation:
+    """Edges of the artifact graph (§15): a directed link `source —relation→ target`.
+
+    Not an artifact, but a first-class dimension of the Context state: created/removed
+    by Link/Unlink operations, serialized into commits and snapshots.
+    """
+
+    source_id: str
+    relation: str
+    target_id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source_id": self.source_id,
+            "relation": self.relation,
+            "target_id": self.target_id,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Relation:
+        return cls(
+            source_id=d["source_id"],
+            relation=d["relation"],
+            target_id=d["target_id"],
+        )
+
+
+@dataclass
+class Link(Operation):
+    """Sets the link `artifact_id —relation→ target_id` (§12, §15)."""
+
+    artifact_id: str
+    relation: str
+    target_id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": "link",
+            "artifact_id": self.artifact_id,
+            "relation": self.relation,
+            "target_id": self.target_id,
+        }
+
+
+@dataclass
+class Unlink(Operation):
+    """Removes links `artifact_id —relation→ *`.
+
+    `relation`/`target_id` are optional: None = any. The pattern is resolved at
+    apply time, so replayability is preserved.
+    """
+
+    artifact_id: str
+    relation: str | None = None
+    target_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": "unlink",
+            "artifact_id": self.artifact_id,
+            "relation": self.relation,
+            "target_id": self.target_id,
+        }
+
+
+def operation_from_dict(d: dict[str, Any]) -> Operation:
+    op_type = d["type"]
+    if op_type == "create":
+        model_class = _import_class(d["data_type"])
+        data = model_class.model_validate(d["data"])
+        return Create(data=data, id=d.get("id"), artifact_id=d.get("artifact_id"))
+    elif op_type == "update":
+        model_class = _import_class(d["data_type"])
+        new_data = model_class.model_validate(d["data"])
+        return Update(artifact_id=d["artifact_id"], new_data=new_data)
+    elif op_type == "delete":
+        return Delete(artifact_id=d["artifact_id"])
+    elif op_type == "link":
+        return Link(
+            artifact_id=d["artifact_id"],
+            relation=d["relation"],
+            target_id=d["target_id"],
+        )
+    elif op_type == "unlink":
+        return Unlink(
+            artifact_id=d["artifact_id"],
+            relation=d.get("relation"),
+            target_id=d.get("target_id"),
+        )
+    else:
+        raise ValueError(f"Unknown operation type: {op_type}")
+
+
+__all__ = [
+    "Create",
+    "Delete",
+    "Link",
+    "Operation",
+    "Relation",
+    "Unlink",
+    "Update",
+    "operation_from_dict",
+]

reactifact/patches.py

@@ -0,0 +1,112 @@
+"""reactifact.patches — the `Patch` container (§12, §24).
+
+`Patch` is the runtime's *transport*: an ordered set of `operations` (defined in
+`reactifact.operations`) that gets applied as one commit. The authoring surface of
+produces is `self.effects`; a `Patch` is built by the runtime (compiling the
+effects slot), by `Effects.to_patch`, and by custom `Agent.run` implementations
+that assemble a change-set by hand (the escape hatch).
+
+The Operation types and `operation_from_dict` live in `reactifact.operations` and
+are re-exported here for backward compatibility.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any, cast
+
+from .operations import (
+    Create,
+    Delete,
+    Link,
+    Operation,
+    Relation,
+    Unlink,
+    Update,
+    operation_from_dict,
+)
+
+if TYPE_CHECKING:
+    from .artifacts import Artifact
+
+
+def _id_of(value: Any) -> str:
+    """Resolves an id from a string or an Artifact (or an effects handle)."""
+    if isinstance(value, str):
+        return value
+    return cast(str, value.id)  # Artifact | effect Handle
+
+
+def _auto_id(model_name: str) -> str:
+    return f"{model_name.lower()}:{uuid.uuid4().hex[:8]}"
+
+
+class Patch:
+    """An ordered set of operations to apply to the Context (§12)."""
+
+    def __init__(self, operations: list[Operation] | None = None):
+        self.operations: list[Operation] = operations if operations is not None else []
+
+    def add(self, op: Operation) -> Patch:
+        self.operations.append(op)
+        return self
+
+    def create(self, data: Any, id: str | None = None) -> Patch:
+        return self.add(Create(data, id=id))
+
+    def update(self, artifact_id: Any, new_data: Any) -> Patch:
+        return self.add(Update(_id_of(artifact_id), new_data))
+
+    def update_fields(self, artifact: Artifact[Any], **fields: Any) -> Patch:
+        """Update artifact fields without rebuilding the model.
+
+        Sugar over `update`: it does the `model_copy(update=fields)` itself and puts
+        the full new model into `Update` (preserving commit replayability).
+        """
+        return self.update(artifact.id, artifact.data.model_copy(update=fields))
+
+    def delete(self, artifact_id: Any) -> Patch:
+        return self.add(Delete(_id_of(artifact_id)))
+
+    def link(self, artifact_id: Any, relation: str, target_id: Any) -> Patch:
+        return self.add(Link(_id_of(artifact_id), relation, _id_of(target_id)))
+
+    def unlink(
+        self,
+        artifact_id: Any,
+        relation: str | None = None,
+        target_id: Any | None = None,
+    ) -> Patch:
+        return self.add(
+            Unlink(
+                _id_of(artifact_id),
+                relation,
+                _id_of(target_id) if target_id is not None else None,
+            )
+        )
+
+    def merge(self, *patches: Patch | None) -> Patch:
+        """Adds operations from `patches` to this patch; None are skipped.
+
+        Returns `self` (chaining, like `add`/`create`/`update`/`delete`).
+        """
+        for patch in patches:
+            if patch is not None:
+                self.operations.extend(patch.operations)
+        return self
+
+    def is_empty(self) -> bool:
+        return len(self.operations) == 0
+
+
+__all__ = [
+    "Create",
+    "Delete",
+    "Link",
+    "Operation",
+    "Patch",
+    "Relation",
+    "Unlink",
+    "Update",
+    "operation_from_dict",
+]

reactifact/produce.py

@@ -0,0 +1,226 @@
+"""reactifact.produce — how a produce writes an artifact (§24).
+
+Two styles cover almost everything and are the two canonical ones — reach
+for one of these first:
+
+- **Subclass + effects** — `class X(Produce[Model]): async def produce(self,
+  context, inputs, event=None): self.effects.create(...); return None`. Use
+  this whenever the produce has its own state-free logic worth naming as a
+  class (the common case in every example under `examples/`).
+- **`@produce(Model)` function** — `@produce(Model)\\ndef f(context, inputs,
+  effects): effects.create(...)`, or the plain return-style
+  `def f(context, inputs): return Model(...)` (also accepts `event`). One
+  decorator, both signatures recognized by parameter name — pick this for a
+  short, one-off produce with no class ceremony.
+
+Two other things `Produce` accepts are *not* on that list on purpose:
+
+- `Produce(Model, factory=fn)` — a bare two-argument-factory constructor
+  kwarg, **deprecated** (raises `DeprecationWarning`). It predates the
+  `@produce` decorator, only supports `(context, inputs[, event]) -> Model |
+  list | Patch | None`, and can't see the effects slot at all — strictly
+  weaker than `@produce(Model)`, which covers the same signature plus
+  `effects`. Kept only so old code doesn't break; port it to `@produce`.
+- Overriding `Agent.run(self, event, context) -> Patch | None` directly,
+  bypassing `Produce` entirely (though not necessarily `effects` — the
+  runtime still merges whatever `current_effects()` collected during the
+  call, same as for a normal produce). This is a low-level, internal escape
+  hatch for cases a `Produce` genuinely can't express — not a third everyday
+  style to reach for on a first pass. `reactifact.llm_agent.StructuredGenerateAgent`
+  is the one built-in exception (writes via `current_effects()` directly
+  instead of `self.effects`, since `Agent` — unlike `Produce` — has no
+  `effects` property); no example under `examples/` overrides `run()`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import warnings
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar, get_args, get_origin
+
+from pydantic import BaseModel
+
+from .artifacts import Artifact, ArtifactType
+from .context import Context
+from .effects import Effects
+from .events import Event
+from .patches import Patch
+
+TOut = TypeVar("TOut", bound=BaseModel)
+
+
+class Produce(Generic[TOut]):
+    """Describes the produced artifact type and how it is created.
+
+    `artifact_type` is auto-derived from the generic when a subclass is written
+    as `class X(Produce[Foo])` — write it explicitly only to override or when
+    the class has no generic (e.g. programmatic `Produce(Foo)`).
+    """
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if "artifact_type" in cls.__dict__ or cls.artifact_type is not None:
+            return
+        for base in getattr(cls, "__orig_bases__", ()):
+            if get_origin(base) is Produce:
+                args = get_args(base)
+                if args and isinstance(args[0], type):
+                    cls.artifact_type = args[0]
+                    return
+
+    artifact_type: ArtifactType | None = None
+    factory: Callable[..., Any] | None = None
+
+    def __init__(
+        self,
+        artifact_type: ArtifactType | None = None,
+        factory: Callable[..., Any] | None = None,
+    ):
+        self.artifact_type = artifact_type or self.__class__.artifact_type
+        if self.artifact_type is None:
+            raise ValueError(
+                "artifact_type must be provided either as class attribute or constructor argument"
+            )
+        self.factory = factory if factory is not None else self.__class__.factory
+        if self.factory is not None:
+            warnings.warn(
+                "Produce(..., factory=...) is deprecated: it only supports "
+                "(context, inputs[, event]) -> Model | list | Patch | None and "
+                "can't see the effects slot (no `effects` param support). Use "
+                "the @produce(Type) decorator instead — same return-style "
+                "signature, plus optional effects/event params when you need "
+                "them. See the reactifact.produce module docstring.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        self._accepts_event = False
+        if self.factory is not None:
+            try:
+                signature = inspect.signature(self.factory)
+            except (TypeError, ValueError):
+                signature = None
+            if signature is not None:
+                positional = [
+                    p
+                    for p in signature.parameters.values()
+                    if not p.kind & inspect.Parameter.VAR_POSITIONAL
+                ]
+                self._accepts_event = len(positional) >= 3
+
+    @property
+    def effects(self) -> Effects:
+        """The produce-scoped effect slot (authoring surface, §24).
+
+        Only meaningful *inside* `produce()`: the runtime pushes a fresh slot
+        per execution. Returns an error outside a run.
+        """
+        from .effects import current_effects
+
+        slot = current_effects()
+        if slot is None:
+            raise RuntimeError(
+                "Produce.effects is only available while the runtime executes "
+                "this produce — write effects inside produce(), not before it."
+            )
+        return slot
+
+    async def produce(
+        self,
+        context: Context,
+        inputs: list[Artifact[Any]],
+        event: Event | None = None,
+    ) -> None:
+        """Runs the factory and writes its effect into the slot (§24).
+
+        Subclass-style overrides write `self.effects.*` and return None;
+        a `None` return means "no work". (The progress nest the old
+        `Patch | None` return — the runtime compiles the slot now.)
+        """
+        if self.factory is None:
+            return None
+
+        if self._accepts_event:
+            result = self.factory(context, inputs, event)
+        else:
+            result = self.factory(context, inputs)
+        if asyncio.iscoroutine(result):
+            result = await result
+
+        self._apply_result(result)
+
+    def _apply_result(self, result: Any) -> None:
+        """Writes a factory result into the effect slot (§24).
+
+        `None` — nothing; a model or a list of models — creates; a Patch — the
+        factory-level legacy escape (its operations are appended to the effects).
+        """
+        if result is None:
+            return
+        if isinstance(result, Patch):
+            for op in result.operations:
+                self.effects.add(op)
+            return
+        if isinstance(result, list):
+            for item in result:
+                self.effects.create(item)
+        else:
+            self.effects.create(result)
+
+
+def produce(
+    artifact_type: ArtifactType,
+) -> Callable[[Callable[..., Any]], Produce[Any]]:
+    """Decorator to create a Produce from a function.
+
+    The function must accept ``(context, inputs)`` plus, optionally, ``event``
+    and/or ``effects`` (each recognized by name):
+
+    - ``def f(context, inputs)`` — return style (no event, no slot);
+    - ``def f(context, inputs, event)`` — return style with the event;
+    - ``def f(context, inputs, effects)`` — author the produce-scoped
+      ``Effects`` slot directly (the same surface as ``self.effects``);
+    - ``def f(context, inputs, event, effects)`` — both.
+
+    Return style: return a model / a list of models / a ``Patch`` / ``None``;
+    the runtime writes them into the slot (reate/append) as usual. Effects
+    style: write ``effects.create/update/link/ask/...`` and return ``None`` —
+    the function behaves exactly like a class produce with ``self.effects``.
+    """
+
+    def decorator(func: Callable[..., Any]) -> Produce[Any]:
+        # Recognize which optional parameters the function declares.
+        params = list(inspect.signature(func).parameters.values())
+        names = [p.name for p in params]
+        if len(params) < 2:
+            raise TypeError(
+                f"Function {func.__name__} must accept at least (context, inputs)"
+            )
+        accepts_event = "event" in names
+        accepts_effects = "effects" in names
+
+        class _FunctionProduce(Produce[Any]):
+            async def produce(
+                self,
+                context: Context,
+                inputs: list[Artifact[Any]],
+                event: Event | None = None,
+            ) -> None:
+                args: list[Any] = [context, inputs]
+                if accepts_event:
+                    args.append(event)
+                result = (
+                    func(*args, effects=self.effects)
+                    if accepts_effects
+                    else func(*args)
+                )
+                if asyncio.iscoroutine(result):
+                    result = await result
+                self._apply_result(result)
+
+        # Return an instance of the Produce class with the required artifact_type
+        instance = _FunctionProduce(artifact_type=artifact_type)
+        return instance
+
+    return decorator