briar-cli 1.1.1__py3-none-any.whl

briar/extract/pr_archaeology.py

@@ -0,0 +1,131 @@
+"""Mine the merged-PR history of one or more repos.
+
+Surfaces the patterns + reviewer cadence agents should respect when
+proposing changes. Modeled on
+`claude-standalone/scans/pr_archaeology.py` condensed to a live agent
+context blob (heavy duplicate-PR clustering is deferred to v2).
+
+Provider-agnostic: this extractor talks to a `RepositoryProvider`,
+not to GitHub directly. Setting ``--provider bitbucket`` in the
+runbook routes the same logic onto Bitbucket Cloud once
+`BitbucketProvider.list_pulls` is implemented."""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+from datetime import datetime
+from statistics import median
+from typing import Any, Dict, List
+
+from briar.extract._provider import PullRequest
+from briar.extract._user_filter import (
+    add_user_filter_arguments,
+    apply_user_filter_objs,
+)
+from briar.extract.base import EMPTY_SECTION, ExtractedSection, RepoBackedExtractor
+
+
+class ExtractPrArchaeology(RepoBackedExtractor):
+    UNPARSABLE_HOURS = -1.0
+
+    @classmethod
+    def _hours_between(cls, start_iso: str, end_iso: str) -> float:
+        """Hours between two ISO-8601 timestamps. Returns `-1.0` on a
+        parse error — callers filter that out before averaging."""
+        try:
+            s = datetime.fromisoformat(start_iso.replace("Z", "+00:00"))
+            e = datetime.fromisoformat(end_iso.replace("Z", "+00:00"))
+        except ValueError:
+            return cls.UNPARSABLE_HOURS
+        return (e - s).total_seconds() / 3600.0
+
+    name = "pr-archaeology"
+    description = "merged-PR patterns, review focus, reviewer profiles"
+    requires_github = True  # legacy flag — kept for back-compat; new gate is requires_repository_provider
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--pr-repo",
+            action="append",
+            default=[],
+            help="Repository slug to mine (e.g. owner/repo). Repeatable.",
+        )
+        parser.add_argument(
+            "--pr-max",
+            type=int,
+            default=100,
+            help="Max merged PRs per repo (default: 100)",
+        )
+        add_user_filter_arguments(parser, prefix="pr")
+
+    def is_available(self, args: argparse.Namespace) -> bool:
+        if not args.pr_repo:
+            return False
+        try:
+            provider = self._provider(args)
+        except Exception:  # noqa: BLE001
+            return False
+        return provider.is_available()
+
+    def extract(self, args: argparse.Namespace) -> ExtractedSection:
+        provider = self._provider(args)
+        per_repo: List[ExtractedSection] = []
+        for repo in args.pr_repo:
+            section = self._mine_repo(repo, args.pr_max, args, provider)
+            if not section.is_empty:
+                per_repo.append(section)
+        if not per_repo:
+            return EMPTY_SECTION
+        return ExtractedSection(
+            title=f"PR archaeology — {len(per_repo)} repo(s)",
+            body=(
+                "Patterns from the most recent merged PRs. Agents should "
+                "match the established conventions (review focus, file "
+                "paths touched most, reviewer cadence)."
+            ),
+            subsections=per_repo,
+        )
+
+    def _mine_repo(
+        self,
+        repo: str,
+        max_prs: int,
+        args: argparse.Namespace,
+        provider,
+    ) -> ExtractedSection:
+        merged: List[PullRequest] = provider.list_pulls(repo, state="merged", max_count=max_prs)
+        merged = apply_user_filter_objs(merged, args, prefix="pr")
+        if not merged:
+            return EMPTY_SECTION
+
+        cycle_hours = [h for h in (self._hours_between(p.created_at, p.merged_at) for p in merged) if h >= 0]
+        reviewers: Counter = Counter()
+        authors: Counter = Counter()
+        for p in merged:
+            authors[p.author or "?"] += 1
+            for r in p.requested_reviewers:
+                reviewers[r or "?"] += 1
+
+        data: Dict[str, Any] = {
+            "repo": repo,
+            "merged_pr_count": len(merged),
+            "median_cycle_hours": (round(median(cycle_hours), 2) if cycle_hours else None),
+            "top_authors": authors.most_common(5),
+            "top_reviewers": reviewers.most_common(5),
+        }
+        body_lines = [f"- merged PR sample: **{data['merged_pr_count']}**"]
+        if data["median_cycle_hours"] is not None:
+            body_lines.append(f"- median time-to-merge: **{data['median_cycle_hours']}h**")
+        if data["top_authors"]:
+            top = ", ".join(f"{u}({n})" for u, n in data["top_authors"])
+            body_lines.append(f"- top authors: {top}")
+        if data["top_reviewers"]:
+            top = ", ".join(f"{u}({n})" for u, n in data["top_reviewers"])
+            body_lines.append(f"- requested reviewers: {top}")
+        return ExtractedSection(
+            title=repo,
+            body="\n".join(body_lines),
+            data=data,
+        )

