semora-fork 0.1.0__tar.gz

semora_fork-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+
+
+# Local tool/editor state — machine-specific, never pushed.
+.claude/
+.codecanvas/
+.vscode/
+
+
+# Superpowers design/spec scratch — working notes, not project documentation.
+docs/superpowers/
+
+# 로컬 자격증명 — 절대 커밋 금지.
+a.txt
+*.token

semora_fork-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.5
+Name: semora-fork
+Version: 0.1.0
+Summary: Fork a conversation from before one injected input, under different controls.
+Project-URL: Homepage, https://github.com/donggyun112/semora
+Project-URL: Source, https://github.com/donggyun112/semora
+Project-URL: Changelog, https://github.com/donggyun112/semora/blob/main/CHANGELOG.md
+Author: donggyun112
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: langchain-core<2,>=1
+Requires-Dist: semora-store==0.1.0
+Requires-Dist: semora==0.1.0

semora_fork-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "semora-fork"
+version = "0.1.0"
+description = "Fork a conversation from before one injected input, under different controls."
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "donggyun112" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+urls = { Homepage = "https://github.com/donggyun112/semora", Source = "https://github.com/donggyun112/semora", Changelog = "https://github.com/donggyun112/semora/blob/main/CHANGELOG.md" }
+dependencies = [
+  "langchain-core>=1,<2",
+  "semora==0.1.0",
+  "semora-store==0.1.0",
+]
+# Assembly over the core's public primitives: the ledger keeps the pre-screen original, the
+# transcript rewinds by branch, controls are per-call arguments. This package only walks those
+# seams; putting the walk inside the core would freeze one composition into the contract.
+
+[tool.uv.sources]
+semora = { workspace = true }
+semora-store = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semora_fork"]

semora_fork-0.1.0/src/semora_fork/__init__.py

