induscode 0.1.0__py3-none-any.whl

induscode/conductor/serialize.py

@@ -0,0 +1,575 @@
+"""Transcript serialization — the bridge between the conductor's on-disk
+``TranscriptEntry`` vocabulary and the framework's ``AgentMessage`` shapes
+(port of TS ``src/conductor/transcript-store/serialize.ts``).
+
+Two distinct directions live here, and the split is deliberate:
+
+1. **Conductor ⇄ conductor** — encoding a ``TranscriptEntry`` to/from a single
+   NDJSON line in the ``indus/transcript@1`` format. This is the conductor's
+   *own* envelope (``schema``/``id``/``prev``/``role``/``message``/``at``/
+   ``meta``). The store owns these field names; they are our own, not any
+   framework-internal session schema.
+
+2. **Conductor ⇄ framework** — projecting a transcript branch down to the
+   ``AgentMessage`` list the agent loop consumes, and (for migration) lifting
+   a legacy framework session file *up* into transcript entries. Here we
+   **delegate the actual message resolution to the framework**: the
+   framework's published loader/context helpers
+   (:func:`indusagi.agent.load_entries_from_file`,
+   :func:`indusagi.agent.parse_session_entries`,
+   :func:`indusagi.agent.build_session_context`,
+   :func:`indusagi.agent.convert_to_llm`) know how to parse and resolve the
+   legacy on-disk schema, and those internal schema literals stay inside the
+   framework package rather than being re-declared in the app.
+
+THE MESSAGE ⇄ DICT CODEC (the plan's cross-cutting rule 2)
+----------------------------------------------------------
+TS could ``JSON.stringify`` an ``AgentMessage`` because messages were plain
+objects; the Python framework's messages are **frozen dataclasses** with
+``ClassVar`` role tags, so the NDJSON boundary needs an explicit codec.
+
+Decision (checked ``indusagi.agent.sessions`` FIRST, per the plan):
+
+- The framework owns a serializer-direction only: the *private*
+  ``sessions._jsonable`` projects dataclasses to TS-shaped JSON dicts but the
+  read side deliberately keeps loaded messages as plain dicts (the session
+  manager's losslessness stance) — there is **no public dataclass-rehydrating
+  codec to reuse**. Importing a private underscore helper from the framework
+  would couple the app to an implementation detail.
+- So the one app-wide codec is hand-written here: :func:`message_to_dict`
+  (mirroring the framework's ``_jsonable`` contract: ``role``/``type``
+  ``ClassVar`` tags re-materialized, ``None`` fields dropped exactly like
+  ``JSON.stringify`` drops ``undefined``) and :func:`message_from_dict`
+  (rebuilding every known message shape — the three LLM roles from
+  :mod:`indusagi.ai` *and* the agent's custom session kinds
+  ``bashExecution``/``custom``/``branchSummary``/``compactionSummary`` from
+  :mod:`indusagi.agent` — by their ``role`` tag).
+- **Unknown roles / dict-shaped notes pass through as dicts.** The framework
+  reads message fields through its tolerant accessor (``get_field``) and
+  ``convert_to_llm`` drops unrecognized roles, so a dict-shaped payload flows
+  through the whole system safely; round-tripping it as a dict is lossless
+  where guessing a constructor would not be.
+
+Channels' ``LinkSnapshot``, ``/debug`` JSONL, and transcript-export's
+``PublishEntry`` adapter all consume this codec — no second serializer
+anywhere (plan §5.2).
+
+The ``role`` discriminant on a ``TranscriptEntry`` is the conductor's own —
+``role`` labels the *node*, not the LLM message. It is derived from the
+carried message's ``role`` field so a round-trip is faithful, but the
+transcript can also hold conductor-only nodes (``condense``, ``note``) that
+the framework message union has no direct counterpart for.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, fields as dataclass_fields, is_dataclass
+from typing import Any
+
+from indusagi.agent import (
+    build_session_context,
+    convert_to_llm,
+    load_entries_from_file,
+    parse_session_entries,
+)
+from indusagi.agent import (
+    BashExecutionMessage,
+    BranchSummaryMessage,
+    CompactionSummaryMessage,
+    CustomMessage,
+)
+from indusagi.ai import (
+    AssistantMessage,
+    ImageContent,
+    TextContent,
+    ThinkingContent,
+    ToolCall,
+    ToolResultMessage,
+    Usage,
+    UsageCost,
+    UserMessage,
+)
+
+from induscode.conductor.contract import (
+    TRANSCRIPT_SCHEMA,
+    SessionHead,
+    TranscriptEntry,
+    TranscriptRole,
+)
+
+__all__ = [
+    "ParsedSessionFile",
+    "branch_to_llm_messages",
+    "branch_to_messages",
+    "encode_entry",
+    "encode_head",
+    "import_legacy_file",
+    "import_legacy_text",
+    "message_from_dict",
+    "message_to_dict",
+    "parse_session_text",
+    "resolve_legacy_messages",
+    "role_for_message",
+]
+
+
+# ---------------------------------------------------------------------------
+# Tolerant field access (messages may be dataclasses or dict-shaped notes)
+# ---------------------------------------------------------------------------
+
+
+def _field_of(message: Any, name: str, default: Any = None) -> Any:
+    """Read ``name`` off a message, whether it is a frozen dataclass
+    (attribute access) or a raw mapping (key access)."""
+    if isinstance(message, Mapping):
+        return message.get(name, default)
+    return getattr(message, name, default)
+
+
+# ---------------------------------------------------------------------------
+# Role derivation
+# ---------------------------------------------------------------------------
+
+
+def role_for_message(message: Any) -> TranscriptRole:
+    """Derive the conductor's node ``TranscriptRole`` from a framework
+    ``AgentMessage``.
+
+    The framework message union uses ``role`` values (``user``/``assistant``/
+    ``toolResult`` plus the custom app messages). We fold those onto the
+    transcript's own role vocabulary. Anything we don't recognize
+    (custom/notification-style messages) is filed as a ``note`` node so it
+    persists without claiming an LLM turn role.
+    """
+    match _field_of(message, "role"):
+        case "user":
+            return "user"
+        case "assistant":
+            return "assistant"
+        case "toolResult":
+            return "tool"
+        case "compactionSummary" | "branchSummary":
+            return "condense"
+        case _:
+            return "note"
+
+
+# ---------------------------------------------------------------------------
+# Message ⇄ dict codec
+# ---------------------------------------------------------------------------
+
+
+def message_to_dict(message: Any) -> Any:
+    """Project a framework message (or any nested value) into its
+    JSON-serializable dict form.
+
+    Mirrors the framework's serialization contract: the ``role`` (messages) /
+    ``type`` (content parts) ``ClassVar`` tags are written first, ``None``
+    fields are dropped (``JSON.stringify`` drops ``undefined``), and field
+    names keep their TS camelCase spelling because the dataclasses already do.
+    Mappings and sequences pass through recursively; scalars pass through
+    untouched.
+    """
+    if message is None or isinstance(message, (str, int, float, bool)):
+        return message
+    if isinstance(message, Mapping):
+        return {key: message_to_dict(value) for key, value in message.items()}
+    if isinstance(message, (list, tuple)):
+        return [message_to_dict(item) for item in message]
+    if is_dataclass(message) and not isinstance(message, type):
+        out: dict[str, Any] = {}
+        role = getattr(message, "role", None)
+        if isinstance(role, str):
+            out["role"] = role
+        else:
+            kind = getattr(message, "type", None)
+            if isinstance(kind, str):
+                out["type"] = kind
+        for f in dataclass_fields(message):
+            value = getattr(message, f.name)
+            if value is None:
+                continue  # JSON.stringify drops undefined fields
+            out[f.name] = message_to_dict(value)
+        return out
+    return str(message)
+
+
+def _part_from_dict(part: Any) -> Any:
+    """Rebuild one content part from its dict form by its ``type`` tag;
+    unknown part shapes pass through unchanged."""
+    if not isinstance(part, Mapping):
+        return part
+    match part.get("type"):
+        case "text":
+            return TextContent(
+                text=str(part.get("text", "")),
+                textSignature=part.get("textSignature"),
+            )
+        case "thinking":
+            return ThinkingContent(
+                thinking=str(part.get("thinking", "")),
+                thinkingSignature=part.get("thinkingSignature"),
+            )
+        case "image":
+            return ImageContent(
+                data=str(part.get("data", "")),
+                mimeType=str(part.get("mimeType", "")),
+            )
+        case "toolCall":
+            return ToolCall(
+                id=str(part.get("id", "")),
+                name=str(part.get("name", "")),
+                arguments=dict(part.get("arguments") or {}),
+                thoughtSignature=part.get("thoughtSignature"),
+            )
+        case _:
+            return dict(part)
+
+
+def _parts_from_dict(content: Any) -> tuple[Any, ...]:
+    """Rebuild a content-part list; tolerates a missing/odd payload."""
+    if not isinstance(content, Sequence) or isinstance(content, (str, bytes)):
+        return ()
+    return tuple(_part_from_dict(part) for part in content)
+
+
+def _usage_from_dict(usage: Any) -> Usage:
+    """Rebuild a :class:`~indusagi.ai.Usage` record (zeros where absent)."""
+    cost = _field_of(usage, "cost") or {}
+    return Usage(
+        input=int(_field_of(usage, "input", 0) or 0),
+        output=int(_field_of(usage, "output", 0) or 0),
+        cacheRead=int(_field_of(usage, "cacheRead", 0) or 0),
+        cacheWrite=int(_field_of(usage, "cacheWrite", 0) or 0),
+        totalTokens=int(_field_of(usage, "totalTokens", 0) or 0),
+        cost=UsageCost(
+            input=float(_field_of(cost, "input", 0.0) or 0.0),
+            output=float(_field_of(cost, "output", 0.0) or 0.0),
+            cacheRead=float(_field_of(cost, "cacheRead", 0.0) or 0.0),
+            cacheWrite=float(_field_of(cost, "cacheWrite", 0.0) or 0.0),
+            total=float(_field_of(cost, "total", 0.0) or 0.0),
+        ),
+    )
+
+
+def _timestamp_from(value: Any) -> int:
+    return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else 0
+
+
+def message_from_dict(payload: Any) -> Any:
+    """Rebuild a framework message from its dict form by its ``role`` tag.
+
+    Handles every shape the transcript can carry: the three LLM roles
+    (``user``/``assistant``/``toolResult``), the agent's custom session kinds
+    (``bashExecution``/``custom``/``branchSummary``/``compactionSummary``),
+    and — deliberately — **anything else passes through as the dict it is**
+    (conductor ``note`` payloads, app-registered kinds with unknown
+    constructors). A non-mapping payload also passes through untouched.
+    """
+    if not isinstance(payload, Mapping):
+        return payload
+    match payload.get("role"):
+        case "user":
+            content = payload.get("content")
+            return UserMessage(
+                content=content if isinstance(content, str) else _parts_from_dict(content),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+            )
+        case "assistant":
+            return AssistantMessage(
+                content=_parts_from_dict(payload.get("content")),
+                api=str(payload.get("api", "")),
+                provider=str(payload.get("provider", "")),
+                model=str(payload.get("model", "")),
+                usage=_usage_from_dict(payload.get("usage")),
+                stopReason=payload.get("stopReason", "stop"),
+                errorMessage=payload.get("errorMessage"),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+            )
+        case "toolResult":
+            return ToolResultMessage(
+                toolCallId=str(payload.get("toolCallId", "")),
+                toolName=str(payload.get("toolName", "")),
+                content=_parts_from_dict(payload.get("content")),
+                details=payload.get("details"),
+                isError=bool(payload.get("isError", False)),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+            )
+        case "bashExecution":
+            return BashExecutionMessage(
+                command=str(payload.get("command", "")),
+                output=str(payload.get("output", "")),
+                exitCode=payload.get("exitCode"),
+                cancelled=bool(payload.get("cancelled", False)),
+                truncated=bool(payload.get("truncated", False)),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+                fullOutputPath=payload.get("fullOutputPath"),
+                excludeFromContext=payload.get("excludeFromContext"),
+            )
+        case "custom":
+            content = payload.get("content")
+            return CustomMessage(
+                customType=str(payload.get("customType", "")),
+                content=content if isinstance(content, str) else _parts_from_dict(content),
+                display=bool(payload.get("display", False)),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+                details=payload.get("details"),
+            )
+        case "branchSummary":
+            return BranchSummaryMessage(
+                summary=str(payload.get("summary", "")),
+                fromId=str(payload.get("fromId", "")),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+            )
+        case "compactionSummary":
+            return CompactionSummaryMessage(
+                summary=str(payload.get("summary", "")),
+                tokensBefore=int(payload.get("tokensBefore", 0) or 0),
+                timestamp=_timestamp_from(payload.get("timestamp")),
+            )
+        case _:
+            # Unknown role / dict-shaped note: keep the dict verbatim. The
+            # framework's tolerant accessors handle it everywhere downstream.
+            return dict(payload)
+
+
+# ---------------------------------------------------------------------------
+# Entry ⇄ line (conductor's own format)
+# ---------------------------------------------------------------------------
+
+
+def _dump_line(line: Mapping[str, Any]) -> str:
+    # JSON.stringify's compact separators; non-ASCII kept literal.
+    return json.dumps(line, separators=(",", ":"), ensure_ascii=False)
+
+
+def encode_entry(entry: TranscriptEntry) -> str:
+    """Encode one ``TranscriptEntry`` to its NDJSON entry line (no newline).
+
+    The wire shape is the conductor's fresh vocabulary — fields are renamed
+    away from the framework's session-manager schema on purpose: ``schema`` is
+    a namespaced string (``indus/transcript@1``), ``prev`` is the parent link
+    (the framework uses ``parentId``), ``message`` carries the framework
+    message verbatim (through the codec), ``at`` is the ISO timestamp (the
+    framework uses ``timestamp``).
+    """
+    line: dict[str, Any] = {
+        "schema": TRANSCRIPT_SCHEMA,
+        "kind": "entry",
+        "id": entry.id,
+        "prev": entry.parent,
+        "role": entry.role,
+        "message": message_to_dict(entry.content),
+        "at": entry.createdAt,
+    }
+    if entry.meta is not None:
+        line["meta"] = message_to_dict(entry.meta)
+    return _dump_line(line)
+
+
+def encode_head(head: SessionHead) -> str:
+    """Encode the ``SessionHead`` to its NDJSON head line (no newline).
+
+    The head line is written as the *first* record of a session file: it pins
+    the schema and tracks which leaf the session currently points at, so a
+    reader can recover the active branch without scanning for the deepest
+    node. ``kind: "head"`` distinguishes it from entry lines.
+    """
+    return _dump_line(
+        {
+            "schema": TRANSCRIPT_SCHEMA,
+            "kind": "head",
+            "sessionId": head.sessionId,
+            "leaf": head.leaf,
+        }
+    )
+
+
+def _line_to_entry(line: Mapping[str, Any]) -> TranscriptEntry | None:
+    """Re-lift a parsed entry line back into a ``TranscriptEntry``; a line
+    missing its envelope fields is dropped (tolerant parse)."""
+    entry_id = line.get("id")
+    role = line.get("role")
+    at = line.get("at")
+    if not isinstance(entry_id, str) or not isinstance(role, str) or not isinstance(at, str):
+        return None
+    prev = line.get("prev")
+    meta = line.get("meta")
+    return TranscriptEntry(
+        id=entry_id,
+        parent=prev if isinstance(prev, str) else None,
+        role=role,
+        content=message_from_dict(line.get("message")),
+        createdAt=at,
+        meta=dict(meta) if isinstance(meta, Mapping) else None,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedSessionFile:
+    """The result of parsing a whole session file: its head plus its entries
+    (TS ``ParsedSessionFile``)."""
+
+    head: SessionHead | None
+    entries: list[TranscriptEntry]
+
+
+#: Sentinel distinguishing "no head line seen" from a head whose leaf is null.
+_UNSET: Any = object()
+
+
+def parse_session_text(session_id: str, text: str) -> ParsedSessionFile:
+    """Parse the raw text of a conductor session file into a head + entries.
+
+    Tolerant by design: blank lines are skipped, malformed lines are dropped,
+    and lines whose ``schema`` does not match ``indus/transcript@1`` are
+    ignored. The last head line wins (a file should carry exactly one, written
+    first and rewritten on branch). Entries keep file order.
+    """
+    entries: list[TranscriptEntry] = []
+    leaf: Any = _UNSET
+
+    for raw in text.split("\n"):
+        trimmed = raw.strip()
+        if len(trimmed) == 0:
+            continue
+        try:
+            parsed = json.loads(trimmed)
+        except ValueError:
+            continue
+        if not _is_file_line(parsed):
+            continue
+        if parsed["kind"] == "head":
+            # `.get(..., _UNSET)` mirrors TS `leaf = parsed.leaf`: a head line
+            # *without* a leaf field leaves the head unresolved (undefined),
+            # while an explicit `"leaf": null` pins an empty-transcript head.
+            leaf = parsed.get("leaf", _UNSET)
+        else:
+            entry = _line_to_entry(parsed)
+            if entry is not None:
+                entries.append(entry)
+
+    head = None if leaf is _UNSET else SessionHead(sessionId=session_id, leaf=leaf)
+    return ParsedSessionFile(head=head, entries=entries)
+
+
+def _is_file_line(value: Any) -> bool:
+    """Narrow an unknown parsed value to a recognized ``indus/transcript@1``
+    line (TS ``isFileLine``)."""
+    if not isinstance(value, Mapping):
+        return False
+    if value.get("schema") != TRANSCRIPT_SCHEMA:
+        return False
+    return value.get("kind") in ("head", "entry")
+
+
+# ---------------------------------------------------------------------------
+# Conductor ⇄ framework (delegated message resolution)
+# ---------------------------------------------------------------------------
+
+
+def branch_to_messages(branch: Sequence[TranscriptEntry]) -> list[Any]:
+    """Project a resolved transcript branch down to the framework
+    ``AgentMessage`` list the agent loop consumes.
+
+    The branch is the root→leaf node list (the store's reducer produces it).
+    We pull the carried ``content`` payloads and hand them straight to the
+    agent; they are already framework messages. Conductor-only nodes whose
+    payload is not a real message would be filtered by the framework's own
+    ``convert_to_llm`` at call time, so we keep them here and let the loop's
+    converter decide.
+    """
+    return [entry.content for entry in branch]
+
+
+def branch_to_llm_messages(branch: Sequence[TranscriptEntry]) -> list[Any]:
+    """Convert a transcript branch to *LLM-ready* ``Message`` list, delegating
+    entirely to the framework's :func:`indusagi.agent.convert_to_llm`.
+
+    This is the one place that must understand how each message variant
+    (including the framework's custom ``bashExecution``/``branchSummary``/…
+    messages) collapses into a plain LLM message — and that knowledge stays in
+    the framework. The conductor never re-implements it.
+    """
+    return convert_to_llm(branch_to_messages(branch))
+
+
+def import_legacy_file(file_path: str) -> list[TranscriptEntry]:
+    """Lift a *legacy framework session file* into conductor
+    ``TranscriptEntry`` nodes, for one-way migration/import.
+
+    The legacy file is the framework's own internal JSONL format. We do
+    **not** parse its schema ourselves — we call the framework's published
+    loader (or its in-memory text parser), then map only the message-bearing
+    entries onto our envelope. Every framework-internal schema literal stays
+    behind that call.
+
+    Non-message bookkeeping entries (model/thinking changes, labels, raw
+    compaction markers) are dropped from the imported transcript: their effect
+    is already folded into the resolved messages we keep, and the conductor
+    tracks model/thinking in its own state rather than as transcript nodes.
+    """
+    return _map_framework_entries(load_entries_from_file(file_path))
+
+
+def import_legacy_text(text: str) -> list[TranscriptEntry]:
+    """As :func:`import_legacy_file`, but from already-loaded text
+    (testing/import)."""
+    return _map_framework_entries(parse_session_entries(text))
+
+
+def resolve_legacy_messages(file_path: str) -> list[Any]:
+    """Resolve a legacy framework file straight to the ``AgentMessage`` list
+    of its active branch, delegating to the framework's
+    :func:`indusagi.agent.build_session_context`.
+
+    Useful when the goal is to *seed* a fresh conductor session from a legacy
+    one without reproducing its tree: the framework walks its own parent links
+    and applies its own compaction/branch-summary resolution, and we receive a
+    flat message list to re-append as new transcript nodes.
+    """
+    file_entries = load_entries_from_file(file_path)
+    session_entries = [fe for fe in file_entries if _is_session_entry(fe)]
+    context = build_session_context(session_entries)
+    return context.messages
+
+
+def _map_framework_entries(file_entries: Sequence[Mapping[str, Any]]) -> list[TranscriptEntry]:
+    """Map framework ``FileEntry`` records onto conductor entries, preserving
+    the tree links the framework already encodes.
+
+    We translate the framework's ``id``/``parentId``/``timestamp`` onto our
+    ``id``/``parent``/``createdAt``, derive our ``role`` from the carried
+    message, and stash the framework's original entry ``type`` under
+    ``meta["importedFrom"]`` for traceability. Only ``message``-typed entries
+    carry an ``AgentMessage``, so those are the ones we surface as transcript
+    nodes. The carried message stays in whatever representation the framework
+    loader yielded (plain dicts for on-disk files) — parity with the TS
+    import, and the framework's tolerant accessors consume it either way.
+    """
+    out: list[TranscriptEntry] = []
+    for fe in file_entries:
+        if not _is_session_entry(fe):
+            continue
+        if fe.get("type") != "message":
+            continue
+        out.append(
+            TranscriptEntry(
+                id=fe.get("id"),
+                parent=fe.get("parentId"),
+                role=role_for_message(fe.get("message")),
+                content=fe.get("message"),
+                createdAt=fe.get("timestamp"),
+                meta={"importedFrom": fe.get("type")},
+            )
+        )
+    return out
+
+
+def _is_session_entry(entry: Mapping[str, Any]) -> bool:
+    """Separate framework ``SessionEntry`` records (which carry an ``id``)
+    from the file's header line. The header is the framework's ``session``
+    record; everything else is a real entry (TS ``isSessionEntry``)."""
+    return entry.get("type") != "session"