tool_prompt.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/tool_prompt.py
 
"""
Compact tool-map renderer for the system prompt — plan 135 (§3.3).
 
Purpose
-------
Render a one-line-per-tool routing table from the live (mode-filtered) tool
schemas, replacing the ~21 KB embedded JSON-Schema dump + the hand-maintained
quick-reference card in ``messages[0]``. The authoritative, machine-readable
JSON Schema for every tool still travels via the provider's API ``tools``
parameter; this map is only the human/LLM-readable routing aid.
 
Responsibilities
----------------
- :func:`compact_tool_map` — pure function: schemas → Markdown table (one row
  per tool, sorted, deterministic), ``*`` marking required params, ``[confirm]``
  marking confirmation-gated tools, Markdown pipes escaped, ending with a stable
  sentinel so re-attach logic can detect presence.
 
Diagnostics
-----------
Domain: OC_CHAT.PROMPT
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Pure: no I/O, no global state; deterministic for a given schema list.
- Empty ``schemas`` → ``""`` (never raises).
- Tolerates the OpenAI ``{"type":"function","function":{…}}`` wrapper and the
  flat ``{"name":…,"parameters":…}`` shape.
- The compact-map sentinel is the LAST line of the returned block.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import re
from typing import Any
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.PROMPT", "tool_prompt", "module", 4)
 
#: Stable presence marker; ``ensure_system_includes_tool_reference`` keys on it.
COMPACT_TOOL_MAP_SENTINEL = "<!--oc:compact-tool-map:v1-->"
 
#: Tools whose confirmation gate is not expressed as a ``confirmed`` parameter.
#: Add a name here only if a gated tool lacks the ``confirmed`` arg (§3.3); do
#: not silently drop the marker. Empty today (``run_command`` self-declares).
_GATED_TOOLS: frozenset[str] = frozenset()
 
_PIPE_RE = re.compile(r"(?<!\\)\|")  # unescaped pipe only — never double-escape
 
 
def _one_line(text: str, limit: int) -> str:
    """First sentence of *text*, whitespace-collapsed, capped at *limit* chars."""
    text = " ".join((text or "").split())
    if not text:
        return ""
    for end in (". ", "? ", "! "):
        i = text.find(end)
        if 0 < i <= limit:
            return text[: i + 1].rstrip()
    if len(text) <= limit:
        return text
    head = text[:limit]
    if " " in head:  # drop the partial trailing word — no mid-word break
        head = head.rsplit(" ", 1)[0]
    return head.rstrip() + " …"
 
 
def _escape_cell(text: str) -> str:
    """Collapse whitespace and escape unescaped Markdown table pipes (no double-escape)."""
    return _PIPE_RE.sub(r"\|", " ".join((text or "").split()))
 
 
def _params(fn: dict[str, Any]) -> str:
    """``required*`` params first, then optional; ``-`` when the tool takes none."""
    params = fn.get("parameters") or {}
    props = params.get("properties") or {}
    required = set(params.get("required") or [])
    if not props:
        return "-"
    ordered = [p for p in props if p in required] + [p for p in props if p not in required]
    return ", ".join(p + ("*" if p in required else "") for p in ordered)
 
 
def _is_gated(name: str, fn: dict[str, Any]) -> bool:
    """True when *fn* is confirmation-gated (``confirmed`` param or in the gated set)."""
    props = (fn.get("parameters") or {}).get("properties") or {}
    return "confirmed" in props or name in _GATED_TOOLS
 
 
def compact_tool_map(
    schemas: list[dict[str, Any]], *, max_purpose: int = 160, confirm_marker: bool = True
) -> str:
    """Return a Markdown routing table for *schemas*, one row per tool.
 
    Sorted by name; ``*`` marks a required param; ``[confirm]`` marks a
    confirmation-gated tool. The block ends with
    :data:`COMPACT_TOOL_MAP_SENTINEL`. Empty *schemas* → ``""``.
    """
    if not schemas:
        return ""
    rows: list[tuple[str, str, str, str]] = []
    for sch in schemas:
        fn = sch.get("function", sch)
        name = str(fn.get("name", "?"))
        marker = " [confirm]" if confirm_marker and _is_gated(name, fn) else ""
        purpose = _escape_cell(_one_line(str(fn.get("description", "")), max_purpose))
        params = _escape_cell(_params(fn))
        rows.append((name, marker, purpose, params))
    rows.sort(key=lambda r: r[0])
    lines = ["| Tool | Purpose | Parameters |", "|------|---------|------------|"]
    lines += [f"| `{name}`{marker} | {purpose} | {params} |" for name, marker, purpose, params in rows]
    lines += [
        "",
        f"_{len(rows)} tools. Generated from the live registry — do not hand-edit._",
        "",
        COMPACT_TOOL_MAP_SENTINEL,
    ]
    return "\n".join(lines)
 
 
__all__ = ["compact_tool_map", "COMPACT_TOOL_MAP_SENTINEL"]