induscode 0.1.0__py3-none-any.whl

induscode/briefing/compose.py

@@ -0,0 +1,414 @@
+"""Briefing composer — the declarative system-prompt pipeline.
+
+The system prompt is assembled from an ordered list of
+:class:`~induscode.briefing.contract.BriefingSection` descriptors, not a string
+template with ``{{TOKEN}}`` holes. Each section decides for itself whether it
+contributes to a given :class:`~induscode.briefing.contract.BriefingContext`
+(its ``applies`` predicate) and renders its own fragment (its ``render``). The
+composer is a small reducer: it walks the recipe in order, keeps the
+applicable sections, renders them, drops empties, and joins with blank-line
+gaps. Adding, removing, or reordering a section is a data edit to
+:data:`BRIEFING_SECTIONS`, never a change to the composer.
+
+Every guideline, tool note, and heading below is authored for this rebuild
+(the prose is copied verbatim from the TS ``src/briefing/compose.ts``). The
+*set* of sections (role, tools, working guidance, task tracking, delegates,
+connectors, project context, skills, footer) follows the well-known coding-
+agent shape; the wording is the briefing's own.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime, timezone
+from typing import Final, Mapping
+
+from .contract import (
+    AgentTool,
+    Briefing,
+    BriefingContext,
+    BriefingInputs,
+    BriefingSection,
+)
+
+__all__ = [
+    "BRIEFING_SECTIONS",
+    "compose_briefing",
+]
+
+
+# ---------------------------------------------------------------------------
+# Small render helpers
+# ---------------------------------------------------------------------------
+
+
+def _join_blocks(parts: Sequence[str]) -> str:
+    """Join non-empty fragments with a blank line between them."""
+    return "\n\n".join(p for p in parts if p.strip())
+
+
+def _bullets(lines: Sequence[str]) -> str:
+    """Render a markdown bullet list from already-formatted line bodies."""
+    return "\n".join(f"- {line}" for line in lines)
+
+
+def _escape_xml(value: str) -> str:
+    """Escape the five XML metacharacters for the skills block's tag values."""
+    out = ""
+    for ch in value:
+        if ch == "&":
+            out += "&"
+        elif ch == "<":
+            out += "&lt;"
+        elif ch == ">":
+            out += "&gt;"
+        elif ch == '"':
+            out += "&quot;"
+        elif ch == "'":
+            out += "&#39;"
+        else:
+            out += ch
+    return out
+
+
+def _has_tool(ctx: BriefingContext, tool_id: str) -> bool:
+    """True when the context advertises a tool whose name matches ``tool_id``."""
+    return any(t.name == tool_id for t in ctx.tools or ())
+
+
+def _has_tool_prefix(ctx: BriefingContext, prefix: str) -> bool:
+    """True when the context advertises any tool whose name begins with
+    ``prefix``."""
+    return any(t.name.startswith(prefix) for t in ctx.tools or ())
+
+
+def _iso_utc(moment: datetime) -> str:
+    """Format a timestamp the way the TS footer did (``Date.toISOString()``):
+    UTC, millisecond precision, trailing ``Z``. A naive datetime is treated as
+    already-UTC."""
+    if moment.tzinfo is not None:
+        moment = moment.astimezone(timezone.utc)
+    return moment.strftime("%Y-%m-%dT%H:%M:%S.") + f"{moment.microsecond // 1000:03d}Z"
+
+
+# ---------------------------------------------------------------------------
+# Tool descriptions (re-authored one-liners)
+# ---------------------------------------------------------------------------
+
+#: One-line summaries for the built-in tools, keyed by tool name. The briefing
+#: surfaces the summary for each advertised tool that has one; tools without
+#: an entry fall back to their own ``description`` from the
+#: :class:`~induscode.briefing.contract.AgentTool` record.
+#:
+#: The phrasing here is the briefing's own.
+TOOL_SUMMARIES: Final[Mapping[str, str]] = {
+    "read": "Open a file's contents for inspection.",
+    "write": "Create a new file or overwrite an existing one wholesale.",
+    "edit": "Apply a precise in-place change by matching exact existing text.",
+    "bash": "Run a shell command in the workspace.",
+    "grep": "Search file contents by pattern across the tree.",
+    "find": "Locate files and directories by name or glob.",
+    "ls": "List the entries of a directory.",
+    "task": "Hand a self-contained sub-task to a delegate agent.",
+    "todoread": "Read back the current task checklist.",
+    "todowrite": "Record or revise the task checklist.",
+    "webfetch": "Retrieve and read the contents of a URL.",
+    "websearch": "Query the web for current information.",
+}
+
+
+def _describe_tool(tool: AgentTool) -> str:
+    """Render a single tool's advertised line: name + best available summary."""
+    summary = TOOL_SUMMARIES.get(tool.name)
+    if summary is None:
+        description = getattr(tool, "description", None)
+        summary = description.strip() if isinstance(description, str) else ""
+    return f"`{tool.name}` — {summary}" if summary else f"`{tool.name}`"
+
+
+# ---------------------------------------------------------------------------
+# Sections
+# ---------------------------------------------------------------------------
+
+
+def _render_role(_ctx: BriefingContext) -> str:
+    return _join_blocks(
+        [
+            "You are a terminal-based software engineering assistant. You operate inside a real workspace and make progress by reading code, running commands, and editing files directly — not by describing what someone else should do.",
+            "Work toward the user's actual goal. Take the initiative to gather the context you need, but stay within the scope of what was asked: do not redesign, rename, or refactor beyond the request unless the user invites it.",
+        ]
+    )
+
+
+#: Role / setup. Always present. Establishes the agent's purpose and the
+#: stance the rest of the briefing assumes.
+ROLE_SECTION: Final[BriefingSection] = BriefingSection(id="role", render=_render_role)
+
+
+def _tools_applies(ctx: BriefingContext) -> bool:
+    return len(ctx.tools or ()) > 0
+
+
+def _render_tools(ctx: BriefingContext) -> str:
+    lines = [_describe_tool(t) for t in ctx.tools or ()]
+    return _join_blocks(
+        [
+            "# Tools",
+            "These capabilities are available to you this turn. Reach for the most specific one for the job.",
+            _bullets(lines),
+        ]
+    )
+
+
+#: Available tools. Renders only when the context advertises at least one
+#: tool. Lists each advertised tool with its re-authored one-liner.
+TOOLS_SECTION: Final[BriefingSection] = BriefingSection(
+    id="tools", title="Tools", applies=_tools_applies, render=_render_tools
+)
+
+
+def _render_guidelines(ctx: BriefingContext) -> str:
+    items: list[str] = []
+
+    if _has_tool(ctx, "read"):
+        items.append(
+            "Always inspect a file with the reader before you change it. Do not shell out to `cat`, `head`, or `sed` to view a file when the reader is available."
+        )
+    if _has_tool(ctx, "edit"):
+        items.append(
+            "For a targeted change, prefer the editor: it replaces an exact span of existing text, so the old text you supply must match the file byte-for-byte."
+        )
+    if _has_tool(ctx, "write"):
+        items.append(
+            "Reserve the writer for creating a new file or replacing one in full; for anything smaller, edit in place rather than rewriting the whole file."
+        )
+    if _has_tool(ctx, "grep") or _has_tool(ctx, "find") or _has_tool(ctx, "ls"):
+        items.append(
+            "Explore the tree with the dedicated search and listing tools rather than shell equivalents — they are quicker and already skip ignored paths."
+        )
+    if _has_tool(ctx, "bash"):
+        items.append(
+            "Use the shell for builds, tests, and other commands that no purpose-built tool covers. Keep commands scoped and avoid destructive operations unless the user asked for them."
+        )
+
+    items.append(
+        "Keep your replies short and to the point. Lead with the result; add only the explanation the user needs to act on it."
+    )
+    items.append(
+        "When a change is non-trivial, verify it — run the build or the relevant tests — before you report it as done."
+    )
+
+    return _join_blocks(["# Working guidance", _bullets(items)])
+
+
+#: Working guidance. The behavioral guidelines — every sentence authored
+#: fresh. Each guideline is gated on the relevant tool being present so the
+#: briefing never instructs the model to use a capability it was not given.
+GUIDELINES_SECTION: Final[BriefingSection] = BriefingSection(
+    id="guidelines", title="Working guidance", render=_render_guidelines
+)
+
+
+def _tasks_applies(ctx: BriefingContext) -> bool:
+    return _has_tool(ctx, "todowrite") or _has_tool(ctx, "todoread")
+
+
+def _render_tasks(_ctx: BriefingContext) -> str:
+    return _join_blocks(
+        [
+            "# Task tracking",
+            "For work that spans several steps, maintain a checklist with the task tools. Break the job into concrete items, mark exactly one in progress at a time, and tick items off as you finish them so the user can follow along.",
+        ]
+    )
+
+
+#: Task tracking. Present when a todo tool is advertised. Explains how the
+#: model should keep the shared checklist current.
+TASK_SECTION: Final[BriefingSection] = BriefingSection(
+    id="tasks", title="Task tracking", applies=_tasks_applies, render=_render_tasks
+)
+
+
+def _subagents_applies(ctx: BriefingContext) -> bool:
+    return len(ctx.subagents or ()) > 0
+
+
+def _render_subagents(ctx: BriefingContext) -> str:
+    lines = []
+    for s in ctx.subagents or ():
+        when = f" Use it when {s.when}" if s.when else ""
+        lines.append(f"**{s.name}** — {s.purpose}.{when}")
+    return _join_blocks(
+        [
+            "# Delegates",
+            "You can offload a focused, self-contained piece of work to one of these delegates with the task tool. Hand off when a sub-problem is well-scoped enough to be solved without your full conversation context.",
+            _bullets(lines),
+        ]
+    )
+
+
+#: Delegates / subagents. Present when the context lists delegate roles.
+#: Renders each role the primary agent may hand work to.
+SUBAGENTS_SECTION: Final[BriefingSection] = BriefingSection(
+    id="subagents", title="Delegates", applies=_subagents_applies, render=_render_subagents
+)
+
+
+def _connectors_applies(ctx: BriefingContext) -> bool:
+    return _has_tool_prefix(ctx, "connector_") or _has_tool_prefix(ctx, "saas_")
+
+
+def _render_connectors(_ctx: BriefingContext) -> str:
+    return _join_blocks(
+        [
+            "# Connectors",
+            _bullets(
+                [
+                    "When a task needs an external service (issue trackers, calendars, docs, and the like), prefer the connector tools over scraping or guessing.",
+                    "Confirm the connection is authorized before you rely on it, and surface a clear next step if it is not.",
+                    "Page through large result sets deliberately rather than assuming the first response is complete.",
+                ]
+            ),
+        ]
+    )
+
+
+#: Connector guidance. Present when SaaS-connector tools (prefixed) are
+#: advertised. Authored fresh; no carried-over vendor prose.
+CONNECTORS_SECTION: Final[BriefingSection] = BriefingSection(
+    id="connectors", title="Connectors", applies=_connectors_applies, render=_render_connectors
+)
+
+
+def _project_context_applies(ctx: BriefingContext) -> bool:
+    return len(ctx.context_docs or ()) > 0
+
+
+def _render_project_context(ctx: BriefingContext) -> str:
+    docs = [f"## {d.path}\n\n{d.body.strip()}" for d in ctx.context_docs or ()]
+    return _join_blocks(
+        [
+            "# Project context",
+            "The following project documents describe conventions for this repository. Treat them as standing instructions.",
+            *docs,
+        ]
+    )
+
+
+#: Project context. Present when the context carries project documents.
+#: Inlines each under its own sub-heading so repository conventions are in
+#: view.
+PROJECT_CONTEXT_SECTION: Final[BriefingSection] = BriefingSection(
+    id="project-context",
+    title="Project context",
+    applies=_project_context_applies,
+    render=_render_project_context,
+)
+
+
+def _skills_applies(ctx: BriefingContext) -> bool:
+    return len(ctx.skills or ()) > 0
+
+
+def _render_skills(ctx: BriefingContext) -> str:
+    entries = []
+    for card in ctx.skills or ():
+        entries.append(
+            "\n".join(
+                [
+                    "  <skill>",
+                    f"    <name>{_escape_xml(card.name)}</name>",
+                    f"    <description>{_escape_xml(card.description)}</description>",
+                    f"    <location>{_escape_xml(card.location)}</location>",
+                    "  </skill>",
+                ]
+            )
+        )
+    joined = "\n".join(entries)
+    return _join_blocks(
+        [
+            "# Skills",
+            "Each skill below is a set of task-specific instructions stored on disk. When a task lines up with a skill's description, load its file with the reader and follow it. Paths a skill mentions are relative to that skill's own directory.",
+            f"<available_skills>\n{joined}\n</available_skills>",
+        ]
+    )
+
+
+#: Skills block. Present when the context carries model-invocable cards.
+#: Renders the cards into an ``<available_skills>`` block (the format's shape)
+#: with a re-authored lead-in.
+SKILLS_SECTION: Final[BriefingSection] = BriefingSection(
+    id="skills", title="Skills", applies=_skills_applies, render=_render_skills
+)
+
+
+def _render_footer(ctx: BriefingContext) -> str:
+    where = ctx.cwd if ctx.cwd is not None else ctx.workspace
+    when = _iso_utc(ctx.now if ctx.now is not None else datetime.now(timezone.utc))
+    lines: list[str] = []
+    if where:
+        lines.append(f"Working directory: {where}")
+    lines.append(f"Current time: {when}")
+    return "\n".join(lines)
+
+
+#: Footer. Always present. Stamps the working directory and the current time
+#: so the model has its bearings.
+FOOTER_SECTION: Final[BriefingSection] = BriefingSection(id="footer", render=_render_footer)
+
+
+#: The default briefing recipe, in render order. Swap or reorder entries to
+#: reshape the prompt without touching :func:`compose_briefing`.
+BRIEFING_SECTIONS: Final[Briefing] = (
+    ROLE_SECTION,
+    TOOLS_SECTION,
+    GUIDELINES_SECTION,
+    TASK_SECTION,
+    SUBAGENTS_SECTION,
+    CONNECTORS_SECTION,
+    PROJECT_CONTEXT_SECTION,
+    SKILLS_SECTION,
+    FOOTER_SECTION,
+)
+
+
+# ---------------------------------------------------------------------------
+# Composer
+# ---------------------------------------------------------------------------
+
+
+def compose_briefing(value: BriefingContext | BriefingInputs) -> str:
+    """Fold a section recipe and a context into the final briefing string.
+
+    Accepts either a plain :class:`~induscode.briefing.contract.BriefingContext`
+    (using the default :data:`BRIEFING_SECTIONS` recipe) or a full
+    :class:`~induscode.briefing.contract.BriefingInputs` bundle that names its
+    own sections and optional ``prelude`` / ``append`` text. The composer
+    keeps each section whose ``applies`` predicate is satisfied (or absent),
+    renders it, discards empty fragments, and joins the rest with blank-line
+    gaps. Optional ``prelude`` and ``append`` bracket the rendered sections.
+
+    :param value: either the render context, or a full inputs bundle
+    :returns: the assembled system-prompt string
+    """
+    inputs = (
+        value
+        if isinstance(value, BriefingInputs)
+        else BriefingInputs(sections=BRIEFING_SECTIONS, context=value)
+    )
+
+    rendered: list[str] = []
+    if inputs.prelude is not None and inputs.prelude.strip():
+        rendered.append(inputs.prelude.strip())
+
+    for section in inputs.sections:
+        if section.applies is not None and not section.applies(inputs.context):
+            continue
+        fragment = section.render(inputs.context)
+        if fragment.strip():
+            rendered.append(fragment.strip())
+
+    if inputs.append is not None and inputs.append.strip():
+        rendered.append(inputs.append.strip())
+
+    return _join_blocks(rendered)