agentforge-py 0.2.1__py3-none-any.whl

agentforge/pipeline/tool.py

@@ -0,0 +1,93 @@
+"""`pipeline_findings` — the built-in tool that surfaces a Pipeline's
+output back to the LLM (feat-015).
+
+The agent wires one `PipelineFindingsTool` instance into its tool set
+whenever `Agent(pipeline=...)` is set. Before each `Agent.run()`, the
+agent stashes the freshly produced findings on the tool via
+``_set_cache(...)``. The LLM can then call ``pipeline_findings()``
+with optional ``category`` / ``severity`` filters to retrieve them as
+JSON-friendly dicts.
+
+Returning serialized dicts (via ``model_dump(mode="json")`` when
+available, else ``to_dict()``) keeps the contract tolerant of
+non-Pydantic Finding shapes — see ``agentforge_core.contracts.finding``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentforge_core.contracts.tool import Tool
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PipelineFindingsInput(BaseModel):
+    """Filter parameters for `pipeline_findings`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    category: str | None = Field(
+        default=None,
+        description="If set, return only findings whose `category` matches.",
+    )
+    severity: str | None = Field(
+        default=None,
+        description="If set, return only findings whose `severity` matches.",
+    )
+
+
+class PipelineFindingsTool(Tool):
+    """Built-in tool that lets the LLM re-query pipeline output.
+
+    The agent caches the latest `PipelineResult.findings` on this
+    instance at the start of every `Agent.run()`. The tool's `run()`
+    filters the cache and returns serializable dicts.
+    """
+
+    name = "pipeline_findings"
+    description = (
+        "List the findings produced by this agent's deterministic pipeline. "
+        "Optional filters: `category` (e.g. 'lint', 'coverage') and `severity` "
+        "(e.g. 'error', 'warning', 'info'). Returns a list of dicts."
+    )
+    input_schema = PipelineFindingsInput
+
+    def __init__(self) -> None:
+        self._cached_findings: list[Any] = []
+
+    def _set_cache(self, findings: list[Any]) -> None:
+        """Replace the cached findings (called by `Agent.run()`)."""
+        self._cached_findings = list(findings)
+
+    async def run(self, **kwargs: Any) -> list[dict[str, Any]]:
+        params = PipelineFindingsInput.model_validate(kwargs)
+        out: list[dict[str, Any]] = []
+        for f in self._cached_findings:
+            if params.category is not None and getattr(f, "category", None) != params.category:
+                continue
+            if params.severity is not None and getattr(f, "severity", None) != params.severity:
+                continue
+            out.append(_serialise_finding(f))
+        return out
+
+
+def _serialise_finding(f: Any) -> dict[str, Any]:
+    dump = getattr(f, "model_dump", None)
+    if callable(dump):
+        result = dump(mode="json")
+        if isinstance(result, dict):
+            return result
+    to_dict = getattr(f, "to_dict", None)
+    if callable(to_dict):
+        result = to_dict()
+        if isinstance(result, dict):
+            return result
+    # Best-effort fallback for arbitrary Finding-shaped objects.
+    return {
+        "severity": getattr(f, "severity", None),
+        "category": getattr(f, "category", None),
+        "message": getattr(f, "message", None),
+    }
+
+
+__all__ = ["PipelineFindingsInput", "PipelineFindingsTool"]

agentforge/recording.py

