loopx 0.4.8__py3-none-any.whl

loopx/presentation/markdown.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+
+class _MarkdownCell(str):
+    pass
+
+
+def as_dict(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def as_list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def markdown_scalar(value: Any) -> str:
+    return str(value or "").replace("\r", " ").replace("\n", " ").replace("|", "\\|").strip()
+
+
+def markdown_code(value: Any) -> str:
+    return _MarkdownCell(f"`{markdown_scalar(value)}`")
+
+
+def markdown_table_row(cells: Iterable[Any]) -> str:
+    rendered = (
+        str(cell) if isinstance(cell, _MarkdownCell) else markdown_scalar(cell)
+        for cell in cells
+    )
+    return "| " + " | ".join(rendered) + " |"
+
+
+def markdown_table_separator(column_count: int) -> str:
+    if column_count < 1:
+        raise ValueError("markdown table must have at least one column")
+    return markdown_table_row(["---"] * column_count)
+
+
+def append_operator_action_markdown(
+    lines: list[str],
+    payload: dict[str, Any],
+) -> None:
+    action = as_dict(payload.get("operator_action"))
+    if not action:
+        return
+    if payload.get("error_code"):
+        lines.append(f"- error_code: `{markdown_scalar(payload.get('error_code'))}`")
+    if payload.get("incident_channel"):
+        lines.append(
+            f"- incident_channel: `{markdown_scalar(payload.get('incident_channel'))}`"
+        )
+    lines.append(
+        "- operator_action: "
+        f"action={markdown_scalar(action.get('action'))} "
+        f"holder_pid={markdown_scalar(action.get('holder_pid')) or 'unknown'} "
+        f"retry_mode={markdown_scalar(action.get('retry_mode'))}"
+    )
+    for step in as_list(action.get("steps")):
+        lines.append(f"  - {markdown_scalar(step)}")

loopx/presentation/projection_source_reconcile.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+SCHEMA_VERSION = "projection_source_reconcile_plan_v0"
+
+
+def validate_projection_source_reconcile_request(
+    *,
+    requested: bool,
+    source_snapshot_complete: bool,
+    agent_id: str | None,
+    include_done: bool,
+    namespace_warnings: Sequence[str],
+    selected_row_count: int,
+    complete_row_count: int,
+    complete_warnings: Sequence[str],
+) -> None:
+    if not requested:
+        return
+    if not source_snapshot_complete:
+        raise ValueError(
+            "source reconcile requires an explicit complete source snapshot"
+        )
+    if agent_id:
+        raise ValueError("source reconcile refuses an agent-filtered projection")
+    if not include_done:
+        raise ValueError("source reconcile requires include_done=true")
+    warnings = [*namespace_warnings, *complete_warnings]
+    if warnings:
+        raise ValueError(str(warnings[0]))
+    if selected_row_count != complete_row_count:
+        raise ValueError(
+            "source reconcile row limit truncates the complete source snapshot"
+        )
+
+
+def projection_source_key_prefix(*, goal_id: str, source_id: str) -> str:
+    resolved_goal = str(goal_id or "").strip()
+    resolved_source = str(source_id or "").strip()
+    if not resolved_goal:
+        raise ValueError("projection source reconcile requires goal_id")
+    if not resolved_source:
+        raise ValueError("projection source reconcile requires source_id")
+    return f"{resolved_goal}:projection:{resolved_source}:"
+
+
+def plan_projection_source_reconcile(
+    *,
+    goal_id: str,
+    source_id: str,
+    desired_keys: Sequence[str],
+    local_record_map: Mapping[str, str],
+    remote_records: Sequence[Mapping[str, Any]],
+) -> dict[str, Any]:
+    """Plan exact orphan cleanup inside one complete projection namespace."""
+
+    prefix = projection_source_key_prefix(goal_id=goal_id, source_id=source_id)
+    desired = {str(key).strip() for key in desired_keys if str(key).strip()}
+    outside = sorted(key for key in desired if not key.startswith(prefix))
+    if outside:
+        raise ValueError(
+            "desired projection keys must stay inside the reconciled source namespace"
+        )
+
+    local_source_keys = {
+        str(key).strip()
+        for key in local_record_map
+        if str(key).strip().startswith(prefix)
+    }
+    remote_source_records: list[dict[str, str]] = []
+    for item in remote_records:
+        key = str(item.get("key") or "").strip()
+        record_id = str(item.get("record_id") or "").strip()
+        if key.startswith(prefix) and record_id:
+            remote_source_records.append({"key": key, "record_id": record_id})
+
+    remote_by_key: dict[str, list[dict[str, str]]] = {}
+    for item in remote_source_records:
+        remote_by_key.setdefault(item["key"], []).append(item)
+
+    remote_orphans = sorted(
+        (
+            item
+            for key, items in remote_by_key.items()
+            if key not in desired
+            for item in items
+        ),
+        key=lambda item: (item["key"], item["record_id"]),
+    )
+    remote_duplicates: list[dict[str, str]] = []
+    duplicate_keys: list[str] = []
+    for key, items in sorted(remote_by_key.items()):
+        if key not in desired or len(items) < 2:
+            continue
+        ordered = sorted(items, key=lambda item: item["record_id"])
+        preferred_record_id = str(local_record_map.get(key) or "").strip()
+        keeper_record_id = (
+            preferred_record_id
+            if any(item["record_id"] == preferred_record_id for item in ordered)
+            else ordered[0]["record_id"]
+        )
+        duplicates = [
+            item for item in ordered if item["record_id"] != keeper_record_id
+        ]
+        if duplicates:
+            duplicate_keys.append(key)
+            remote_duplicates.extend(duplicates)
+
+    remote_delete_records = sorted(
+        [*remote_orphans, *remote_duplicates],
+        key=lambda item: (item["key"], item["record_id"]),
+    )
+    local_mapping_keys_to_remove = sorted(local_source_keys - desired)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "goal_id": str(goal_id).strip(),
+        "source_id": str(source_id).strip(),
+        "namespace_prefix": prefix,
+        "desired_key_count": len(desired),
+        "remote_source_record_count": len(remote_source_records),
+        "remote_source_key_count": len(remote_by_key),
+        "local_source_mapping_count": len(local_source_keys),
+        "remote_orphans": remote_orphans,
+        "remote_orphan_record_ids": [item["record_id"] for item in remote_orphans],
+        "remote_duplicate_key_count": len(duplicate_keys),
+        "remote_duplicate_keys": duplicate_keys,
+        "remote_duplicates": remote_duplicates,
+        "remote_duplicate_record_ids": [
+            item["record_id"] for item in remote_duplicates
+        ],
+        "remote_delete_record_ids": [
+            item["record_id"] for item in remote_delete_records
+        ],
+        "local_mapping_keys_to_remove": local_mapping_keys_to_remove,
+        "remote_delete_count": len(remote_delete_records),
+        "local_mapping_delete_count": len(local_mapping_keys_to_remove),
+    }

loopx/presentation/public_safety.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+
+PUBLIC_SAFE_BOUNDARY_FIELDS = (
+    "raw_logs_recorded",
+    "raw_transcripts_recorded",
+    "raw_connector_payloads_recorded",
+    "credential_values_recorded",
+    "absolute_paths_recorded",
+    "private_source_bodies_recorded",
+)
+
+LOCAL_PATH_PATTERNS = (
+    re.compile(r"/(?:Users|home|private|tmp|var)/[^\s`|,)]+"),
+    re.compile(r"[A-Za-z]:\\\\Users\\\\[^\s`|,)]+"),
+)
+
+
+def public_safe_boundary() -> dict[str, bool]:
+    return {field: False for field in PUBLIC_SAFE_BOUNDARY_FIELDS}
+
+
+def redact_public_text(
+    value: Any,
+    *,
+    limit: int,
+    replacements: Mapping[str, str] | None = None,
+    truncation_marker: str = "...",
+) -> str:
+    text = str(value or "").strip()
+    for source, target in (replacements or {}).items():
+        text = text.replace(source, target)
+    for pattern in LOCAL_PATH_PATTERNS:
+        text = pattern.sub("<local-path-redacted>", text)
+    text = re.sub(r"\s+", " ", text)
+    if len(text) > limit:
+        return text[: max(0, limit - 1)].rstrip() + truncation_marker
+    return text

loopx/presentation/renderers/__init__.py

@@ -0,0 +1,17 @@
+"""Render-only helpers for LoopX presentation surfaces."""
+
+from .periodic_report_html import (
+    periodic_report_html_renderer_adapter,
+    render_periodic_report_html,
+)
+from .periodic_report_markdown import (
+    periodic_report_markdown_renderer_adapter,
+    render_periodic_report_markdown,
+)
+
+__all__ = [
+    "periodic_report_html_renderer_adapter",
+    "periodic_report_markdown_renderer_adapter",
+    "render_periodic_report_html",
+    "render_periodic_report_markdown",
+]

loopx/presentation/renderers/goal_channel_html.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from html import escape
+from typing import Any, Mapping, Sequence
+
+from ...control_plane.goals.goal_channel_projection import (
+    GOAL_CHANNEL_PROJECTION_SCHEMA_VERSION,
+    compact_goal_channel_text,
+)
+
+
+def _as_mapping(value: Mapping[str, Any] | None) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _as_mappings(values: Sequence[Mapping[str, Any]] | None) -> list[dict[str, Any]]:
+    if not values:
+        return []
+    return [dict(item) for item in values if isinstance(item, Mapping)]
+
+
+def _html_text(value: Any, *, fallback: str = "") -> str:
+    text = compact_goal_channel_text(value, limit=500)
+    return escape(text if text is not None else fallback)
+
+
+def _html_attr(value: Any) -> str:
+    return escape(str(value), quote=True)
+
+
+def _html_dict_list(items: Sequence[Mapping[str, Any]], *, keys: Sequence[str]) -> str:
+    rows: list[str] = []
+    for item in items:
+        cells = []
+        for key in keys:
+            value = item.get(key)
+            if value in (None, "", []):
+                continue
+            cells.append(
+                f"<dt>{_html_text(key.replace('_', ' ').title())}</dt>"
+                f"<dd>{_html_text(value)}</dd>"
+            )
+        if cells:
+            rows.append("<li><dl>" + "".join(cells) + "</dl></li>")
+    return "\n".join(rows)
+
+
+def _html_panel(
+    *,
+    panel: str,
+    title: str,
+    body: str,
+    tone: str = "neutral",
+) -> str:
+    return (
+        f'<section class="panel panel-{_html_attr(tone)}" data-panel="{_html_attr(panel)}">'
+        f"<h2>{_html_text(title)}</h2>"
+        f"{body}"
+        "</section>"
+    )
+
+
+def _html_kv_panel(panel: str, title: str, values: Mapping[str, Any], *, tone: str = "neutral") -> str:
+    pairs = []
+    for key, value in values.items():
+        if value in (None, "", []):
+            continue
+        pairs.append(
+            f"<dt>{_html_text(str(key).replace('_', ' ').title())}</dt>"
+            f"<dd>{_html_text(value)}</dd>"
+        )
+    body = "<dl>" + "".join(pairs) + "</dl>" if pairs else '<p class="empty">No compact fields.</p>'
+    return _html_panel(panel=panel, title=title, body=body, tone=tone)
+
+
+def _html_item_panel(
+    panel: str,
+    title: str,
+    items: Sequence[Mapping[str, Any]],
+    *,
+    keys: Sequence[str],
+    empty: str,
+    tone: str = "neutral",
+) -> str:
+    if items:
+        body = "<ol>" + _html_dict_list(items, keys=keys) + "</ol>"
+    else:
+        body = f'<p class="empty">{_html_text(empty)}</p>'
+    return _html_panel(panel=panel, title=title, body=body, tone=tone)
+
+
+def render_goal_channel_projection_html(projection: Mapping[str, Any]) -> str:
+    """Render a read-only static HTML fixture for a channel projection.
+
+    This renderer is intentionally presentation-only. It accepts an already
+    compact projection, exposes source warnings, and avoids form/button/write
+    controls so dashboard prototypes can validate the frontstage shape without
+    becoming a second source of truth.
+    """
+
+    if projection.get("schema_version") != GOAL_CHANNEL_PROJECTION_SCHEMA_VERSION:
+        raise ValueError("unsupported goal channel projection schema_version")
+    if projection.get("mode") != "read_only":
+        raise ValueError("goal channel projection renderer only accepts read_only mode")
+
+    goal_id = projection.get("goal_id") or "goal"
+    display_name = projection.get("display_name") or goal_id
+    decision_frame = _as_mapping(projection.get("decision_frame"))
+    quota = _as_mapping(projection.get("quota"))
+    source_refs = _as_mapping(projection.get("source_refs"))
+    truth_contract = _as_mapping(projection.get("truth_contract"))
+    user_todos = _as_mappings(projection.get("user_todos"))
+    agent_todos = _as_mappings(projection.get("agent_todos"))
+    open_gates = _as_mappings(projection.get("open_gates"))
+    artifacts = _as_mappings(projection.get("artifacts"))
+    active_leases = _as_mappings(projection.get("active_leases"))
+    recent_events = _as_mappings(projection.get("recent_events"))
+    source_warnings = _as_mappings(projection.get("source_warnings"))
+
+    panels = [
+        _html_kv_panel("decision-frame", "Decision Frame", decision_frame, tone="blue"),
+        _html_kv_panel("quota", "Quota Guard", quota, tone="purple"),
+        _html_item_panel(
+            "user-todos",
+            "User Todos",
+            user_todos,
+            keys=(
+                "priority",
+                "status",
+                "bound_agent",
+                "goal_bound",
+                "todo_id",
+                "title",
+            ),
+            empty="No open user todo projected.",
+            tone="orange",
+        ),
+        _html_item_panel(
+            "agent-todos",
+            "Agent Todos",
+            agent_todos,
+            keys=(
+                "priority",
+                "status",
+                "claimed_by",
+                "todo_id",
+                "title",
+            ),
+            empty="No open agent todo projected.",
+            tone="green",
+        ),
+        _html_item_panel(
+            "open-gates",
+            "Open Gates",
+            open_gates,
+            keys=("kind", "status", "gate_id", "blocks"),
+            empty="No open gate projected.",
+            tone="orange",
+        ),
+        _html_item_panel(
+            "active-leases",
+            "Claims And Leases",
+            active_leases,
+            keys=(
+                "status",
+                "owner_agent",
+                "todo_id",
+                "lease_until",
+                "write_scope",
+                "lease_version",
+                "expires_at",
+                "reason",
+                "claimed_by",
+            ),
+            empty="No active claim or lease projected.",
+            tone="green",
+        ),
+        _html_item_panel(
+            "artifacts",
+            "Artifacts",
+            artifacts,
+            keys=("kind", "label", "path", "run_id"),
+            empty="No public-safe artifact projected.",
+        ),
+        _html_item_panel(
+            "recent-events",
+            "Recent Events",
+            recent_events,
+            keys=("generated_at", "classification", "summary"),
+            empty="No compact run event projected.",
+        ),
+        _html_item_panel(
+            "source-warnings",
+            "Source Warnings",
+            source_warnings,
+            keys=("kind", "key_names", "message"),
+            empty="No source warning.",
+            tone="red",
+        ),
+        _html_kv_panel("source-refs", "Source References", source_refs),
+        _html_kv_panel("truth-contract", "Truth Contract", truth_contract, tone="blue"),
+    ]
+
+    css = """
+    :root {
+      color-scheme: light;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #f8fafc;
+      color: #111827;
+    }
+    body { margin: 0; }
+    main { max-width: 1180px; margin: 0 auto; padding: 40px 24px 56px; }
+    header { border-bottom: 1px solid #d7dde8; padding-bottom: 22px; margin-bottom: 24px; }
+    h1 { font-size: 34px; line-height: 1.15; margin: 0 0 10px; letter-spacing: 0; }
+    h2 { font-size: 18px; line-height: 1.25; margin: 0 0 16px; letter-spacing: 0; }
+    p { color: #4b5563; margin: 0; line-height: 1.55; }
+    code { background: #eef2ff; border-radius: 4px; padding: 2px 5px; }
+    .meta { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 14px; }
+    .pill { border: 1px solid #cfd8e7; border-radius: 999px; color: #334155; padding: 6px 10px; font-size: 13px; }
+    .grid { display: grid; gap: 16px; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); }
+    .panel { background: #ffffff; border: 1px solid #d8dee9; border-radius: 8px; padding: 18px; min-height: 160px; }
+    .panel-blue { border-color: #3b82f6; background: #eff6ff; }
+    .panel-green { border-color: #22c55e; background: #f0fdf4; }
+    .panel-orange { border-color: #f59e0b; background: #fffbeb; }
+    .panel-purple { border-color: #8b5cf6; background: #f5f3ff; }
+    .panel-red { border-color: #f43f5e; background: #fff1f2; }
+    ol { margin: 0; padding-left: 20px; display: grid; gap: 12px; }
+    dl { display: grid; grid-template-columns: minmax(92px, 0.35fr) 1fr; gap: 7px 12px; margin: 0; }
+    dt { color: #64748b; font-size: 13px; font-weight: 700; }
+    dd { margin: 0; color: #1f2937; font-size: 14px; line-height: 1.45; overflow-wrap: anywhere; }
+    .empty { color: #64748b; }
+    @media (max-width: 720px) {
+      main { padding: 28px 16px 40px; }
+      h1 { font-size: 28px; }
+      dl { grid-template-columns: 1fr; }
+    }
+    """
+
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{_html_text(display_name)} - Goal Channel Projection</title>
+  <style>{css}</style>
+</head>
+<body>
+  <main
+    data-schema="{_html_attr(projection.get('schema_version'))}"
+    data-mode="{_html_attr(projection.get('mode'))}"
+    data-goal-id="{_html_attr(goal_id)}"
+  >
+    <header>
+      <h1>{_html_text(display_name)}</h1>
+      <p>{_html_text(projection.get('next_action'), fallback='No next action projected.')}</p>
+      <div class="meta">
+        <span class="pill">goal: <code>{_html_text(goal_id)}</code></span>
+        <span class="pill">status: {_html_text(projection.get('latest_status'), fallback='unknown')}</span>
+        <span class="pill">waiting on: {_html_text(projection.get('waiting_on'), fallback='unknown')}</span>
+        <span class="pill">generated: {_html_text(projection.get('generated_at'), fallback='unknown')}</span>
+      </div>
+    </header>
+    <div class="grid">
+      {"".join(panels)}
+    </div>
+  </main>
+</body>
+</html>
+"""