briar/extract/pr_review_context.py

@@ -0,0 +1,123 @@
+"""Task-scoped: fetch full review context for ONE PR.
+
+Invoked by `briar agent` when the operator passes a specific PR
+number. Output is spliced into that single agent run's system prompt
+so the pr-fixer archetype can see:
+
+  - the PR's metadata (title, branches, draft status)
+  - every comment thread (resolved + unresolved, inline + top-level)
+  - failing CI steps with a log tail per failure
+
+That's what the agent actually needs to address review feedback —
+the scheduled `active-work` extractor only surfaces metadata."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import List
+
+from briar.extract._provider import CiFailure, ReviewComment
+from briar.extract.base import EMPTY_SECTION, ExtractedSection, TaskScopedRepoExtractor
+
+
+log = logging.getLogger(__name__)
+
+
+class FetchPrReviewContext(TaskScopedRepoExtractor):
+    name = "pr-review-context"
+    description = "Full review context (comments + CI failures) for ONE specific PR"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--pr-target-repo",
+            required=True,
+            help="Repository slug (`owner/repo` for GitHub, `workspace/slug` for Bitbucket)",
+        )
+        parser.add_argument(
+            "--pr-target-number",
+            type=int,
+            required=True,
+            help="PR number to fetch context for",
+        )
+
+    def fetch(self, args: argparse.Namespace) -> ExtractedSection:
+        provider = self._provider(args)
+        repo = args.pr_target_repo
+        number = args.pr_target_number
+
+        pr = provider.get_pull(repo, number)
+        # Adapter's `@swallow_errors(default=None)` returns None on any
+        # provider-side failure. The boundary that translates None →
+        # EMPTY_SECTION lives at this caller, not inside the decorator.
+        if pr is None or (not pr.title and not pr.head_ref):
+            log.warning("pr-review-context: PR %s#%d not found", repo, number)
+            return EMPTY_SECTION
+
+        comments: List[ReviewComment] = provider.list_pr_comments(repo, number)
+        failures: List[CiFailure] = provider.list_ci_failures(repo, number)
+
+        body_parts: List[str] = [
+            f"**PR**: {repo}#{number}",
+            f"**Title**: {pr.title}",
+            f"**Author**: {pr.author or '(unknown)'}",
+            f"**Branch**: {pr.head_ref} → {pr.base_ref}",
+        ]
+        if pr.is_draft:
+            body_parts.append("**Status**: DRAFT")
+        if pr.requested_reviewers:
+            body_parts.append(f"**Reviewers**: {', '.join(pr.requested_reviewers)}")
+
+        # CI failures first — usually higher priority than comments.
+        if failures:
+            body_parts.append("")
+            body_parts.append(f"### Failing CI ({len(failures)})")
+            body_parts.append("")
+            for f in failures:
+                body_parts.append(f"**{f.workflow} → {f.job} → {f.step}**")
+                if f.url:
+                    body_parts.append(f"_{f.url}_")
+                if f.log_tail:
+                    body_parts.append("```")
+                    body_parts.append(f.log_tail)
+                    body_parts.append("```")
+                body_parts.append("")
+
+        if comments:
+            inline = [c for c in comments if c.file_path]
+            top_level = [c for c in comments if not c.file_path]
+
+            if inline:
+                body_parts.append(f"### Inline review comments ({len(inline)})")
+                body_parts.append("")
+                for c in inline[:30]:
+                    body_parts.append(f"**{c.author}** on `{c.file_path}:{c.line}`:")
+                    body_parts.append(c.body)
+                    body_parts.append("")
+                if len(inline) > 30:
+                    body_parts.append(f"_…and {len(inline) - 30} more inline comments_")
+
+            if top_level:
+                body_parts.append(f"### PR-level comments ({len(top_level)})")
+                body_parts.append("")
+                for c in top_level[:15]:
+                    body_parts.append(f"**{c.author}** ({c.created_at}):")
+                    body_parts.append(c.body)
+                    body_parts.append("")
+
+        if not failures and not comments:
+            body_parts.append("")
+            body_parts.append("_No failing CI and no review comments — PR may already be ready to merge._")
+
+        return ExtractedSection(
+            title=f"PR review context — {repo}#{number}: {pr.title[:60]}",
+            body="\n".join(body_parts),
+            data={
+                "pr_number": pr.number,
+                "title": pr.title,
+                "author": pr.author,
+                "comment_count": len(comments),
+                "failing_ci_count": len(failures),
+            },
+        )

briar/extract/reviewer_profile.py

@@ -0,0 +1,141 @@
+"""Mine each top-reviewer's review behaviour per repo.
+
+Surfaces patterns the engineer/pr-fixer archetypes should match:
+which reviewers leave the most comments, what files they touch, the
+typical request volume per PR. Lets an agent calibrate "how much
+review depth does this reviewer expect" instead of guessing.
+
+Provider-agnostic: same RepositoryProvider contract as
+pr-archaeology. Falls back gracefully on providers that don't expose
+review comments via the `list_pr_comments` verb."""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter, defaultdict
+from typing import Any, Dict, List
+
+from briar.extract._provider import PullRequest, ReviewComment
+from briar.extract.base import EMPTY_SECTION, ExtractedSection, RepoBackedExtractor
+
+
+class ExtractReviewerProfile(RepoBackedExtractor):
+    name = "reviewer-profile"
+    description = "per-reviewer comment cadence, file hotspots, common asks"
+    requires_github = True  # legacy flag
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--reviewer-repo",
+            action="append",
+            default=[],
+            help="Repository slug to profile reviewers for. Repeatable.",
+        )
+        parser.add_argument(
+            "--reviewer-pr-sample",
+            type=int,
+            default=20,
+            help="How many recent merged PRs to sample per repo (default: 20)",
+        )
+        parser.add_argument(
+            "--reviewer-top-n",
+            type=int,
+            default=5,
+            help="How many top reviewers to profile (default: 5)",
+        )
+
+    def is_available(self, args: argparse.Namespace) -> bool:
+        if not args.reviewer_repo:
+            return False
+        try:
+            provider = self._provider(args)
+        except Exception:  # noqa: BLE001
+            return False
+        return provider.is_available()
+
+    def extract(self, args: argparse.Namespace) -> ExtractedSection:
+        provider = self._provider(args)
+        per_repo: List[ExtractedSection] = []
+        for repo in args.reviewer_repo:
+            section = self._profile_repo(repo, args, provider)
+            if not section.is_empty:
+                per_repo.append(section)
+        if not per_repo:
+            return EMPTY_SECTION
+        return ExtractedSection(
+            title=f"Reviewer profiles — {len(per_repo)} repo(s)",
+            body=(
+                "Per-reviewer behaviour mined from recent merged PRs. "
+                "Agents should match the bar of the most-likely reviewer "
+                "for the touched files — not the project median."
+            ),
+            subsections=per_repo,
+        )
+
+    def _profile_repo(self, repo: str, args: argparse.Namespace, provider) -> ExtractedSection:
+        sample = provider.list_pulls(repo, state="merged", max_count=args.reviewer_pr_sample)
+        if not sample:
+            return EMPTY_SECTION
+
+        # Aggregate: per-reviewer, total comments + which files they
+        # commented on + sample of their actual comment bodies.
+        per_reviewer_comments: Dict[str, int] = Counter()
+        per_reviewer_files: Dict[str, Counter] = defaultdict(Counter)
+        per_reviewer_samples: Dict[str, List[str]] = defaultdict(list)
+        prs_reviewed: Dict[str, int] = Counter()
+
+        for pr in sample:
+            comments: List[ReviewComment] = provider.list_pr_comments(repo, pr.number)
+            reviewers_on_this_pr: set = set()
+            for c in comments:
+                if not c.author or c.author == pr.author:
+                    continue  # skip self-comments
+                per_reviewer_comments[c.author] += 1
+                if c.file_path:
+                    per_reviewer_files[c.author][c.file_path] += 1
+                # Keep a short sample of actual comment text per reviewer.
+                if len(per_reviewer_samples[c.author]) < 3 and len(c.body) > 20:
+                    per_reviewer_samples[c.author].append(c.body[:200])
+                reviewers_on_this_pr.add(c.author)
+            for r in reviewers_on_this_pr:
+                prs_reviewed[r] += 1
+
+        if not per_reviewer_comments:
+            return EMPTY_SECTION
+
+        top_reviewers = per_reviewer_comments.most_common(args.reviewer_top_n)
+        body_parts: List[str] = [
+            f"Sample: {len(sample)} merged PRs",
+            f"Active reviewers: {len(per_reviewer_comments)}",
+            "",
+        ]
+        data_rows: List[Dict[str, Any]] = []
+        for reviewer, total_comments in top_reviewers:
+            prs = prs_reviewed.get(reviewer, 0)
+            avg_per_pr = round(total_comments / prs, 1) if prs else 0.0
+            top_files = [path for path, _ in per_reviewer_files[reviewer].most_common(3)]
+            body_parts.append(f"### {reviewer}")
+            body_parts.append(f"- PRs reviewed: **{prs}** / comments left: **{total_comments}** (avg **{avg_per_pr}**/PR)")
+            if top_files:
+                body_parts.append(f"- Hot files: {', '.join(top_files)}")
+            samples = per_reviewer_samples.get(reviewer, [])
+            if samples:
+                body_parts.append(f"- Sample asks (truncated):")
+                for s in samples:
+                    body_parts.append(f"  - _{s}_")
+            body_parts.append("")
+            data_rows.append(
+                {
+                    "reviewer": reviewer,
+                    "prs_reviewed": prs,
+                    "comments": total_comments,
+                    "avg_comments_per_pr": avg_per_pr,
+                    "top_files": top_files,
+                }
+            )
+        return ExtractedSection(
+            title=repo,
+            body="\n".join(body_parts),
+            data={"reviewers": data_rows, "pr_sample_size": len(sample)},
+        )

briar/extract/ticket_archaeology.py

@@ -0,0 +1,115 @@
+"""Mine the closed-ticket history of one or more projects.
+
+Symmetric to `pr-archaeology`. Surfaces: median time-to-close, top
+reporters/assignees, label distribution. Helps agents match the
+project's established triage cadence + categorisation."""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+from datetime import datetime
+from statistics import median
+from typing import Any, Dict, List
+
+from briar.extract._tracker import Ticket
+from briar.extract.base import EMPTY_SECTION, ExtractedSection, TrackerBackedExtractor
+
+
+class ExtractTicketArchaeology(TrackerBackedExtractor):
+    UNPARSABLE_HOURS = -1.0
+
+    name = "ticket-archaeology"
+    description = "closed-ticket patterns, assignee + label cadence"
+
+    @classmethod
+    def _hours_between(cls, start_iso: str, end_iso: str) -> float:
+        try:
+            s = datetime.fromisoformat(start_iso.replace("Z", "+00:00"))
+            e = datetime.fromisoformat(end_iso.replace("Z", "+00:00"))
+        except ValueError:
+            return cls.UNPARSABLE_HOURS
+        return (e - s).total_seconds() / 3600.0
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--ticket-archaeology-project",
+            action="append",
+            default=[],
+            help="Tracker project key to mine. Repeatable.",
+        )
+        parser.add_argument(
+            "--ticket-max",
+            type=int,
+            default=100,
+            help="Max closed tickets per project (default: 100)",
+        )
+
+    def is_available(self, args: argparse.Namespace) -> bool:
+        if not args.ticket_archaeology_project:
+            return False
+        try:
+            tracker = self._tracker(args)
+        except Exception:  # noqa: BLE001
+            return False
+        return tracker.is_available()
+
+    def extract(self, args: argparse.Namespace) -> ExtractedSection:
+        tracker = self._tracker(args)
+        per_project: List[ExtractedSection] = []
+        for project in args.ticket_archaeology_project:
+            section = self._mine_project(project, args.ticket_max, tracker)
+            if not section.is_empty:
+                per_project.append(section)
+        if not per_project:
+            return EMPTY_SECTION
+        return ExtractedSection(
+            title=f"Ticket archaeology — {len(per_project)} project(s)",
+            body=("Patterns from the most recent closed tickets. Agents " "should match the project's triage + labelling conventions."),
+            subsections=per_project,
+        )
+
+    def _mine_project(self, project: str, max_tickets: int, tracker) -> ExtractedSection:
+        tickets: List[Ticket] = tracker.list_tickets(project, state="closed", max_count=max_tickets)
+        if not tickets:
+            return EMPTY_SECTION
+
+        cycle_hours = [h for h in (self._hours_between(t.created_at, t.updated_at) for t in tickets) if h >= 0]
+        reporters: Counter = Counter()
+        assignees: Counter = Counter()
+        labels: Counter = Counter()
+        kinds: Counter = Counter()
+        for t in tickets:
+            reporters[t.reporter or "?"] += 1
+            assignees[t.assignee or "?"] += 1
+            kinds[t.kind or "?"] += 1
+            for lbl in t.labels:
+                labels[lbl] += 1
+
+        data: Dict[str, Any] = {
+            "project": project,
+            "closed_ticket_count": len(tickets),
+            "median_close_hours": (round(median(cycle_hours), 2) if cycle_hours else None),
+            "top_reporters": reporters.most_common(5),
+            "top_assignees": assignees.most_common(5),
+            "top_labels": labels.most_common(5),
+            "kinds": kinds.most_common(5),
+        }
+        body_lines = [f"- closed ticket sample: **{data['closed_ticket_count']}**"]
+        if data["median_close_hours"] is not None:
+            body_lines.append(f"- median time-to-close: **{data['median_close_hours']}h**")
+        for label, items in (
+            ("top reporters", data["top_reporters"]),
+            ("top assignees", data["top_assignees"]),
+            ("top labels", data["top_labels"]),
+            ("kinds", data["kinds"]),
+        ):
+            if items:
+                joined = ", ".join(f"{u}({n})" for u, n in items)
+                body_lines.append(f"- {label}: {joined}")
+        return ExtractedSection(
+            title=project,
+            body="\n".join(body_lines),
+            data=data,
+        )