@@ -0,0 +1,189 @@
+"""Run-recording hooks (feat-017).
+
+Records every emitted `Step` and the final `RunResult` to a configured
+`MemoryStore` so `agentforge run --replay <run-id>` and `agentforge
+debug --replay <run-id>` can reconstruct a run deterministically.
+
+Layout in the store (reserved categories):
+
+- `category="__step"` — one claim per `Step`, payload carries every
+  field on the frozen model so the step can be re-instantiated.
+- `category="__eval"` — one claim per `EvalResult` from the run.
+- `category="__run"` — one claim per run carrying the run-level
+  summary (output, cost, tokens, duration, finish_reason).
+
+The hook is opt-in: pass `Agent(record_runs=memory)` (or use
+`agentforge run --record` from the CLI). Errors are isolated by
+`Agent`'s existing `_safe_call_hook` wrapper — recording will never
+break a run.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.production.run_context import current_run
+from agentforge_core.values.claim import Claim
+
+if TYPE_CHECKING:
+    from agentforge_core.values.pipeline import PipelineResult
+    from agentforge_core.values.state import RunResult, Step
+
+# Public category names. Tests, CLI, and external tooling can rely on
+# these — they are part of the v0.1 on-disk contract.
+STEP_CATEGORY = "__step"
+EVAL_CATEGORY = "__eval"
+RUN_CATEGORY = "__run"
+PIPELINE_CATEGORY = "__pipeline"
+
+
+class RecordRunHook:
+    """Builds hooks that persist run telemetry to a `MemoryStore`.
+
+    Single hook object exposes `.on_step` and `.on_finish` callables
+    that `Agent` installs alongside any user-supplied hooks.
+    """
+
+    def __init__(
+        self,
+        *,
+        memory: MemoryStore,
+        project: str,
+        agent_name: str,
+    ) -> None:
+        self._memory = memory
+        self._project = project
+        self._agent_name = agent_name
+
+    async def on_step(self, step: Step) -> None:
+        try:
+            run_id = current_run().run_id
+        except RuntimeError:
+            # Outside Agent.run(); fall back to a sentinel so the
+            # claim still persists. Tests that call the hook directly
+            # exercise this branch.
+            run_id = "unknown"
+        await self._memory.put(
+            Claim(
+                run_id=run_id,
+                project=self._project,
+                agent=self._agent_name,
+                category=STEP_CATEGORY,
+                payload=_step_payload(step),
+            )
+        )
+
+    async def on_finish(self, result: RunResult) -> None:
+        await self._memory.put(
+            Claim(
+                run_id=result.run_id,
+                project=self._project,
+                agent=self._agent_name,
+                category=RUN_CATEGORY,
+                payload={
+                    "output": _serializable(result.output),
+                    "cost_usd": result.cost_usd,
+                    "tokens_in": result.tokens_in,
+                    "tokens_out": result.tokens_out,
+                    "duration_ms": result.duration_ms,
+                    "finish_reason": result.finish_reason,
+                    "metadata": dict(result.metadata),
+                },
+            )
+        )
+        for eval_result in result.eval_scores:
+            await self._memory.put(
+                Claim(
+                    run_id=result.run_id,
+                    project=self._project,
+                    agent=self._agent_name,
+                    category=EVAL_CATEGORY,
+                    payload=eval_result.model_dump(mode="json"),
+                )
+            )
+
+
+def _step_payload(step: Step) -> dict[str, Any]:
+    """Serialize a `Step` into a JSON-safe dict for storage."""
+    return {
+        "iteration": step.iteration,
+        "kind": step.kind,
+        "content": _serializable(step.content),
+        "tool_call": step.tool_call.model_dump(mode="json") if step.tool_call else None,
+        "tokens_in": step.tokens_in,
+        "tokens_out": step.tokens_out,
+        "cost_usd": step.cost_usd,
+        "duration_ms": step.duration_ms,
+        "timestamp": step.timestamp.isoformat(),
+        "metadata": dict(step.metadata),
+    }
+
+
+def _serializable(value: Any) -> Any:
+    """Pass-through for dicts/lists/scalars; coerce others to str."""
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    if isinstance(value, dict):
+        return {str(k): _serializable(v) for k, v in value.items()}
+    if isinstance(value, list | tuple):
+        return [_serializable(v) for v in value]
+    return str(value)
+
+
+async def record_pipeline_result(
+    *,
+    memory: MemoryStore,
+    run_id: str,
+    project: str,
+    agent_name: str,
+    result: PipelineResult,
+) -> None:
+    """Persist a `PipelineResult` as one ``__pipeline`` claim.
+
+    Replay reads this back and threads it into `Agent.run`'s
+    ``replay_pipeline`` kwarg so the deterministic tasks don't
+    re-execute (side-effect-bearing tasks would double-run).
+    """
+    await memory.put(
+        Claim(
+            run_id=run_id,
+            project=project,
+            agent=agent_name,
+            category=PIPELINE_CATEGORY,
+            payload={
+                "findings": [_finding_payload(f) for f in result.findings],
+                "task_durations_ms": dict(result.task_durations_ms),
+                "task_failures": dict(result.task_failures),
+                "total_cost_usd": result.total_cost_usd,
+            },
+        )
+    )
+
+
+def _finding_payload(f: Any) -> dict[str, Any]:
+    dump = getattr(f, "model_dump", None)
+    if callable(dump):
+        result = dump(mode="json")
+        if isinstance(result, dict):
+            return result
+    to_dict = getattr(f, "to_dict", None)
+    if callable(to_dict):
+        result = to_dict()
+        if isinstance(result, dict):
+            return result
+    return {
+        "severity": getattr(f, "severity", None),
+        "category": getattr(f, "category", None),
+        "message": getattr(f, "message", None),
+    }
+
+
+__all__ = [
+    "EVAL_CATEGORY",
+    "PIPELINE_CATEGORY",
+    "RUN_CATEGORY",
+    "STEP_CATEGORY",
+    "RecordRunHook",
+    "record_pipeline_result",
+]

agentforge/renderers/__init__.py

@@ -0,0 +1,28 @@
+"""Renderer registry + built-in renderers for `Finding` variants (feat-008).
+
+`RendererRegistry` maps a `Finding` instance to a `FindingRenderer`
+using isinstance-based dispatch with a most-specific-wins rule. The
+four built-in renderers (shipped in chunk 3) handle the four shipped
+variants.
+
+A `default()` factory returns a pre-populated registry — the common
+case for agent code. Custom agents register additional renderers for
+their own variants.
+"""
+
+from __future__ import annotations
+
+from agentforge.renderers.markdown import MarkdownRenderer
+from agentforge.renderers.patch_applier import PatchApplierRenderer
+from agentforge.renderers.registry import MissingRendererError, RendererRegistry
+from agentforge.renderers.scorecard import ScorecardRenderer
+from agentforge.renderers.span_table import SpanTableRenderer
+
+__all__ = [
+    "MarkdownRenderer",
+    "MissingRendererError",
+    "PatchApplierRenderer",
+    "RendererRegistry",
+    "ScorecardRenderer",
+    "SpanTableRenderer",
+]

agentforge/renderers/_defaults.py

@@ -0,0 +1,32 @@
+"""Pre-population helper for `RendererRegistry.default()` (feat-008).
+
+Kept in a separate module so `registry.py` can lazy-import it inside
+`default()` and avoid a top-level cycle between the registry and the
+concrete renderer modules (which themselves import the variants from
+`agentforge.findings`).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentforge.findings import MultiSpanFinding, NarrativeFinding, PatchFinding, SimpleFinding
+from agentforge.renderers.markdown import MarkdownRenderer
+from agentforge.renderers.patch_applier import PatchApplierRenderer
+from agentforge.renderers.scorecard import ScorecardRenderer
+from agentforge.renderers.span_table import SpanTableRenderer
+
+if TYPE_CHECKING:
+    from agentforge.renderers.registry import RendererRegistry
+
+
+def populate_defaults(registry: RendererRegistry) -> None:
+    """Register the four built-in renderers on `registry`.
+
+    Idempotent — re-registering the same exact type replaces the
+    prior entry (see `RendererRegistry.register`).
+    """
+    registry.register(SimpleFinding, ScorecardRenderer())
+    registry.register(PatchFinding, PatchApplierRenderer())
+    registry.register(NarrativeFinding, MarkdownRenderer())
+    registry.register(MultiSpanFinding, SpanTableRenderer())

