feat(cp4): JSONL trace persistence (append_trace / read_traces)

proteus/runtime/__init__.py

@@ -1,7 +1,15 @@
-"""proteus.runtime — session orchestration, trace, and metrics."""
+"""proteus.runtime — session orchestration, trace, metrics, and I/O."""
 
 from proteus.runtime.session import SessionRunner
 from proteus.runtime.trace import SessionTrace, TurnTrace
 from proteus.runtime.metrics import compute_metrics
+from proteus.runtime.io import append_trace, read_traces
 
-__all__ = ["SessionRunner", "SessionTrace", "TurnTrace", "compute_metrics"]
+__all__ = [
+    "SessionRunner",
+    "SessionTrace",
+    "TurnTrace",
+    "compute_metrics",
+    "append_trace",
+    "read_traces",
+]

proteus/runtime/io.py

@@ -0,0 +1,51 @@
+"""Persist and reload :class:`SessionTrace` as JSONL.
+
+A run file is JSON Lines: one ``SessionTrace`` JSON object per line. Appending
+lets a batch of sessions accumulate into a single file; one CLI ``run`` writes
+exactly one line. This is the analysis/handoff boundary described in the spec
+(§7: "세션당 JSONL 1개").
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from proteus.runtime.trace import SessionTrace
+
+
+def append_trace(trace: SessionTrace, path: str | Path) -> Path:
+    """Append one ``SessionTrace`` as a JSON line to *path*.
+
+    Creates parent directories if needed.
+
+    Args:
+        trace: The session trace to persist.
+        path: Destination ``.jsonl`` file (created/appended).
+
+    Returns:
+        The :class:`~pathlib.Path` written to.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(trace.model_dump_json() + "\n")
+    return path
+
+
+def read_traces(path: str | Path) -> list[SessionTrace]:
+    """Read all ``SessionTrace`` records from a JSONL *path*.
+
+    Blank lines are skipped.
+
+    Args:
+        path: A ``.jsonl`` file written by :func:`append_trace`.
+
+    Returns:
+        The traces in file order.
+    """
+    path = Path(path)
+    return [
+        SessionTrace.model_validate_json(line)
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]

tests/runtime/test_io.py

@@ -0,0 +1,43 @@
+from proteus.agents import VanillaAgent
+from proteus.providers import FakeProvider
+from proteus.runtime import SessionRunner, append_trace, read_traces
+
+
+def _trace(seed):
+    agent = VanillaAgent(FakeProvider(responses=["ACTION: up"], model_name="fake-1"))
+    return SessionRunner(
+        "predator_evade", agent, seed=seed, play_turns=4, use_probe=False,
+    ).run()
+
+
+def test_append_then_read_roundtrips_one_trace(tmp_path):
+    path = tmp_path / "runs" / "session.jsonl"
+    written = append_trace(_trace(42), path)
+    assert written.exists()
+    traces = read_traces(path)
+    assert len(traces) == 1
+    assert traces[0].scenario == "predator_evade"
+    assert traces[0].model == "fake-1"
+
+
+def test_append_accumulates_multiple_sessions(tmp_path):
+    path = tmp_path / "session.jsonl"
+    append_trace(_trace(1), path)
+    append_trace(_trace(2), path)
+    traces = read_traces(path)
+    assert len(traces) == 2
+    assert [t.seed for t in traces] == [1, 2]
+
+
+def test_read_ignores_blank_lines(tmp_path):
+    path = tmp_path / "s.jsonl"
+    append_trace(_trace(7), path)
+    with path.open("a", encoding="utf-8") as f:
+        f.write("\n")  # trailing blank line
+    assert len(read_traces(path)) == 1
+
+
+def test_append_creates_parent_dirs(tmp_path):
+    path = tmp_path / "deep" / "nested" / "s.jsonl"
+    append_trace(_trace(3), path)
+    assert path.exists()