briar/extract/ticket_context.py

@@ -0,0 +1,95 @@
+"""Task-scoped: fetch full body, ACs, and comments for ONE ticket.
+
+Invoked by `briar agent` when the operator passes a specific ticket
+key. Output is spliced into that single agent run's system prompt —
+it does NOT go into the per-company knowledge blob.
+
+The agent uses this section to anchor its plan against the actual
+ticket description rather than just the title + assignee summary
+that the scheduled `active-tickets` extractor surfaces."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import List
+
+from briar.extract._tracker import Comment
+from briar.extract.base import EMPTY_SECTION, ExtractedSection, TaskScopedTrackerExtractor
+
+
+log = logging.getLogger(__name__)
+
+
+class FetchTicketContext(TaskScopedTrackerExtractor):
+    name = "ticket-context"
+    description = "Full body + ACs + comments for ONE specific ticket"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--ticket-project",
+            required=True,
+            help="Tracker project key (Jira: PROJ; Linear team: ENG; "
+            "GH Issues: owner/repo; BB Issues: workspace/repo)",
+        )
+        parser.add_argument(
+            "--ticket-key",
+            required=True,
+            help="Ticket identifier (Jira: PROJ-123; GH/BB: #42; Linear: ENG-7)",
+        )
+
+    def fetch(self, args: argparse.Namespace) -> ExtractedSection:
+        tracker = self._tracker(args)
+        ticket = tracker.get_ticket(args.ticket_project, args.ticket_key)
+        # `swallow_errors(default=None)` on the provider verb means the
+        # adapter returns None on any failure (auth, network, missing
+        # ticket). The decorator is the right contract for the adapter —
+        # the boundary that converts None → EMPTY_SECTION lives here.
+        if ticket is None or (not ticket.title and not ticket.description):
+            log.warning("ticket-context: %s not found or empty", args.ticket_key)
+            return EMPTY_SECTION
+
+        comments: List[Comment] = tracker.list_comments(args.ticket_project, args.ticket_key)
+        transitions = tracker.list_status_transitions(args.ticket_project, args.ticket_key)
+
+        body_parts: List[str] = [
+            f"**Key**: {ticket.key}",
+            f"**Status**: {ticket.status}",
+        ]
+        if ticket.kind:
+            body_parts.append(f"**Type**: {ticket.kind}")
+        if ticket.priority:
+            body_parts.append(f"**Priority**: {ticket.priority}")
+        body_parts.append(f"**Reporter**: {ticket.reporter or '(unset)'}")
+        body_parts.append(f"**Assignee**: {ticket.assignee or '(unset)'}")
+        if ticket.labels:
+            body_parts.append(f"**Labels**: {', '.join(ticket.labels)}")
+        if transitions:
+            body_parts.append(f"**Status history**: {' → '.join(transitions)}")
+        body_parts.append("")
+        body_parts.append("### Description")
+        body_parts.append("")
+        body_parts.append(ticket.description or "_(no description)_")
+        if comments:
+            body_parts.append("")
+            body_parts.append(f"### Comments ({len(comments)})")
+            body_parts.append("")
+            for c in comments[:20]:
+                body_parts.append(f"**{c.author}** ({c.created_at}):")
+                body_parts.append(c.body)
+                body_parts.append("")
+            if len(comments) > 20:
+                body_parts.append(f"_…and {len(comments) - 20} more (older); fetch with --max-comments to see all_")
+
+        return ExtractedSection(
+            title=f"Ticket context — {ticket.key}: {ticket.title}",
+            body="\n".join(body_parts),
+            data={
+                "key": ticket.key,
+                "title": ticket.title,
+                "status": ticket.status,
+                "labels": ticket.labels,
+                "comment_count": len(comments),
+            },
+        )

briar/formatting/__init__.py

@@ -0,0 +1,67 @@
+"""Output formatters (Strategy + Registry).
+
+Adding a new format = one `Formatter` subclass + one entry in
+`FormatterRegistry.FORMATTERS`. Nothing else changes."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from briar.formatting.base import Formatter
+from briar.formatting.csv import FormatCsv
+from briar.formatting.json import FormatJson
+from briar.formatting.quiet import FormatQuiet
+from briar.formatting.table import FormatTable
+from briar.formatting.yaml import FormatYaml
+
+
+class FormatterRegistry:
+    """Strategy lookup + entry points. Static methods only — there is
+    no instance state worth carrying."""
+
+    FORMATTERS: Dict[str, Formatter] = {
+        "table": FormatTable(),
+        "json": FormatJson(),
+        "yaml": FormatYaml(),
+        "csv": FormatCsv(),
+        "quiet": FormatQuiet(),
+    }
+
+    @classmethod
+    def names(cls) -> List[str]:
+        return list(cls.FORMATTERS.keys())
+
+    @classmethod
+    def get(cls, format_name: str) -> Formatter:
+        return cls.FORMATTERS.get(format_name) or cls.FORMATTERS["table"]
+
+    @classmethod
+    def render(
+        cls,
+        payload: Any,
+        format_name: str,
+        columns: List[str] = [],
+    ) -> None:
+        cls.get(format_name).render(payload, columns)
+
+    @classmethod
+    def render_object(cls, payload: Any, format_name: str) -> None:
+        """Single-record path: `table` falls through to JSON because a
+        one-row table is just JSON with line noise."""
+        effective = "json" if format_name == "table" else format_name
+        cls.render(payload, effective)
+
+
+# Module-level callables — keep the existing import surface stable.
+FORMATTERS = FormatterRegistry.FORMATTERS
+render = FormatterRegistry.render
+render_object = FormatterRegistry.render_object
+
+
+__all__ = [
+    "Formatter",
+    "FormatterRegistry",
+    "FORMATTERS",
+    "render",
+    "render_object",
+]