induscode 0.1.0__py3-none-any.whl

induscode/transcript_export/contract.py

@@ -0,0 +1,522 @@
+"""Transcript-export contract — the FROZEN type surface of the HTML publisher.
+
+Port of the transcript-export half of TS ``src/briefing/contract.ts`` (the TS
+build hosted these types on the briefing contract; the Python build relocates
+them here, next to the modules that implement them — see the port note in
+``induscode.briefing.contract``). It declares *only* shapes plus inert
+constants — no string assembly, no theme math — so every behavior module (the
+SGR painter, the theme bridge, the page-shell template, and the publisher) is
+written against the names declared here. The file is intentionally small,
+append-mostly, and stable.
+
+Design stance:
+
+- ANSI styling is a **table-driven SGR machine**. :class:`SgrState` is the
+  running style; an :data:`SgrToken` is one parsed unit (a text run or an SGR
+  command); an :data:`SgrMutation` is the partial state one code imposes. The
+  SGR *semantics* (which code sets which attribute) are the published
+  standard; the state shape is ours.
+- HTML-export color is computed behind a :class:`ThemeBridge` over an
+  :class:`ExportTheme` token bag, with luminance read from a precomputed
+  :data:`LuminanceLut` (the WCAG relative-luminance formula is a standard; the
+  LUT and the fallback colors are ours).
+- Publishing consumes :class:`PublishEntry` nodes whose
+  :class:`PublishMessage` is a *narrow structural view* of a framework
+  message — the publisher never imports the framework message union; it reads
+  ``role`` / ``content`` / ``toolCallId`` / ``toolName`` and dispatches on
+  each part's ``type`` tag.
+
+Faults stay briefing-owned: :class:`BriefingFault` (kinds ``publish`` /
+``theme`` included) is imported from ``induscode.briefing.contract`` and
+re-exported here, so the closed fault set lives in exactly one place.
+
+Framework anchors (from the ``indusagi`` package):
+
+- :class:`TextContent`, :class:`ImageContent` ← ``indusagi.ai``
+
+This contract never re-declares those; it composes them. Wire-facing field
+names that mirror the framework's keep their camelCase (``toolCallId``,
+``toolName``, ``callId``, ``mimeType``), exactly as the framework's own
+message dataclasses do; the camelCase :class:`ExportTheme` token names are
+likewise wire-facing — the publisher hyphenates them into the ``--x-*`` CSS
+custom properties the page shell reads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import ClassVar, Final, Literal, Protocol, TypeAlias
+
+from indusagi.ai import ImageContent, TextContent
+
+from induscode.briefing.contract import (
+    BriefingFault,
+    BriefingFaultKind,
+    briefing_fault,
+)
+
+__all__ = [
+    "BriefingFault",
+    "BriefingFaultKind",
+    "ExportTheme",
+    "FALLBACK_EXPORT_THEME",
+    "ImageContent",
+    "LuminanceLut",
+    "MessagePart",
+    "PublishEntry",
+    "PublishMessage",
+    "PublishOptions",
+    "PublishRole",
+    "Rgb",
+    "SGR_INITIAL_STATE",
+    "SHELL_SLOTS",
+    "SgrCommandToken",
+    "SgrMutation",
+    "SgrState",
+    "SgrTextToken",
+    "SgrToken",
+    "ShellSlot",
+    "TextContent",
+    "ThemeBridge",
+    "ThemeMode",
+    "ThinkingPart",
+    "ToolCallPart",
+    "TranscriptPart",
+    "WidgetRender",
+    "briefing_fault",
+]
+
+
+# ---------------------------------------------------------------------------
+# SGR machine (table-driven ANSI styling)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SgrState:
+    """The running display style of the table-driven SGR machine.
+
+    As the painter scans an ANSI stream it folds each SGR command into this
+    state via the mutation table, then emits a styled span whenever a text run
+    follows. Colors are stored as resolved CSS color strings (or ``None`` for
+    "inherit"); the boolean flags track the standard attribute set. The shape
+    is this rebuild's own; the SGR *semantics* (which code sets which
+    attribute) are the published standard.
+
+    - ``fg`` / ``bg`` — foreground / background color, or ``None`` for the
+      default.
+    - ``bold`` — increased weight (SGR 1).
+    - ``dim`` — decreased intensity (SGR 2).
+    - ``italic`` — italic (SGR 3).
+    - ``underline`` — underline (SGR 4).
+    - ``blink`` — blink (SGR 5/6), rendered as an attribute hook.
+    - ``inverse`` — swap fg/bg at render time (SGR 7).
+    - ``hidden`` — concealed text (SGR 8).
+    - ``strike`` — crossed-out (SGR 9).
+    """
+
+    # Foreground color as a CSS color string, or None for the default.
+    fg: str | None = None
+    # Background color as a CSS color string, or None for the default.
+    bg: str | None = None
+    # Increased weight (SGR 1).
+    bold: bool = False
+    # Decreased intensity (SGR 2).
+    dim: bool = False
+    # Italic (SGR 3).
+    italic: bool = False
+    # Underline (SGR 4).
+    underline: bool = False
+    # Blink (SGR 5/6).
+    blink: bool = False
+    # Swap foreground and background at render time (SGR 7).
+    inverse: bool = False
+    # Concealed text (SGR 8).
+    hidden: bool = False
+    # Crossed-out (SGR 9).
+    strike: bool = False
+
+
+#: The neutral starting style of the SGR machine — every attribute off and
+#: both colors at their default. A reset (SGR 0) returns the state to exactly
+#: this.
+SGR_INITIAL_STATE: Final[SgrState] = SgrState(
+    fg=None,
+    bg=None,
+    bold=False,
+    dim=False,
+    italic=False,
+    underline=False,
+    blink=False,
+    inverse=False,
+    hidden=False,
+    strike=False,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SgrTextToken:
+    """A run of printable characters for the painter to wrap."""
+
+    kind: ClassVar[Literal["text"]] = "text"
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class SgrCommandToken:
+    """The numeric parameter list of one ``ESC[...m`` sequence (an empty list
+    means a bare ``ESC[m``, equivalent to a reset)."""
+
+    kind: ClassVar[Literal["sgr"]] = "sgr"
+    params: tuple[int, ...]
+
+
+#: One unit produced by the SGR tokenizer.
+#:
+#: Scanning an ANSI stream splits it into an alternation of plain text runs
+#: and SGR command sequences. The painter walks these tokens, applying ``sgr``
+#: parameter lists to the running :class:`SgrState` and wrapping ``text`` runs
+#: in a span styled by the state in force.
+SgrToken: TypeAlias = SgrTextToken | SgrCommandToken
+
+#: A field-level mutation an SGR code applies to the running
+#: :class:`SgrState` — a mapping of :class:`SgrState` field names to their
+#: new values (the Python form of the TS ``Partial<SgrState>``).
+#:
+#: The painter's dispatch table maps each handled SGR parameter to one of
+#: these partial states; folding it over the current state yields the next
+#: state. This is the data form of the SGR semantics — a table, not a switch —
+#: so the set of handled codes is extended by adding table rows, not by
+#: editing control flow.
+SgrMutation: TypeAlias = Mapping[str, str | bool | None]
+
+
+# ---------------------------------------------------------------------------
+# Export theme + ThemeBridge (HTML transcript publishing)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExportTheme:
+    """The color token bag the HTML transcript is themed with.
+
+    These are this rebuild's *own* token names and default values —
+    deliberately not the legacy export's. The publisher emits them as CSS
+    custom properties and the page shell reads them. ``surface`` family tokens
+    are the large backgrounds; ``ink`` is the body text color; ``accent``
+    tints interactive affordances; the ``role`` tokens tint message
+    attribution. Values are any CSS color string. The camelCase token names
+    are wire-facing: the publisher hyphenates each into its ``--x-*`` CSS
+    custom property (``pageSurface`` → ``--x-page-surface``).
+
+    - ``pageSurface`` — the outermost page background.
+    - ``cardSurface`` — the surface of a message card.
+    - ``noteSurface`` — the surface of an informational/system note.
+    - ``ink`` — primary body text color.
+    - ``inkMuted`` — secondary/de-emphasized text color.
+    - ``accent`` — interactive affordance tint.
+    - ``border`` — hairline/separator color.
+    - ``userRole`` — attribution tint for user turns.
+    - ``agentRole`` — attribution tint for assistant turns.
+    - ``toolRole`` — attribution tint for tool turns.
+    """
+
+    # Outermost page background.
+    pageSurface: str
+    # Surface of a message card.
+    cardSurface: str
+    # Surface of an informational/system note.
+    noteSurface: str
+    # Primary body text color.
+    ink: str
+    # Secondary/de-emphasized text color.
+    inkMuted: str
+    # Interactive affordance tint.
+    accent: str
+    # Hairline/separator color.
+    border: str
+    # Attribution tint for user turns.
+    userRole: str
+    # Attribution tint for assistant turns.
+    agentRole: str
+    # Attribution tint for tool turns.
+    toolRole: str
+
+
+#: This rebuild's own fallback :class:`ExportTheme` — a calm dark palette used
+#: when the active UI theme supplies no export colors.
+#:
+#: Chosen fresh for this rebuild (a deep slate page over a muted blue accent);
+#: none of these values are the legacy export's magic constants. The
+#: :class:`ThemeBridge` derives surface variants from these when a richer
+#: source is unavailable.
+FALLBACK_EXPORT_THEME: Final[ExportTheme] = ExportTheme(
+    pageSurface="#13161c",
+    cardSurface="#1b1f27",
+    noteSurface="#232834",
+    ink="#e6e8ee",
+    inkMuted="#9aa3b2",
+    accent="#6f9ce8",
+    border="#2c323d",
+    userRole="#7fd1b9",
+    agentRole="#6f9ce8",
+    toolRole="#d6a36b",
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Rgb:
+    """An RGB color decomposed into its 0–255 channels.
+
+    The neutral intermediate the :class:`ThemeBridge` parses a CSS color into
+    before computing luminance or deriving a brighter/darker variant.
+    ``parse_color`` produces one; ``format_color`` renders one back to a CSS
+    string.
+    """
+
+    # Red channel, 0–255.
+    r: int
+    # Green channel, 0–255.
+    g: int
+    # Blue channel, 0–255.
+    b: int
+
+
+#: A precomputed lookup table for the per-channel sRGB→linear step of the
+#: WCAG relative-luminance formula.
+#:
+#: The formula is a published standard; computing it per pixel is wasteful, so
+#: the :class:`ThemeBridge` reads the linearized value of each 0–255 channel
+#: from this table — one entry per channel value — and combines the three with
+#: the standard weights. The table is ours (an implementation choice, expected
+#: to be 256 entries long); the math it encodes is the standard.
+LuminanceLut: TypeAlias = Sequence[float]
+
+#: Whether a theme reads as light or dark, by the luminance of its page
+#: surface.
+#:
+#: The :class:`ThemeBridge` branches surface derivation on this: a ``light``
+#: base darkens its variants, a ``dark`` base lightens them. The threshold is
+#: a fixed midpoint of the relative-luminance range.
+ThemeMode: TypeAlias = Literal["light", "dark"]
+
+
+class ThemeBridge(Protocol):
+    """The color service behind the HTML transcript export.
+
+    Replaces the legacy export's loose color functions and ``{{TOKEN}}``
+    string replacement with one small typed service: it resolves an
+    :class:`ExportTheme`, reports the theme's :data:`ThemeMode`, derives
+    surface variants via luminance, computes relative luminance through a
+    :data:`LuminanceLut`, and projects the theme to the CSS custom properties
+    the page shell consumes. Implementations are pure with respect to their
+    inputs.
+    """
+
+    # The resolved export theme this bridge serves.
+    theme: ExportTheme
+
+    def mode(self) -> ThemeMode:
+        """Whether the theme reads as light or dark by page-surface
+        luminance."""
+        ...
+
+    def luminance(self, color: str) -> float:
+        """Compute the WCAG relative luminance (0–1) of a CSS color, reading
+        the per-channel sRGB→linear step from the bridge's
+        :data:`LuminanceLut`.
+
+        :param color: a CSS color string to measure
+        """
+        ...
+
+    def derive_surface(self, base: str, amount: float) -> str:
+        """Derive a surface variant from a base color by stepping its
+        lightness toward or away from the theme's :data:`ThemeMode`.
+
+        :param base: the base CSS color to adjust
+        :param amount: signed lightness delta (positive lightens, negative
+            darkens)
+        """
+        ...
+
+    def to_css_vars(self) -> Mapping[str, str]:
+        """Project the theme to the CSS custom properties the page shell
+        reads, keyed by their token name (e.g. ``"pageSurface"``) with CSS
+        color string values."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Transcript publishing
+# ---------------------------------------------------------------------------
+
+#: A message payload fragment as it appears in a transcript node — the union
+#: the publisher renders into a message card.
+#:
+#: Aliases the framework content parts (:class:`TextContent` for prose,
+#: :class:`ImageContent` for inline images) so a persisted transcript node
+#: round-trips into the publisher without a parallel content type. The
+#: publisher walks these and emits the corresponding HTML fragment.
+TranscriptPart: TypeAlias = TextContent | ImageContent
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingPart:
+    """An internal-reasoning content part, read structurally by the
+    publisher and rendered as a muted note rather than prose."""
+
+    type: ClassVar[Literal["thinking"]] = "thinking"
+    thinking: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolCallPart:
+    """A tool-call content part, read structurally so the assistant turn can
+    surface a call's name and arguments without importing the framework
+    message union. Structurally compatible with the framework's ``ToolCall``
+    (same ``type`` tag and field names), so either may appear in a
+    :class:`PublishMessage` content list."""
+
+    type: ClassVar[Literal["toolCall"]] = "toolCall"
+    id: str
+    name: str
+    arguments: Mapping[str, object]
+
+
+#: The content-part union the publisher renders. Text and image parts alias
+#: the framework's; thinking and tool-call parts are read structurally so the
+#: assistant turn can surface a call's name and arguments.
+MessagePart: TypeAlias = TextContent | ImageContent | ThinkingPart | ToolCallPart
+
+#: The conversational role a published turn carries. Mirrors the conductor's
+#: node roles but is declared locally so the publisher depends only on this
+#: contract, not on the conductor subsystem.
+PublishRole: TypeAlias = Literal["user", "assistant", "tool", "system", "condense", "note"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PublishMessage:
+    """The narrow view of a framework message the publisher reads.
+
+    Covers the three concrete message roles' content shapes plus the
+    tool-call linkage a tool result carries, without redeclaring the whole
+    framework union. ``toolCallId`` / ``toolName`` keep the framework's
+    camelCase, exactly as ``indusagi.ai.ToolResultMessage`` spells them.
+    """
+
+    # The framework message role.
+    role: str
+    # The message content — a bare string or a list of content parts.
+    content: str | Sequence[MessagePart]
+    # Present on tool-result messages; links the node to its originating call.
+    toolCallId: str | None = None
+    # Present on tool-result messages; the invoked tool's display name.
+    toolName: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PublishEntry:
+    """One transcript node the publisher consumes.
+
+    Structurally a subset of the conductor's persisted entry: a ``role`` for
+    attribution and a ``message`` carrying the framework content this node
+    renders. The ``message`` is read with narrow structural access so the
+    publisher never imports the framework message union.
+    """
+
+    # Attribution role for this node.
+    role: PublishRole
+    # The framework message payload to render.
+    message: PublishMessage
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class WidgetRender:
+    """The pre-rendered HTML a custom (non-builtin) tool contributes to the
+    transcript, keyed back to its tool-call.
+
+    Custom tools render their call and result through the widget rasterizer
+    ahead of page assembly; the publisher looks the result up by ``callId``
+    when it emits that tool's card. A single ``html`` string carries the
+    rendered block (the legacy collapsed/expanded pair is intentionally
+    flattened to one).
+    """
+
+    # The tool-call id this rendered block belongs to.
+    callId: str
+    # The rendered HTML block for the tool's call/result.
+    html: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PublishOptions:
+    """Options that configure a single transcript publish.
+
+    ``theme`` overrides the export palette (otherwise the fallback is used);
+    ``title`` labels the document; ``out_dir`` chooses where the file is
+    written; and ``widgets`` supplies any pre-rendered custom-tool blocks to
+    splice in. All are optional — publishing a transcript with no options
+    produces a themed, self-contained file under the default location.
+    """
+
+    # Override export palette; defaults to FALLBACK_EXPORT_THEME.
+    theme: ExportTheme | None = None
+    # Document title for the published page.
+    title: str | None = None
+    # Directory to write the published file into.
+    out_dir: str | None = None
+    # Pre-rendered custom-tool blocks, keyed by their tool-call id.
+    widgets: Sequence[WidgetRender] | None = None
+
+
+#: The placeholder token names the page shell template carries.
+#:
+#: The publisher interpolates each of these into the shell with a typed
+#: substitution keyed off this mapping — replacing the legacy ad-hoc
+#: ``{{TOKEN}}`` string replacement. The names are this rebuild's own; the
+#: values are computed at publish time (theme vars, surface colors, inlined
+#: CSS/JS, the base64 session payload, and the preserved library notices).
+#:
+#: Port note: the ``markedLib`` / ``highlightLib`` slot *keys* and token
+#: strings are kept from the TS contract (the closed slot set is frozen), but
+#: in the Python build they carry the markdown-it-py and Pygments license
+#: notices — the libraries this port renders with — instead of marked /
+#: highlight.js.
+SHELL_SLOTS: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        # CSS custom-property block derived from the ThemeBridge.
+        "themeVars": "THEME_VARS",
+        # Resolved page-surface color.
+        "pageSurface": "PAGE_SURFACE",
+        # Resolved card-surface color.
+        "cardSurface": "CARD_SURFACE",
+        # Resolved note-surface color.
+        "noteSurface": "NOTE_SURFACE",
+        # Inlined stylesheet body.
+        "styles": "STYLES",
+        # Inlined client renderer body.
+        "script": "SCRIPT",
+        # Base64-encoded session payload.
+        "payload": "PAYLOAD",
+        # Markdown library notice (markdown-it-py, MIT, preserved verbatim).
+        "markedLib": "MARKED_LIB",
+        # Highlighter library notice (Pygments, BSD-2-Clause, preserved verbatim).
+        "highlightLib": "HIGHLIGHT_LIB",
+    }
+)
+
+#: The literal slot-name type of :data:`SHELL_SLOTS`.
+ShellSlot: TypeAlias = Literal[
+    "THEME_VARS",
+    "PAGE_SURFACE",
+    "CARD_SURFACE",
+    "NOTE_SURFACE",
+    "STYLES",
+    "SCRIPT",
+    "PAYLOAD",
+    "MARKED_LIB",
+    "HIGHLIGHT_LIB",
+]