agentforge/renderers/markdown.py

@@ -0,0 +1,44 @@
+"""`MarkdownRenderer` — narrative rendering for `NarrativeFinding`.
+
+text format: question (message) + body + "References:" footer.
+markdown format: heading + body + "## References" section with a list.
+"""
+
+from __future__ import annotations
+
+from agentforge_core.contracts.finding import Finding
+from agentforge_core.contracts.renderer import FindingRenderer
+
+from agentforge.findings import NarrativeFinding
+
+_SUPPORTED_FORMATS = frozenset({"text", "markdown"})
+
+
+class MarkdownRenderer(FindingRenderer):
+    """Renders `NarrativeFinding` as prose with citations."""
+
+    def render(self, finding: Finding, format: str = "text") -> str:
+        if format not in _SUPPORTED_FORMATS:
+            raise ValueError(
+                f"MarkdownRenderer supports {sorted(_SUPPORTED_FORMATS)}; got {format!r}"
+            )
+        if not isinstance(finding, NarrativeFinding):
+            raise TypeError(
+                f"MarkdownRenderer renders NarrativeFinding; got {type(finding).__name__}"
+            )
+
+        if format == "markdown":
+            heading = f"## {finding.message}"
+            refs_section = ""
+            if finding.references:
+                refs_lines = "\n".join(f"- {r}" for r in finding.references)
+                refs_section = f"\n\n### References\n\n{refs_lines}"
+            return f"{heading}\n\n{finding.body}{refs_section}"
+
+        refs_section = ""
+        if finding.references:
+            refs_section = "\n\nReferences:\n" + "\n".join(f"  - {r}" for r in finding.references)
+        return f"{finding.message}\n\n{finding.body}{refs_section}"
+
+    def supports(self, finding_type: type) -> bool:
+        return issubclass(finding_type, NarrativeFinding)

