prompture 1.1.3.dev3__tar.gz → 1.1.4.dev2__tar.gz

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.1.3.dev3
+Version: 1.1.4.dev2
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.3.dev3'
-__version_tuple__ = version_tuple = (1, 1, 3, 'dev3')
+__version__ = version = '1.1.4.dev2'
+__version_tuple__ = version_tuple = (1, 1, 4, 'dev2')
 
 __commit_id__ = commit_id = None

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture/agents/__init__.py

@@ -38,7 +38,13 @@ from .persona import (
     reset_persona_registry,
     reset_trait_registry,
 )
-from .review_loop import AsyncReviewLoop, ReviewLoopIteration, ReviewLoopResult
+from .review_loop import (
+    AsyncReviewLoop,
+    ReviewLoopEvent,
+    ReviewLoopEventType,
+    ReviewLoopIteration,
+    ReviewLoopResult,
+)
 from .skills import (
     SKILLS,
     SkillInfo,
@@ -97,6 +103,8 @@ __all__ = [
     "GuardrailError",
     "ModelRetry",
     "Persona",
+    "ReviewLoopEvent",
+    "ReviewLoopEventType",
     "ReviewLoopIteration",
     "ReviewLoopResult",
     "RunContext",

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture/agents/assistant.py

@@ -62,7 +62,7 @@ import asyncio
 import dataclasses
 import logging
 import threading
-from collections.abc import AsyncIterator, Callable
+from collections.abc import AsyncIterator
 from typing import Any
 
 from .persona import Persona
@@ -145,34 +145,61 @@ class Assistant:
         output_type: Optional Pydantic model passed to ``AsyncAgent`` for
             structured-output parsing.  Ignored for the coding-agent
             backend.
-        options: Driver options merged into the underlying agent (e.g.
-            ``{"max_tokens": 8000, "timeout": 600}``).
+        options: Driver options forwarded to the underlying agent's
+            ``options`` kwarg (driver-level settings like
+            ``{"max_tokens": 8000, "timeout": 600}``). Distinct from
+            ``agent_options`` below, which targets the agent constructor
+            itself.
+        agent_options: Extra kwargs spread into ``AsyncAgent.__init__``
+            when ``enable_planning=False``. Use this for budget controls
+            and other agent-level settings the Assistant doesn't expose
+            as first-class fields, e.g.
+            ``{"max_iterations": 5, "max_cost": 0.50,
+            "budget_policy": "hard_stop",
+            "fallback_models": ["openai/gpt-4o-mini"]}``.
         coding_agent_options: Extra kwargs forwarded to
             ``run_coding_agent`` / ``astream_coding_agent`` (e.g.
             ``approval_mode``, ``cwd``, ``timeout``).
+        deep_agent_options: Extra kwargs spread into
+            ``AsyncDeepAgent.__init__`` when ``enable_planning=True``
+            (e.g. ``{"enable_vfs": False, "enable_summarization": False,
+            "max_iterations": 30}``).
     """
 
     name: str
     persona: Persona
     skills: tuple[SkillInfo, ...] = ()
-    tools: tuple[Callable[..., Any], ...] = ()
+    # Either a tuple of Python callables OR a ToolRegistry — both are
+    # accepted by the underlying AsyncAgent.
+    tools: Any = ()
     model: str | None = None
     coding_agent: str | None = None
     description: str = ""
     variables: dict[str, Any] = dataclasses.field(default_factory=dict)
     enable_planning: bool = False
     output_type: Any = None
+    output_key: str | None = None
     options: dict[str, Any] = dataclasses.field(default_factory=dict)
     coding_agent_options: dict[str, Any] = dataclasses.field(default_factory=dict)
+    # Extra kwargs forwarded to AsyncAgent.__init__ when enable_planning is
+    # False (e.g. {"max_iterations": 5, "max_cost": 0.50,
+    # "budget_policy": "hard_stop", "fallback_models": ["openai/gpt-4o-mini"]}).
+    # Anything AsyncAgent accepts works here — see its signature for the
+    # full list (max_tokens, persistent_conversation, output_key, ...).
+    agent_options: dict[str, Any] = dataclasses.field(default_factory=dict)
+    # Extra kwargs forwarded to AsyncDeepAgent when enable_planning=True
+    # (e.g. {"enable_vfs": False, "enable_summarization": False}).
+    deep_agent_options: dict[str, Any] = dataclasses.field(default_factory=dict)
 
     # ----- construction --------------------------------------------------
 
     def __post_init__(self) -> None:
-        # Normalise iterable args to immutable tuples so the dataclass
-        # stays hashable + frozen-friendly.
+        # Normalise skills to an immutable tuple.  Tools may be either a
+        # tuple of callables OR a ToolRegistry — both are passed
+        # through to AsyncAgent unchanged.
         if not isinstance(self.skills, tuple):
             object.__setattr__(self, "skills", tuple(self.skills))
-        if not isinstance(self.tools, tuple):
+        if isinstance(self.tools, (list, set)):
             object.__setattr__(self, "tools", tuple(self.tools))
 
         if bool(self.model) == bool(self.coding_agent):
@@ -183,8 +210,7 @@ class Assistant:
             )
         if self.enable_planning and not self.model:
             raise ValueError(
-                "enable_planning=True only applies to the LLM backend "
-                "(set `model=...`, not `coding_agent=...`)."
+                "enable_planning=True only applies to the LLM backend (set `model=...`, not `coding_agent=...`)."
             )
 
     # ----- composition ---------------------------------------------------
@@ -204,10 +230,7 @@ class Assistant:
         persona = self.persona
 
         for skill in self.skills:
-            block = (
-                f"## Skill: {skill.name}\n"
-                f"{skill.description}\n\n{skill.instructions}".rstrip()
-            )
+            block = f"## Skill: {skill.name}\n{skill.description}\n\n{skill.instructions}".rstrip()
             persona = persona.extend(block)
 
         # Push merged variables back so render() (called by AsyncAgent)
@@ -275,19 +298,52 @@ class Assistant:
 
     # ----- LLM backend ---------------------------------------------------
 
+    def build_async_agent(self, **vars: Any) -> Any:
+        """Construct the underlying ``AsyncAgent`` (or ``AsyncDeepAgent``).
+
+        Use this when you want the Assistant as a *configuration* bundle
+        (persona + skills + tools + model + options) but need to drive
+        the underlying agent yourself — through a group, a streaming
+        callback machinery, or any other orchestration layer that
+        operates on :class:`AsyncAgent` directly.
+
+        Args:
+            **vars: Per-call template variables merged into the persona
+                before rendering.  Equivalent to the per-call kwargs of
+                :meth:`arun` / :meth:`astream`, but applied at
+                construction time.
+
+        Returns:
+            An :class:`AsyncAgent` when ``enable_planning=False``,
+            otherwise an :class:`AsyncDeepAgent`.
+
+        Raises:
+            ValueError: When this Assistant is configured with a
+                ``coding_agent`` backend (it shells out to a CLI and has
+                no in-process agent to expose).
+        """
+        if self.coding_agent:
+            raise ValueError(
+                "build_async_agent() is only available for the LLM backend; "
+                f"this Assistant uses coding_agent={self.coding_agent!r}."
+            )
+        return self._build_async_agent(call_vars=vars)
+
     def _build_async_agent(self, *, call_vars: dict[str, Any]) -> Any:
         persona = self._composed_persona(call_vars)
+        tools_arg = self._tools_for_agent()
         if self.enable_planning:
             from .async_deep_agent import AsyncDeepAgent
 
             return AsyncDeepAgent(
                 self.model or "",
                 system_prompt=persona,
-                tools=list(self.tools) or None,
+                tools=tools_arg,
                 name=self.name,
                 description=self.description,
                 enable_planning=True,
                 options=dict(self.options) or None,
+                **dict(self.deep_agent_options),
             )
 
         from .async_agent import AsyncAgent
@@ -295,13 +351,30 @@ class Assistant:
         return AsyncAgent(
             self.model or "",
             system_prompt=persona,
-            tools=list(self.tools) or None,
+            tools=tools_arg,
             output_type=self.output_type,
+            output_key=self.output_key,
             name=self.name,
             description=self.description,
             options=dict(self.options) or None,
+            **dict(self.agent_options),
         )
 
+    def _tools_for_agent(self) -> Any:
+        """Coerce ``self.tools`` into the shape ``AsyncAgent`` expects.
+
+        Returns ``None`` when nothing is configured, the underlying
+        ``ToolRegistry`` when one was passed in directly, or a list of
+        callables otherwise.
+        """
+        if not self.tools:
+            return None
+        # Tuples / lists of callables → list (AsyncAgent expects a list).
+        if isinstance(self.tools, tuple):
+            return list(self.tools) or None
+        # Any other object (e.g. ToolRegistry) is passed through verbatim.
+        return self.tools
+
     async def _run_llm(
         self,
         prompt: str,
@@ -429,9 +502,7 @@ def clear_assistant_registry() -> None:
 def _from_registry(cls: type[Assistant], name: str) -> Assistant:
     found = get_assistant(name)
     if found is None:
-        raise KeyError(
-            f"No Assistant registered as {name!r}. Known: {get_assistant_names()}"
-        )
+        raise KeyError(f"No Assistant registered as {name!r}. Known: {get_assistant_names()}")
     return found
 
 

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture/agents/review_loop.py

@@ -50,8 +50,8 @@ from __future__ import annotations
 
 import dataclasses
 import logging
-from collections.abc import Callable
-from typing import Any, Protocol, runtime_checkable
+from collections.abc import AsyncIterator, Callable
+from typing import Any, Literal, Protocol, runtime_checkable
 
 logger = logging.getLogger("prompture.review_loop")
 
@@ -96,6 +96,53 @@ class ReviewLoopIteration:
     review_result: Any = None
 
 
+ReviewLoopEventType = Literal[
+    "iteration_started",
+    "coder_done",
+    "reviewer_done",
+    "approved",
+    "rejected",
+    "done",
+]
+
+
+@dataclasses.dataclass(frozen=True)
+class ReviewLoopEvent:
+    """Event yielded by :meth:`AsyncReviewLoop.astream`.
+
+    Field meaning per ``type``:
+
+    * ``iteration_started`` — emitted before each coder run.  ``index``
+      is the 0-based iteration number; ``prompt`` is the exact text the
+      coder will receive (for the first iteration this is the user
+      prompt; for later iterations it is ``feedback_prompt(...)``
+      output).
+    * ``coder_done`` — coder finished.  ``code_output`` populated;
+      ``code_result`` carries the raw coder return value (e.g.
+      :class:`AssistantResult` or :class:`AgentResult`) for backend-
+      specific fields like cost.
+    * ``reviewer_done`` — reviewer finished.  ``review_output`` +
+      ``review_result`` populated; ``approved`` reflects the
+      ``approve_when`` verdict for this iteration.
+    * ``approved`` — terminal: the loop is about to exit because the
+      latest iteration was approved.
+    * ``rejected`` — terminal: the loop is about to exit because
+      ``max_iters`` was hit without approval.
+    * ``done`` — emitted last, always.  ``result`` carries the same
+      :class:`ReviewLoopResult` that :meth:`arun` would return.
+    """
+
+    type: ReviewLoopEventType
+    index: int = -1  # iteration index; -1 for the terminal "done" event
+    prompt: str = ""  # only on iteration_started
+    code_output: str = ""  # populated from coder_done onwards
+    review_output: str = ""  # populated from reviewer_done onwards
+    approved: bool = False
+    code_result: Any = None
+    review_result: Any = None
+    result: Any = None  # only on the final "done" event
+
+
 @dataclasses.dataclass(frozen=True)
 class ReviewLoopResult:
     """Final result returned by :meth:`AsyncReviewLoop.arun`."""
@@ -167,9 +214,7 @@ class AsyncReviewLoop:
     review_prompt: Callable[[str], str] = dataclasses.field(
         default=lambda code: f"Review this work and give feedback:\n\n{code}"
     )
-    feedback_prompt: Callable[[str, ReviewLoopIteration], str] = (
-        _default_feedback_prompt
-    )
+    feedback_prompt: Callable[[str, ReviewLoopIteration], str] = _default_feedback_prompt
 
     def __post_init__(self) -> None:
         if self.max_iters < 1:
@@ -182,7 +227,10 @@ class AsyncReviewLoop:
         coder_kwargs: dict[str, Any] | None = None,
         reviewer_kwargs: dict[str, Any] | None = None,
     ) -> ReviewLoopResult:
-        """Run the loop to completion.
+        """Run the loop to completion and return the final result.
+
+        Equivalent to consuming :meth:`astream` and returning its final
+        ``done`` event's ``result``.
 
         Args:
             prompt: The initial task for the coder.
@@ -191,21 +239,69 @@ class AsyncReviewLoop:
             reviewer_kwargs: Extra kwargs forwarded to every
                 ``reviewer.arun`` call.
         """
+        final: ReviewLoopResult | None = None
+        async for event in self.astream(
+            prompt,
+            coder_kwargs=coder_kwargs,
+            reviewer_kwargs=reviewer_kwargs,
+        ):
+            if event.type == "done":
+                final = event.result
+        assert final is not None  # astream always emits a done event
+        return final
+
+    async def astream(
+        self,
+        prompt: str,
+        *,
+        coder_kwargs: dict[str, Any] | None = None,
+        reviewer_kwargs: dict[str, Any] | None = None,
+    ) -> AsyncIterator[ReviewLoopEvent]:
+        """Run the loop and yield :class:`ReviewLoopEvent` events live.
+
+        The sequence per iteration is:
+        ``iteration_started`` → ``coder_done`` → ``reviewer_done``.
+        After the final iteration, ``approved`` or ``rejected`` fires,
+        followed by a single ``done`` event carrying the full
+        :class:`ReviewLoopResult`.
+
+        UI consumers can re-emit each event onto their own transport
+        (WebSocket, SSE, log line) without buffering the whole run.
+        """
         coder_kwargs = coder_kwargs or {}
         reviewer_kwargs = reviewer_kwargs or {}
         history: list[ReviewLoopIteration] = []
         current_prompt = prompt
 
         for i in range(self.max_iters):
+            yield ReviewLoopEvent(
+                type="iteration_started",
+                index=i,
+                prompt=current_prompt,
+            )
+
             code_result = await self.coder.arun(current_prompt, **coder_kwargs)
             code_text = getattr(code_result, "output", "") or ""
-
-            review_result = await self.reviewer.arun(
-                self.review_prompt(code_text), **reviewer_kwargs
+            yield ReviewLoopEvent(
+                type="coder_done",
+                index=i,
+                code_output=code_text,
+                code_result=code_result,
             )
-            review_text = getattr(review_result, "output", "") or ""
 
+            review_result = await self.reviewer.arun(self.review_prompt(code_text), **reviewer_kwargs)
+            review_text = getattr(review_result, "output", "") or ""
             approved = bool(self.approve_when(review_result))
+            yield ReviewLoopEvent(
+                type="reviewer_done",
+                index=i,
+                code_output=code_text,
+                review_output=review_text,
+                approved=approved,
+                code_result=code_result,
+                review_result=review_result,
+            )
+
             iteration = ReviewLoopIteration(
                 index=i,
                 code_output=code_text,
@@ -227,16 +323,38 @@ class AsyncReviewLoop:
             current_prompt = self.feedback_prompt(prompt, iteration)
 
         last = history[-1]
-        return ReviewLoopResult(
+        result = ReviewLoopResult(
             output=last.code_output,
             approved=last.approved,
             iterations=len(history),
             history=tuple(history),
         )
 
+        yield ReviewLoopEvent(
+            type="approved" if result.approved else "rejected",
+            index=last.index,
+            code_output=result.output,
+            review_output=last.review_output,
+            approved=result.approved,
+            code_result=last.code_result,
+            review_result=last.review_result,
+        )
+        yield ReviewLoopEvent(
+            type="done",
+            index=last.index,
+            code_output=result.output,
+            review_output=last.review_output,
+            approved=result.approved,
+            code_result=last.code_result,
+            review_result=last.review_result,
+            result=result,
+        )
+
 
 __all__ = [
     "AsyncReviewLoop",
+    "ReviewLoopEvent",
+    "ReviewLoopEventType",
     "ReviewLoopIteration",
     "ReviewLoopResult",
 ]

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture/infra/coding_agent_events.py

@@ -251,10 +251,10 @@ _QUESTION_PHRASE_RE = re.compile(
 
 _CHOICE_LINE_RE = re.compile(
     r"^\s*(?:"
-    r"(?P<num>\d+)[.\):]\s+|"     # 1. foo  1) foo  1: foo
-    r"[-*•]\s+|"                  # - foo   * foo   • foo
-    r"\([a-zA-Z]\)\s+|"           # (a) foo
-    r"[a-zA-Z][.\)]\s+"           # a) foo  a. foo
+    r"(?P<num>\d+)[.\):]\s+|"  # 1. foo  1) foo  1: foo
+    r"[-*•]\s+|"  # - foo   * foo   • foo
+    r"\([a-zA-Z]\)\s+|"  # (a) foo
+    r"[a-zA-Z][.\)]\s+"  # a) foo  a. foo
     r")(?P<body>.+\S)\s*$"
 )
 

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture/infra/coding_agents.py

@@ -55,6 +55,7 @@ def _record_into_session(
     }
     session.record(response_info)
 
+
 CodingAgentId = str
 ApprovalMode = Literal["default", "auto", "yolo"]
 OutputFormat = Literal["text", "json"]

{prompture-1.1.3.dev3 → prompture-1.1.4.dev2}/prompture.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.1.3.dev3
+Version: 1.1.4.dev2
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT