mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/visual_run/__init__.py

@@ -0,0 +1,83 @@
+"""Durable, transport-independent visual run contracts."""
+
+from mostlyright.data_harness.visual_run.contracts import (
+    ACTORS,
+    ARTIFACT_SCHEMAS,
+    DISPLAY_DISPOSITIONS,
+    EVENT_REGISTRY,
+    EVENT_SCHEMA_VERSION,
+    ArtifactReference,
+    EventSpec,
+    TerminalError,
+    VisualRunDraft,
+    VisualRunError,
+    VisualRunEvent,
+    canonical_draft_bytes,
+    canonical_event_bytes,
+    parse_event,
+)
+from mostlyright.data_harness.visual_run.materialize import (
+    materialize_notebook,
+    notebook_bytes,
+    notebook_digest,
+    notebook_value,
+)
+from mostlyright.data_harness.visual_run.reducer import (
+    CellState,
+    ObjectState,
+    ReducedRun,
+    apply_event,
+    reduce_events,
+)
+from mostlyright.data_harness.visual_run.sdk import VisualWork
+from mostlyright.data_harness.visual_run.store import (
+    EventPage,
+    VisualRunStore,
+    snapshot_json,
+    visual_authority_lock,
+)
+from mostlyright.data_harness.visual_run.transport import (
+    SNAPSHOT_SCHEMA_VERSION,
+    VISUAL_RUN_DIR,
+    TransportSnapshot,
+    VisualRunTransport,
+    discover_visual_transport,
+    parse_last_event_id,
+)
+
+__all__ = [
+    "ACTORS",
+    "ARTIFACT_SCHEMAS",
+    "DISPLAY_DISPOSITIONS",
+    "EVENT_REGISTRY",
+    "EVENT_SCHEMA_VERSION",
+    "SNAPSHOT_SCHEMA_VERSION",
+    "VISUAL_RUN_DIR",
+    "ArtifactReference",
+    "CellState",
+    "EventPage",
+    "EventSpec",
+    "ObjectState",
+    "ReducedRun",
+    "TerminalError",
+    "TransportSnapshot",
+    "VisualRunDraft",
+    "VisualRunError",
+    "VisualRunEvent",
+    "VisualRunStore",
+    "VisualRunTransport",
+    "VisualWork",
+    "apply_event",
+    "canonical_draft_bytes",
+    "canonical_event_bytes",
+    "discover_visual_transport",
+    "materialize_notebook",
+    "notebook_bytes",
+    "notebook_digest",
+    "notebook_value",
+    "parse_event",
+    "parse_last_event_id",
+    "reduce_events",
+    "snapshot_json",
+    "visual_authority_lock",
+]

mostlyright/data_harness/visual_run/authoring.py