agentforge/renderers/patch_applier.py

@@ -0,0 +1,46 @@
+"""`PatchApplierRenderer` — diff rendering for `PatchFinding`.
+
+text format: header line + unified-diff body.
+markdown format: same content wrapped in a fenced ` ```diff ` block.
+
+The renderer does NOT apply the patch — that's the caller's
+responsibility. The name reflects the typical downstream use, not what
+this class does.
+"""
+
+from __future__ import annotations
+
+from agentforge_core.contracts.finding import Finding
+from agentforge_core.contracts.renderer import FindingRenderer
+
+from agentforge.findings import PatchFinding
+
+_SUPPORTED_FORMATS = frozenset({"text", "markdown"})
+
+
+class PatchApplierRenderer(FindingRenderer):
+    """Renders `PatchFinding` as a unified diff (plain or fenced)."""
+
+    def render(self, finding: Finding, format: str = "text") -> str:
+        if format not in _SUPPORTED_FORMATS:
+            raise ValueError(
+                f"PatchApplierRenderer supports {sorted(_SUPPORTED_FORMATS)}; got {format!r}"
+            )
+        if not isinstance(finding, PatchFinding):
+            raise TypeError(
+                f"PatchApplierRenderer renders PatchFinding; got {type(finding).__name__}"
+            )
+
+        header = (
+            f"[{finding.severity}] {finding.category}: {finding.message}\n"
+            f"file: {finding.patch.file}  (confidence={finding.confidence:.2f})\n"
+            f"rationale: {finding.rationale}"
+        )
+
+        diff_body = finding.patch.diff.rstrip("\n")
+        if format == "markdown":
+            return f"{header}\n\n```diff\n{diff_body}\n```"
+        return f"{header}\n\n{diff_body}"
+
+    def supports(self, finding_type: type) -> bool:
+        return issubclass(finding_type, PatchFinding)

agentforge/renderers/registry.py