@@ -0,0 +1,214 @@
+"""Fork a conversation from just before one injected input.
+
+The core keeps the pieces apart on purpose: the ledger holds each input's pre-screen
+original, the transcript rewinds by preserved branch, and controls arrive as call
+arguments. Forking is therefore composition, not a runtime feature — this package walks
+those seams and adds no authority of its own. The source run's ledger is never touched:
+what actually went out stays the record.
+"""
+
+from datetime import UTC, datetime
+from typing import Any, NamedTuple
+
+from langchain_core.language_models import BaseChatModel
+from semora import AgentRuntime
+from semora.contracts import Agent, Tools
+from semora.controls import Controls
+from semora.history import decode_pending_input
+from semora.transcript import SCHEMA_VERSION, entry_id, messages_at
+from semora_store import ExecutionStore, Transcript
+
+__all__ = [
+    "EventCheckpoint",
+    "ForkCoordinate",
+    "fork_event",
+    "fork_run",
+    "read_event_checkpoint",
+    "record_event_checkpoint",
+]
+
+
+class ForkCoordinate(NamedTuple):
+    """One replayable position attached to an observation edge."""
+
+    from_run_id: str
+    origin_id: str | None
+    leaf_uuid: str | None
+
+
+class EventCheckpoint(NamedTuple):
+    """Durable before/after transcript coordinates for one observation."""
+
+    event_id: str
+    conversation_id: str
+    before: ForkCoordinate
+    after: ForkCoordinate
+
+
+def _coordinate_payload(coordinate: ForkCoordinate) -> dict[str, str | None]:
+    return {
+        "from_run_id": coordinate.from_run_id,
+        "origin_id": coordinate.origin_id,
+        "leaf_uuid": coordinate.leaf_uuid,
+    }
+
+
+def _decode_coordinate(payload: object) -> ForkCoordinate:
+    if not isinstance(payload, dict):
+        raise TypeError("fork checkpoint coordinate must be a mapping")
+    from_run_id = payload.get("from_run_id")
+    origin_id = payload.get("origin_id")
+    leaf_uuid = payload.get("leaf_uuid")
+    if not isinstance(from_run_id, str) or not from_run_id:
+        raise TypeError("fork checkpoint coordinate has no source run")
+    if origin_id is not None and not isinstance(origin_id, str):
+        raise TypeError("fork checkpoint origin must be a string or None")
+    if leaf_uuid is not None and not isinstance(leaf_uuid, str):
+        raise TypeError("fork checkpoint leaf must be a string or None")
+    return ForkCoordinate(from_run_id, origin_id, leaf_uuid)
+
+
+async def record_event_checkpoint(
+    transcript: Transcript,
+    checkpoint: EventCheckpoint,
+) -> bool:
+    """Append one immutable event-to-state mapping to the conversation transcript."""
+    body = {
+        "type": "fork_checkpoint",
+        "event_id": checkpoint.event_id,
+        "before": _coordinate_payload(checkpoint.before),
+        "after": _coordinate_payload(checkpoint.after),
+    }
+    return await transcript.append(
+        {
+            "uuid": entry_id(None, body),
+            "conversation_id": checkpoint.conversation_id,
+            "timestamp": datetime.now(UTC).isoformat(),
+            "schema_version": SCHEMA_VERSION,
+            **body,
+        }
+    )
+
+
+async def read_event_checkpoint(
+    transcript: Transcript,
+    conversation_id: str,
+    event_id: str,
+) -> EventCheckpoint:
+    """Read the newest durable mapping for one event identity."""
+    entries = await transcript.read(conversation_id)
+    entry = next(
+        (
+            item
+            for item in reversed(entries)
+            if item.get("type") == "fork_checkpoint" and item.get("event_id") == event_id
+        ),
+        None,
+    )
+    if entry is None:
+        raise ValueError(f"conversation {conversation_id!r} has no fork checkpoint {event_id!r}")
+    return EventCheckpoint(
+        event_id,
+        conversation_id,
+        _decode_coordinate(entry.get("before")),
+        _decode_coordinate(entry.get("after")),
+    )
+
+
+async def fork_run(
+    runtime: AgentRuntime,
+    store: ExecutionStore,
+    *,
+    from_run_id: str,
+    origin_id: str,
+    run_id: str,
+    model: BaseChatModel | Agent,
+    tools: Tools | str | None = None,
+    controls: Controls | None = None,
+    conversation_id: str | None = None,
+    **options: Any,
+) -> dict[str, Any]:
+    """Re-run the conversation from just before ``origin_id`` entered model context.
+
+    The pre-screen original is read from ``from_run_id``'s ledger and enqueued for the new
+    ``run_id``, so it passes through whatever ``controls`` this call supplies — the fork
+    screens, records, and announces it like any live input. The rewind is
+    ``run(history=...)``'s own branch-preserving replace: the source branch stays
+    observable, the conversation head moves to the fork.
+
+    Raises ``ValueError`` when the ledger has no such input or it never reached model
+    context — either way there is no injection point to fork from.
+    """
+    records = await store.list_inputs(from_run_id)
+    record = next((r for r in records if r.input_id == origin_id), None)
+    if record is None:
+        raise ValueError(f"run {from_run_id!r} has no ledger record for input {origin_id!r}")
+    original = decode_pending_input(record.value)
+
+    conversation = conversation_id or from_run_id
+    history = await runtime.committed_history(from_run_id, conversation)
+    cut = next((i for i, message in enumerate(history) if message.id == origin_id), None)
+    if cut is None:
+        raise ValueError(f"input {origin_id!r} never entered the model context of {conversation!r}")
+
+    await runtime.submit(run_id, original, conversation_id=conversation)
+    return await runtime.run(
+        run_id,
+        model,
+        tools,
+        controls=controls,
+        conversation_id=conversation,
+        history=list(history[:cut]),
+        **options,
+    )
+
+
+async def fork_event(
+    runtime: AgentRuntime,
+    store: ExecutionStore,
+    transcript: Transcript,
+    *,
+    event_id: str,
+    edge: str,
+    run_id: str,
+    model: BaseChatModel | Agent,
+    tools: Tools | str | None = None,
+    controls: Controls | None = None,
+    conversation_id: str,
+    **options: Any,
+) -> dict[str, Any]:
+    """Fork from the durable coordinate attached to one observation edge.
+
+    A before edge with an input origin reuses :func:`fork_run`, so the source ledger's
+    pre-screen original crosses the new controls. Other coordinates continue from their
+    explicit transcript leaf without copying source-run effect records.
+    """
+    if edge not in {"before", "after"}:
+        raise ValueError("edge must be 'before' or 'after'")
+    checkpoint = await read_event_checkpoint(transcript, conversation_id, event_id)
+    coordinate = checkpoint.before if edge == "before" else checkpoint.after
+    if edge == "before" and coordinate.origin_id is not None:
+        return await fork_run(
+            runtime,
+            store,
+            from_run_id=coordinate.from_run_id,
+            origin_id=coordinate.origin_id,
+            run_id=run_id,
+            model=model,
+            tools=tools,
+            controls=controls,
+            conversation_id=checkpoint.conversation_id,
+            **options,
+        )
+
+    entries = await transcript.read(checkpoint.conversation_id)
+    history = messages_at(entries, coordinate.leaf_uuid)
+    return await runtime.run(
+        run_id,
+        model,
+        tools,
+        controls=controls,
+        conversation_id=checkpoint.conversation_id,
+        history=history,
+        **options,
+    )