@@ -0,0 +1,235 @@
+"""Deterministic admission rules for agent-authored visible markdown."""
+
+from __future__ import annotations
+
+import unicodedata
+from collections.abc import Callable
+from html.parser import HTMLParser
+
+from mostlyright.data_harness.nbrender.markdown_body import render_markdown
+from mostlyright.data_harness.nbrender.parse import Cell, RenderContext
+from mostlyright.data_harness.visual_run.contracts import (
+    ArtifactReference,
+    VisualRunError,
+    VisualRunEvent,
+)
+from mostlyright.data_harness.visual_run.reducer import ReducedRun
+
+MAX_MARKDOWN_CHECKPOINT_CHARS = 900
+LONG_MARKDOWN_CHARS = 600
+_VOID_HTML_TAGS = {
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+}
+_HEADING_TAGS = {"h2", "h3", "h4"}
+_BODY_BLOCK_TAGS = {"blockquote", "ol", "p", "pre", "table", "ul"}
+
+
+def _normalize_newlines(source: str) -> str:
+    return source.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def _has_visible_text(value: str) -> bool:
+    return any(
+        not character.isspace() and unicodedata.category(character) not in {"Cc", "Cf", "Cs"}
+        for character in value
+    )
+
+
+class _TopLevelMarkdownBlocks(HTMLParser):
+    """Collect the block tags emitted directly under the renderer's markdown root."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._in_root = False
+        self._depth = 0
+        self.blocks: list[tuple[str, bool]] = []
+        self._active_block: int | None = None
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if not self._in_root:
+            classes = next((value for name, value in attrs if name == "class"), None)
+            if tag == "div" and classes is not None and "nb-md" in classes.split():
+                self._in_root = True
+                self._depth = 1
+            return
+        if self._depth == 1:
+            self.blocks.append((tag, False))
+            self._active_block = len(self.blocks) - 1
+        if self._active_block is not None and tag in {"img", "input"}:
+            accessible_text = next(
+                (value for name, value in attrs if name in {"alt", "value"} and value), None
+            )
+            if accessible_text and _has_visible_text(accessible_text):
+                block_tag, _ = self.blocks[self._active_block]
+                self.blocks[self._active_block] = (block_tag, True)
+        if tag not in _VOID_HTML_TAGS:
+            self._depth += 1
+        elif self._depth == 1:
+            self._active_block = None
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if self._in_root and self._depth == 1:
+            accessible_text = next(
+                (value for name, value in attrs if name in {"alt", "value"} and value), None
+            )
+            self.blocks.append((tag, bool(accessible_text and _has_visible_text(accessible_text))))
+
+    def handle_data(self, data: str) -> None:
+        if self._active_block is None or not _has_visible_text(data):
+            return
+        tag, _ = self.blocks[self._active_block]
+        self.blocks[self._active_block] = (tag, True)
+
+    def handle_endtag(self, tag: str) -> None:
+        if not self._in_root:
+            return
+        if self._depth == 2:
+            self._active_block = None
+        self._depth -= 1
+        if self._depth == 0 and tag == "div":
+            self._in_root = False
+
+
+def markdown_block_tags(source: str) -> tuple[str, ...]:
+    """Return visible top-level blocks using the production renderer's semantics."""
+
+    parser = _TopLevelMarkdownBlocks()
+    parser.feed(
+        render_markdown(
+            Cell(cell_type="markdown", cell_id="authoring-check", source=source),
+            RenderContext(mode="static", cell_index=0, cell_count=1),
+        )
+    )
+    parser.close()
+    return tuple(tag for tag, _ in parser.blocks)
+
+
+def _visible_markdown_blocks(source: str) -> tuple[tuple[str, bool], ...]:
+    parser = _TopLevelMarkdownBlocks()
+    parser.feed(
+        render_markdown(
+            Cell(cell_type="markdown", cell_id="authoring-check", source=source),
+            RenderContext(mode="static", cell_index=0, cell_count=1),
+        )
+    )
+    parser.close()
+    return tuple(parser.blocks)
+
+
+def validate_markdown_document(source: str) -> None:
+    """Reserve the single document title for the deterministic materializer."""
+
+    blocks = _visible_markdown_blocks(_normalize_newlines(source))
+    if any(tag == "h1" and visible for tag, visible in blocks):
+        raise VisualRunError(
+            "VISUAL_WORK_MARKDOWN_UNSTRUCTURED",
+            "the document title is added automatically; agent markdown must start at H2",
+        )
+
+
+def validate_markdown_checkpoint(source: str) -> None:
+    """Admit one readable unit, or one heading followed by its first readable unit."""
+
+    normalized = _normalize_newlines(source)
+    blocks = _visible_markdown_blocks(normalized)
+    validate_markdown_document(normalized)
+    heading_with_body = (
+        len(blocks) == 2
+        and blocks[0][0] in _HEADING_TAGS
+        and blocks[0][1]
+        and blocks[1][0] in _BODY_BLOCK_TAGS
+        and blocks[1][1]
+    )
+    one_visible_block = len(blocks) == 1 and blocks[0][1]
+    if len(normalized) > MAX_MARKDOWN_CHECKPOINT_CHARS or not (
+        one_visible_block or heading_with_body
+    ):
+        raise VisualRunError(
+            "VISUAL_WORK_CHECKPOINT_TOO_LARGE",
+            "markdown checkpoints may add at most 900 characters and one readable block, "
+            "or one heading with its first block",
+        )
+
+
+def validate_markdown_completion(source: str) -> None:
+    """Require hierarchy or a table before a long markdown cell becomes terminal."""
+
+    normalized = _normalize_newlines(source)
+    blocks = _visible_markdown_blocks(normalized)
+    validate_markdown_document(normalized)
+    if len(normalized.strip()) <= LONG_MARKDOWN_CHARS:
+        return
+    has_secondary_structure = any(
+        visible and (tag == "table" or tag in _HEADING_TAGS) for tag, visible in blocks[1:]
+    )
+    if not blocks or blocks[0] != ("h2", True) or not has_secondary_structure:
+        raise VisualRunError(
+            "VISUAL_WORK_MARKDOWN_UNSTRUCTURED",
+            "markdown longer than 600 characters must begin with an H2 outcome heading and "
+            "include a table or second heading",
+        )
+
+
+def validate_agent_authoring_event(
+    before: ReducedRun,
+    event: VisualRunEvent,
+    prospective: ReducedRun,
+    read_artifact: Callable[[ArtifactReference], bytes],
+) -> None:
+    """Validate the exact event and state while the durable append lock is held."""
+
+    if event.actor != "agent" or not event.event_type.startswith("cell."):
+        return
+    cell = prospective.cells.get(event.object_id)
+    if cell is None or cell.cell_type != "markdown":
+        return
+    if event.event_type in {"cell.source_extended", "cell.source_revised"}:
+        if event.artifact is None:
+            return
+        source = read_artifact(event.artifact).decode("utf-8")
+        if int(event.payload["source_length"]) != len(source):
+            raise VisualRunError(
+                "VISUAL_RUN_SOURCE_LENGTH_INVALID",
+                "source_length must equal the decoded source character length",
+            )
+        validate_markdown_document(source)
+        if event.event_type == "cell.source_extended":
+            previous_cell = before.cells.get(event.object_id)
+            previous = (
+                ""
+                if previous_cell is None or previous_cell.source is None
+                else read_artifact(previous_cell.source).decode("utf-8")
+            )
+            if not source.startswith(previous):
+                raise VisualRunError(
+                    "VISUAL_RUN_SOURCE_EXTENSION_INVALID",
+                    "source extension artifact must preserve the prior source prefix",
+                )
+            source = source[len(previous) :]
+        validate_markdown_checkpoint(source)
+    elif event.event_type == "cell.completed" and cell.source is not None:
+        validate_markdown_completion(read_artifact(cell.source).decode("utf-8"))
+
+
+__all__ = [
+    "LONG_MARKDOWN_CHARS",
+    "MAX_MARKDOWN_CHECKPOINT_CHARS",
+    "markdown_block_tags",
+    "validate_agent_authoring_event",
+    "validate_markdown_checkpoint",
+    "validate_markdown_completion",
+    "validate_markdown_document",
+]