@@ -0,0 +1,108 @@
+"""`RendererRegistry` — isinstance-based dispatch for `FindingRenderer`s.
+
+Registration maps a `Finding` (sub)type to a renderer. Lookup walks
+the registrations and returns the renderer whose registered type is
+the **most specific** (most-derived) ancestor of the finding's type.
+
+Ties broken by registration order (first wins) — predictable and
+documented. The most-specific rule matches the spec's intent for
+custom variants subclassing a shipped variant: registering a renderer
+for the subclass overrides the parent renderer.
+"""
+
+from __future__ import annotations
+
+from agentforge_core.contracts.finding import Finding
+from agentforge_core.contracts.renderer import FindingRenderer
+
+from agentforge.renderers._defaults import populate_defaults
+
+
+class MissingRendererError(LookupError):
+    """Raised by `RendererRegistry.get` when no renderer matches."""
+
+
+class RendererRegistry:
+    """Map `Finding` (sub)types to `FindingRenderer`s.
+
+    Use `register(finding_type, renderer)` to add an entry. Use
+    `get(finding)` to dispatch — returns the most-specific match.
+    `default()` returns a registry pre-populated with the four
+    built-in renderers shipped for the standard variants.
+    """
+
+    def __init__(self) -> None:
+        # List preserves registration order; `dict[type, renderer]`
+        # would lose duplicates and registration order is part of the
+        # tie-break rule.
+        self._registrations: list[tuple[type, FindingRenderer]] = []
+
+    def register(self, finding_type: type, renderer: FindingRenderer) -> None:
+        """Register `renderer` for findings of type `finding_type` or
+        any subclass.
+
+        Re-registering the same exact type replaces the prior
+        registration in place (preserves the original registration
+        order).
+        """
+        for idx, (existing_type, _) in enumerate(self._registrations):
+            if existing_type is finding_type:
+                self._registrations[idx] = (finding_type, renderer)
+                return
+        self._registrations.append((finding_type, renderer))
+
+    def get(self, finding: Finding) -> FindingRenderer:
+        """Look up the most-specific renderer for `finding`.
+
+        Iterates registrations and selects the one whose registered
+        type is the most-derived ancestor of `type(finding)`. Ties
+        are broken by registration order (first wins).
+
+        Raises:
+            MissingRendererError: if no registered type matches.
+        """
+        best: tuple[type, FindingRenderer] | None = None
+        finding_type = type(finding)
+        for registered_type, renderer in self._registrations:
+            if not isinstance(finding, registered_type):
+                continue
+            if best is None or _is_more_specific(registered_type, best[0], finding_type):
+                best = (registered_type, renderer)
+        if best is None:
+            raise MissingRendererError(
+                f"No renderer registered for {finding_type.__name__!r}. "
+                f"Use RendererRegistry.register({finding_type.__name__}, …) or call "
+                f"RendererRegistry.default() to get a pre-populated registry."
+            )
+        return best[1]
+
+    def registered_types(self) -> tuple[type, ...]:
+        """Diagnostic: types currently registered, in registration order."""
+        return tuple(t for t, _ in self._registrations)
+
+    @classmethod
+    def default(cls) -> RendererRegistry:
+        """Return a registry pre-populated with the four built-in renderers.
+
+        Maps `SimpleFinding` → `ScorecardRenderer`, `PatchFinding` →
+        `PatchApplierRenderer`, `NarrativeFinding` → `MarkdownRenderer`,
+        `MultiSpanFinding` → `SpanTableRenderer`. Agents can register
+        more variants on top, or replace any of these in place.
+        """
+        registry = cls()
+        populate_defaults(registry)
+        return registry
+
+
+def _is_more_specific(candidate: type, current_best: type, target: type) -> bool:
+    """Is `candidate` a more-specific ancestor of `target` than
+    `current_best`? Both `candidate` and `current_best` are guaranteed
+    to be ancestors of `target` at this point.
+
+    "More specific" means: candidate is a proper subclass of
+    current_best. If candidate == current_best, that's a tie — the
+    first registration wins, so we report False (not strictly more
+    specific).
+    """
+    del target  # only relied on by callers for the ancestor invariant
+    return candidate is not current_best and issubclass(candidate, current_best)

agentforge/renderers/scorecard.py

@@ -0,0 +1,59 @@
+"""`ScorecardRenderer` — text/markdown rendering for `SimpleFinding`.
+
+text format: `[severity] category: message (file:line) — recommendation`.
+markdown format: a single GFM table row (header is the caller's job).
+"""
+
+from __future__ import annotations
+
+from agentforge_core.contracts.finding import Finding
+from agentforge_core.contracts.renderer import FindingRenderer
+
+from agentforge.findings import SimpleFinding
+
+_SUPPORTED_FORMATS = frozenset({"text", "markdown"})
+
+
+class ScorecardRenderer(FindingRenderer):
+    """Renders `SimpleFinding` as a severity-tagged line or table row."""
+
+    def render(self, finding: Finding, format: str = "text") -> str:
+        if format not in _SUPPORTED_FORMATS:
+            raise ValueError(
+                f"ScorecardRenderer supports {sorted(_SUPPORTED_FORMATS)}; got {format!r}"
+            )
+        if not isinstance(finding, SimpleFinding):
+            raise TypeError(
+                f"ScorecardRenderer renders SimpleFinding; got {type(finding).__name__}"
+            )
+
+        if format == "markdown":
+            return self._render_markdown(finding)
+        return self._render_text(finding)
+
+    def supports(self, finding_type: type) -> bool:
+        return issubclass(finding_type, SimpleFinding)
+
+    @staticmethod
+    def _render_text(finding: SimpleFinding) -> str:
+        location = ""
+        if finding.file:
+            location = f" ({finding.file}"
+            if finding.line is not None:
+                location += f":{finding.line}"
+            location += ")"
+        trailer = f" — {finding.recommendation}" if finding.recommendation else ""
+        rule = f" [{finding.rule_id}]" if finding.rule_id else ""
+        return (
+            f"[{finding.severity}]{rule} {finding.category}: {finding.message}{location}{trailer}"
+        )
+
+    @staticmethod
+    def _render_markdown(finding: SimpleFinding) -> str:
+        location = finding.file
+        if finding.file and finding.line is not None:
+            location = f"{finding.file}:{finding.line}"
+        return (
+            f"| {finding.severity} | {finding.category} | "
+            f"{finding.message} | {location} | {finding.recommendation} |"
+        )

agentforge/renderers/span_table.py

@@ -0,0 +1,71 @@
+"""`SpanTableRenderer` — multi-span rendering for `MultiSpanFinding`.
+
+text format: header + one block per span (`file:start-end  excerpt`).
+markdown format: header + GFM table (file | lines | excerpt).
+"""
+
+from __future__ import annotations
+
+from agentforge_core.contracts.finding import Finding
+from agentforge_core.contracts.renderer import FindingRenderer
+
+from agentforge.findings import MultiSpanFinding, Span
+
+_SUPPORTED_FORMATS = frozenset({"text", "markdown"})
+
+
+class SpanTableRenderer(FindingRenderer):
+    """Renders `MultiSpanFinding` as a per-span block (text) or table (md)."""
+
+    def render(self, finding: Finding, format: str = "text") -> str:
+        if format not in _SUPPORTED_FORMATS:
+            raise ValueError(
+                f"SpanTableRenderer supports {sorted(_SUPPORTED_FORMATS)}; got {format!r}"
+            )
+        if not isinstance(finding, MultiSpanFinding):
+            raise TypeError(
+                f"SpanTableRenderer renders MultiSpanFinding; got {type(finding).__name__}"
+            )
+
+        header = f"[{finding.severity}] {finding.category}: {finding.message}"
+
+        if format == "markdown":
+            rows = "\n".join(self._md_row(s) for s in finding.spans)
+            table = "| file | lines | excerpt |\n|---|---|---|\n" + rows
+            footer = (
+                f"\n\n**Recommendation:** {finding.recommendation}"
+                if finding.recommendation
+                else ""
+            )
+            return (
+                f"## {finding.message}\n\n"
+                f"severity: `{finding.severity}` — "
+                f"category: `{finding.category}`\n\n"
+                f"{table}{footer}"
+            )
+
+        blocks = "\n".join(self._text_block(s) for s in finding.spans)
+        footer = f"\n\nrecommendation: {finding.recommendation}" if finding.recommendation else ""
+        return f"{header}\n\n{blocks}{footer}"
+
+    def supports(self, finding_type: type) -> bool:
+        return issubclass(finding_type, MultiSpanFinding)
+
+    @staticmethod
+    def _text_block(span: Span) -> str:
+        location = f"{span.file}:{span.start_line}"
+        if span.end_line != span.start_line:
+            location = f"{span.file}:{span.start_line}-{span.end_line}"
+        excerpt = f"\n    {span.excerpt}" if span.excerpt else ""
+        return f"  - {location}{excerpt}"
+
+    @staticmethod
+    def _md_row(span: Span) -> str:
+        lines = (
+            str(span.start_line)
+            if span.start_line == span.end_line
+            else f"{span.start_line}-{span.end_line}"
+        )
+        # Escape pipes in excerpts so we don't break the table.
+        excerpt = span.excerpt.replace("|", "\\|")
+        return f"| `{span.file}` | {lines} | `{excerpt}` |"