agentbyte 0.44.1__tar.gz → 0.46.0__tar.gz

{agentbyte-0.44.1 → agentbyte-0.46.0}/.gitignore

@@ -72,5 +72,8 @@ data/flatfiles/*
 *.sqlite-shm
 *.writer.lock
 
+# Optimization reports written by notebooks (report.md, report.json, trace.json)
+optim-reports/
+
 # marimo local session cache
 __marimo__/

{agentbyte-0.44.1 → agentbyte-0.46.0}/CHANGELOG.md

@@ -6,6 +6,46 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [0.46.0] - 2026-10-05
+
+### Added
+
+- Evaluation UI: read-only optimization pages (spec 0068 phase 3). The Evaluations home page lists
+  stored optimization runs (suite, optimizer, seed → best, cost); `#/evals/optimizations/<id>`
+  renders the report — proposed changes as seed/best text, per-task outcomes, remaining failures
+  with the judge's reasoning, reflector diagnoses and edits, candidates, cost — with Copy markdown
+  and Download report.md.
+- `GET /api/eval/optimizations?suite=` and `GET /api/eval/optimizations/{id}` (`{run, report,
+  markdown}`). They read the history store directly, so runs recorded for suites outside the
+  server's catalog (e.g. notebook suites) are shown.
+
+## [0.45.0] - 2026-10-05
+
+### Added
+
+- Optimization report (spec 0068): `result.report(title=..., pass_score=...)` /
+  `agentbyte.optim.build_report(trace)` return an `OptimizationReport` — summary, proposed changes
+  (seed vs best text per tuned component), per-task outcomes (`TaskStatus`: fixed, regressed,
+  still_failing, passing), remaining failures with the judge's reasoning, every reflector diagnosis
+  and edit with its outcome, candidates and cost. `to_markdown()` is written for a reviewer or AI
+  coding agent; `save(dir)` writes `report.md`, `report.json` and `trace.json`. Built from the trace
+  alone, so a saved trace reproduces the same report.
+- The optimization trace ends with a `result` event (best, rounds, rollouts, cost, latency).
+- Optimization runs in the evaluation history: `OptimizationRunRecord` and
+  `save_optimization` / `list_optimizations(suite=...)` / `get_optimization` on the memory, SQLite and
+  SQLAlchemy stores; `record.report()` rebuilds the report. Conformance check
+  `optimization_runs_round_trip_per_suite`.
+- CLI: `agentbyte optim report <trace.json | run-id> [--history] [--pass-score] [--format] [--out]`
+  and `agentbyte optim list [--suite] [--history]`.
+
+### Changed
+
+- History database layout version 2 (`STORE_SCHEMA_VERSION`) adds the `optimization_runs` table.
+  Opening a layout-1 file as a writer migrates it; a reader on a layout-1 file asks for one writer
+  open first; Agentbyte 0.44 refuses a layout-2 file. Run/item records keep `SCHEMA_VERSION` 1.
+  The new store methods are not abstract, so stores written against the run-only contract still
+  instantiate (they raise `NotImplementedError` for optimization runs).
+
 ## [0.44.1] - 2026-10-05
 
 ### Added

{agentbyte-0.44.1 → agentbyte-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.44.1
+Version: 0.46.0
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -77,7 +77,7 @@ Description-Content-Type: text/markdown
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.44.1**
+Current release: **0.46.0**
 
 ## Building an Agent
 

{agentbyte-0.44.1 → agentbyte-0.46.0}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.44.1**
+Current release: **0.46.0**
 
 ## Building an Agent
 

agentbyte-0.46.0/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.46.0"
+VERSION = __version__

{agentbyte-0.44.1 → agentbyte-0.46.0}/src/agentbyte/cli/main.py

@@ -9,6 +9,7 @@ import sys
 from agentbyte.__about__ import VERSION
 from agentbyte.catalog import BaseInstructionCatalog
 from agentbyte.cli.eval_commands import add_eval_parser, cmd_eval
+from agentbyte.cli.optim_commands import add_optim_parser, cmd_optim
 from agentbyte.cli.loading import ObjectImportError, import_object
 
 
@@ -302,6 +303,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     # eval
     add_eval_parser(subparsers)
+    add_optim_parser(subparsers)
 
     return parser
 
@@ -329,6 +331,10 @@ def main() -> None:
         if not args.eval_command:
             parser.parse_args(["eval", "--help"])
         sys.exit(cmd_eval(args))
+    if args.command == "optim":
+        if not args.optim_command:
+            parser.parse_args(["optim", "--help"])
+        sys.exit(cmd_optim(args))
 
     parser.print_help()
     sys.exit(1)

agentbyte-0.46.0/src/agentbyte/cli/optim_commands.py

@@ -0,0 +1,160 @@
+"""``agentbyte optim`` sub-commands: report and list optimization runs (spec 0068).
+
+``report`` prints or saves the report of an optimization run, read from a saved trace file
+(``trace.json``) or from a run stored in the evaluation history. ``list`` shows the stored runs,
+optionally for one suite.
+
+Exit codes: 0 = done, 2 = the source could not be read or is not an optimization run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+EXIT_OK = 0
+EXIT_ERROR = 2
+
+DEFAULT_HISTORY = "eval.sqlite"
+
+
+class _CliError(Exception):
+    """A configuration or input problem reported with exit code 2."""
+
+
+def add_optim_parser(subparsers: Any) -> None:
+    """Register ``agentbyte optim`` and its sub-commands."""
+    optim_parser = subparsers.add_parser("optim", help="Report optimization runs")
+    optim_sub = optim_parser.add_subparsers(dest="optim_command", metavar="<subcommand>")
+    history_help = f"SQLite evaluation history file (default: ./{DEFAULT_HISTORY})"
+
+    report_parser = optim_sub.add_parser(
+        "report", help="Print or save the report of an optimization run"
+    )
+    report_parser.add_argument(
+        "source",
+        help="A trace file (*.json, from report.save() or trace.save()) or a stored run ID",
+    )
+    report_parser.add_argument("--history", default=DEFAULT_HISTORY, help=history_help)
+    report_parser.add_argument(
+        "--pass-score", type=float, default=None,
+        help="Score a task needs to pass (default: the stored run's, else 10.0)",
+    )
+    report_parser.add_argument("--title", default=None, help="Report title")
+    report_parser.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    report_parser.add_argument(
+        "--out", default=None,
+        help="Directory to write report.md, report.json and trace.json instead of printing",
+    )
+
+    list_parser = optim_sub.add_parser("list", help="List optimization runs in a history file")
+    list_parser.add_argument("--suite", default=None, help="Only runs recorded for this suite")
+    list_parser.add_argument("--history", default=DEFAULT_HISTORY, help=history_help)
+    list_parser.add_argument("--limit", type=int, default=50)
+    list_parser.add_argument("--format", choices=["text", "json"], default="text")
+
+
+def cmd_optim(args: argparse.Namespace) -> int:
+    """Dispatch ``agentbyte optim <subcommand>``."""
+    commands = {"report": _cmd_report, "list": _cmd_list}
+    command = commands.get(getattr(args, "optim_command", None) or "")
+    if command is None:
+        print("Usage: agentbyte optim <report|list>", file=sys.stderr)
+        return EXIT_ERROR
+    try:
+        return command(args)
+    except _CliError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+def _cmd_report(args: argparse.Namespace) -> int:
+    path = Path(args.source)
+    if path.suffix == ".json" or path.is_file():
+        report = _report_from_trace(path, args)
+    else:
+        report = asyncio.run(_report_from_history(args))
+    return _emit(report, args)
+
+
+def _report_from_trace(path: Path, args: argparse.Namespace) -> Any:
+    from agentbyte.optim import DEFAULT_PASS_SCORE, build_report, load_trace
+
+    if not path.is_file():
+        raise _CliError(f"No trace file at {path}")
+    try:
+        return build_report(
+            load_trace(path),
+            title=args.title or path.parent.name or "Optimization run",
+            pass_score=DEFAULT_PASS_SCORE if args.pass_score is None else args.pass_score,
+        )
+    except (ValueError, KeyError) as exc:
+        raise _CliError(f"{path} is not a reportable optimization trace: {exc}") from exc
+
+
+async def _report_from_history(args: argparse.Namespace) -> Any:
+    async with _open_history(args.history) as store:
+        record = await store.get_optimization(args.source)
+    if record is None:
+        raise _CliError(f"No optimization run {args.source!r} in {args.history}")
+    updates = {k: v for k, v in (("title", args.title), ("pass_score", args.pass_score)) if v is not None}
+    return record.model_copy(update=updates).report()
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    records = asyncio.run(_list(args))
+    if args.format == "json":
+        print(json.dumps([r.model_dump(mode="json", exclude={"trace"}) for r in records], indent=2))
+        return EXIT_OK
+    if not records:
+        print("No optimization runs recorded" + (f" for suite {args.suite!r}." if args.suite else "."))
+        return EXIT_OK
+    for r in records:
+        cost = "-" if r.cost_usd is None else f"${r.cost_usd:.4f}"
+        print(
+            f"{r.id}  {r.created_at:%Y-%m-%d %H:%M}  {r.suite:<20} {r.optimizer or '?':<22} "
+            f"{_avg(r.seed_avg)} -> {_avg(r.best_avg)}  best={r.best}  rollouts={r.eval_count}  {cost}"
+        )
+    return EXIT_OK
+
+
+async def _list(args: argparse.Namespace) -> list[Any]:
+    async with _open_history(args.history) as store:
+        return await store.list_optimizations(suite=args.suite, limit=args.limit)
+
+
+def _open_history(history: str) -> Any:
+    from agentbyte.eval.history import EvalHistoryError, SQLiteEvalRunStore
+
+    if not Path(history).is_file():
+        raise _CliError(f"No evaluation history at {history}")
+
+    class _Reader:
+        async def __aenter__(self) -> Any:
+            self.store = SQLiteEvalRunStore(history, writer=False)
+            try:
+                return await self.store.__aenter__()
+            except EvalHistoryError as exc:
+                raise _CliError(f"Cannot read {history}: {exc}") from exc
+
+        async def __aexit__(self, *exc: Any) -> None:
+            await self.store.__aexit__(*exc)
+
+    return _Reader()
+
+
+def _avg(value: float | None) -> str:
+    return "—" if value is None else f"{value:.1f}"
+
+
+def _emit(report: Any, args: argparse.Namespace) -> int:
+    if args.out:
+        out = report.save(args.out)
+        print(f"Wrote {out / 'report.md'}, {out / 'report.json'} and {out / 'trace.json'}")
+        return EXIT_OK
+    print(report.to_json() if args.format == "json" else report.to_markdown(), end="")
+    return EXIT_OK

{agentbyte-0.44.1 → agentbyte-0.46.0}/src/agentbyte/eval/history/__init__.py

@@ -22,11 +22,13 @@ from .errors import (
 from .models import (
     EVIDENCE_VERSION,
     SCHEMA_VERSION,
+    STORE_SCHEMA_VERSION,
     CaptureMode,
     EvalItemRecord,
     EvalRunRecord,
     EvidenceStatus,
     ItemState,
+    OptimizationRunRecord,
     Redactor,
     RunStatus,
     StructuredPayload,
@@ -50,6 +52,7 @@ def __getattr__(name: str) -> Any:
 __all__ = [
     "EVIDENCE_VERSION",
     "SCHEMA_VERSION",
+    "STORE_SCHEMA_VERSION",
     "CaptureMode",
     "EvalHistoryConflictError",
     "EvalHistoryError",
@@ -67,6 +70,7 @@ __all__ = [
     "EvidenceStatus",
     "ItemState",
     "MemoryEvalRunStore",
+    "OptimizationRunRecord",
     "Redactor",
     "RunStatus",
     "SQLiteEvalRunStore",

{agentbyte-0.44.1 → agentbyte-0.46.0}/src/agentbyte/eval/history/conformance.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Awaitable, Callable
 from contextlib import AbstractAsyncContextManager
+from typing import Any
 
 from pydantic import BaseModel
 
@@ -32,7 +33,7 @@ from .errors import (
     EvalRunNotFoundError,
     EvalSerializationError,
 )
-from .models import EvalItemRecord, EvalRunRecord, StructuredPayload
+from .models import EvalItemRecord, EvalRunRecord, OptimizationRunRecord, StructuredPayload
 from .recorder import EvalRunRecorder
 from .store import EvalRunStore
 
@@ -322,6 +323,40 @@ async def check_recorder_bounds_concurrency_without_lost_writes(store: EvalRunSt
     assert [i.overall for i in items] == [float(i % 10) for i in range(16)]
 
 
+def _optimization_trace(seed_avg: float, best_avg: float) -> Any:
+    """A minimal reportable trace: seed, one better candidate, and the closing result."""
+    from agentbyte.optim.trace import OptimizationTrace  # optim depends on eval; import late
+
+    trace = OptimizationTrace()
+    trace.record("candidate", 0, name="seed", parent=None, rationale="seed", avg=seed_avg,
+                 eligible=True, task_scores={"t": seed_avg}, components={"instructions": "old"})
+    trace.record("candidate", 1, name="next", parent="seed", rationale="r", avg=best_avg,
+                 eligible=True, task_scores={"t": best_avg}, components={"instructions": "new"})
+    trace.record("result", 1, best="next", best_avg=best_avg, optimizer="Scripted", rounds=1,
+                 eval_count=2, cost={"total": {"usd": 0.25}})
+    return trace
+
+
+async def check_optimization_runs_round_trip_per_suite(store: EvalRunStore) -> None:
+    first = OptimizationRunRecord.from_trace(_optimization_trace(2.0, 6.0), suite="alpha")
+    second = OptimizationRunRecord.from_trace(_optimization_trace(3.0, 9.0), suite="beta")
+    third = OptimizationRunRecord.from_trace(_optimization_trace(6.0, 8.0), suite="alpha")
+    for record in (first, second, third):
+        assert await store.save_optimization(record) == record
+    await _raises(EvalHistoryConflictError, store.save_optimization(first))
+
+    listed = await store.list_optimizations(suite="alpha")
+    assert [r.id for r in listed] == [third.id, first.id]
+    assert all(r.trace is None for r in listed)
+    assert [r.id for r in await store.list_optimizations(limit=1, offset=1)] == [second.id]
+
+    loaded = await store.get_optimization(first.id)
+    assert loaded == first
+    assert (loaded.best, loaded.best_avg, loaded.cost_usd) == ("next", 6.0, 0.25)
+    assert loaded.report().changed_components[0].best == "new"
+    assert await store.get_optimization("missing") is None
+
+
 CHECKS: dict[str, Check] = {
     name.removeprefix("check_"): check
     for name, check in dict(globals()).items()

{agentbyte-0.44.1 → agentbyte-0.46.0}/src/agentbyte/eval/history/models.py

@@ -27,6 +27,9 @@ from .errors import EvalSchemaVersionError, EvalSerializationError
 SCHEMA_VERSION = 1
 """Version of the stored run/item record layout."""
 
+STORE_SCHEMA_VERSION = 2
+"""Version of the history database layout. 2 adds the ``optimization_runs`` table (spec 0068)."""
+
 EVIDENCE_VERSION = 1
 """Version of the serialized full-capture evidence envelope."""
 
@@ -300,6 +303,72 @@ def _restore_structured(value: Any) -> None:
             _restore_structured(item)
 
 
+class OptimizationRunRecord(BaseModel):
+    """One optimization run, stored next to the suite it optimized (spec 0068).
+
+    The summary fields are derived from the run's trace; ``trace`` is the full
+    ``OptimizationTrace.to_dict()`` and is ``None`` in listings. ``report()`` rebuilds the
+    ``OptimizationReport`` from the stored trace.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    suite: str
+    created_at: datetime = Field(default_factory=utc_now)
+    title: str = "Optimization run"
+    optimizer: str | None = None
+    seed: str
+    best: str
+    seed_avg: float | None = None
+    best_avg: float | None = None
+    rounds: int = 0
+    eval_count: int | None = None
+    cost_usd: float | None = None
+    pass_score: float = 10.0
+    trace: dict[str, Any] | None = None
+
+    @classmethod
+    def from_result(
+        cls, result: Any, *, suite: str, pass_score: float = 10.0, title: str | None = None
+    ) -> OptimizationRunRecord:
+        """Record an ``OptimizationResult`` under ``suite``."""
+        return cls.from_trace(result.trace, suite=suite, pass_score=pass_score, title=title)
+
+    @classmethod
+    def from_trace(
+        cls, trace: Any, *, suite: str, pass_score: float = 10.0, title: str | None = None
+    ) -> OptimizationRunRecord:
+        """Record an ``OptimizationTrace`` (live or loaded) under ``suite``."""
+        from agentbyte.optim.report import build_report
+
+        report = build_report(trace, title=title or suite, pass_score=pass_score)
+        return cls(
+            suite=suite,
+            title=report.title,
+            optimizer=report.optimizer,
+            seed=report.seed,
+            best=report.best,
+            seed_avg=report.seed_avg,
+            best_avg=report.best_avg,
+            rounds=report.rounds,
+            eval_count=report.eval_count,
+            cost_usd=((report.cost or {}).get("total") or {}).get("usd"),
+            pass_score=pass_score,
+            trace=json.loads(trace.to_json(indent=None)),
+        )
+
+    def report(self) -> Any:
+        """The ``OptimizationReport`` rebuilt from the stored trace."""
+        if self.trace is None:
+            raise ValueError("This record has no trace; load it with get_optimization(id)")
+        from agentbyte.optim.report import build_report
+        from agentbyte.optim.trace import OptimizationTrace
+
+        trace = OptimizationTrace(events=list(self.trace.get("events", [])))
+        return build_report(trace, title=self.title, pass_score=self.pass_score)
+
+
 def deserialize_evidence(text: str) -> EvalScore:
     """Load evidence JSON as data only; unknown versions raise."""
     envelope = json.loads(text)
@@ -315,7 +384,9 @@ __all__ = [
     "ACTIVE_RUN_STATUSES",
     "EVIDENCE_VERSION",
     "SCHEMA_VERSION",
+    "STORE_SCHEMA_VERSION",
     "TERMINAL_ITEM_STATES",
+    "OptimizationRunRecord",
     "CaptureMode",
     "EvalItemRecord",
     "EvalRunRecord",

{agentbyte-0.44.1 → agentbyte-0.46.0}/src/agentbyte/eval/history/sql.py

@@ -51,13 +51,14 @@ from .errors import (
 from .models import (
     ACTIVE_RUN_STATUSES,
     SCHEMA_VERSION,
+    STORE_SCHEMA_VERSION,
     EvalItemRecord,
     EvalRunRecord,
     RunStatus,
     deserialize_evidence,
     serialize_evidence,
 )
-from .store import EvalRunStore, _uninterrupted
+from .store import EvalRunStore, _uninterrupted, dump_optimization, load_optimization
 from .transitions import (
     admit,
     admitted_duplicate,
@@ -77,7 +78,11 @@ SessionFactory = Callable[[], "AbstractAsyncContextManager[AsyncSession] | Async
 
 # Forward migrations keyed by the version they upgrade from; each is a callable
 # run on the sync connection inside the opening transaction.
-_MIGRATIONS: dict[int, Callable[[Any, "HistoryTables"], None]] = {}
+_MIGRATIONS: dict[int, Callable[[Any, "HistoryTables"], None]] = {
+    # spec 0068: optimization runs stored next to suites. checkfirst: a user-managed schema
+    # built from history_metadata() may already have the table.
+    1: lambda connection, tables: tables.optimizations.create(connection, checkfirst=True),
+}
 
 
 class HistoryTables:
@@ -109,6 +114,14 @@ class HistoryTables:
             Column("payload", Text, nullable=False),
             Column("evidence", Text),
         )
+        self.optimizations = Table(
+            "optimization_runs", self.metadata,
+            Column("seq", Integer, primary_key=True, autoincrement=True),
+            Column("id", String(64), nullable=False, unique=True),
+            Column("suite", Text, nullable=False, index=True),
+            Column("payload", Text, nullable=False),
+            Column("trace", Text),
+        )
 
 
 def history_metadata(schema: str | None = None) -> MetaData:
@@ -267,16 +280,18 @@ class SqlEvalRunStore(EvalRunStore):
             if not (self.writer and self.create_schema):
                 raise EvalSchemaVersionError("Evaluation history tables are not initialized")
             tables.metadata.create_all(connection)
-            connection.execute(insert(tables.meta).values(key="schema_version", value=str(SCHEMA_VERSION)))
+            connection.execute(
+                insert(tables.meta).values(key="schema_version", value=str(STORE_SCHEMA_VERSION))
+            )
             return
         version = int(row[0])
-        if version > SCHEMA_VERSION:
+        if version > STORE_SCHEMA_VERSION:
             raise EvalSchemaVersionError(
-                f"History schema {version} is newer than supported {SCHEMA_VERSION}"
+                f"History schema {version} is newer than supported {STORE_SCHEMA_VERSION}"
             )
-        if version < SCHEMA_VERSION and not self.writer:
+        if version < STORE_SCHEMA_VERSION and not self.writer:
             raise EvalSchemaVersionError(f"History schema {version} needs migration; open once as writer")
-        while version < SCHEMA_VERSION:
+        while version < STORE_SCHEMA_VERSION:
             if version not in _MIGRATIONS:
                 raise EvalSchemaVersionError(f"No migration from history schema {version}")
             _MIGRATIONS[version](connection, tables)
@@ -565,5 +580,35 @@ class SqlEvalRunStore(EvalRunStore):
 
         return await self._write(run_id, "delete evaluation run", body)
 
+    async def save_optimization(self, record):
+        table = self.tables.optimizations
+        payload, trace = dump_optimization(record)
+
+        async def body(session: AsyncSession) -> Any:
+            existing = await session.execute(select(table.c.id).where(table.c.id == record.id))
+            if existing.first() is not None:
+                raise EvalHistoryConflictError(f"Optimization run {record.id} already exists")
+            await session.execute(
+                insert(table).values(id=record.id, suite=record.suite, payload=payload, trace=trace)
+            )
+            return load_optimization(payload, trace)
+
+        return await self._write(None, "save optimization run", body)
+
+    async def list_optimizations(self, *, suite=None, limit=50, offset=0):
+        table = self.tables.optimizations
+        query = select(table.c.payload)
+        if suite is not None:
+            query = query.where(table.c.suite == suite)
+        query = query.order_by(table.c.seq.desc()).limit(max(0, limit)).offset(max(0, offset))
+        return [load_optimization(row[0], None) for row in await self._read(None, query)]
+
+    async def get_optimization(self, optimization_id):
+        table = self.tables.optimizations
+        rows = await self._read(
+            None, select(table.c.payload, table.c.trace).where(table.c.id == optimization_id)
+        )
+        return load_optimization(rows[0][0], rows[0][1]) if rows else None
+
 
 __all__ = ["HistoryTables", "SessionFactory", "SqlEvalRunStore", "history_metadata"]

{agentbyte-0.44.1 → agentbyte-0.46.0}/src/agentbyte/eval/history/sqlite.py

@@ -23,13 +23,14 @@ from .errors import (
 from .models import (
     ACTIVE_RUN_STATUSES,
     SCHEMA_VERSION,
+    STORE_SCHEMA_VERSION,
     EvalItemRecord,
     EvalRunRecord,
     RunStatus,
     deserialize_evidence,
     serialize_evidence,
 )
-from .store import EvalRunStore, _uninterrupted
+from .store import EvalRunStore, _uninterrupted, dump_optimization, load_optimization
 from .transitions import (
     admit,
     admitted_duplicate,
@@ -56,8 +57,16 @@ _SCHEMA_V1 = (
 )
 
 # Forward migrations keyed by the version they upgrade from. Each runs inside the
-# opening transaction, so a failure leaves the previous schema untouched.
-_MIGRATIONS: dict[int, tuple[str, ...]] = {}
+# opening transaction, so a failure leaves the previous schema untouched. A new file is
+# created at version 1 and migrated forward like an existing one.
+_MIGRATIONS: dict[int, tuple[str, ...]] = {
+    1: (  # spec 0068: optimization runs stored next to suites
+        "CREATE TABLE optimization_runs ("
+        "seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL UNIQUE, suite TEXT NOT NULL, "
+        "payload TEXT NOT NULL, trace TEXT)",
+        "CREATE INDEX optimization_runs_suite ON optimization_runs(suite)",
+    ),
+}
 
 
 def _admission_key(run: EvalRunRecord) -> str | None:
@@ -165,15 +174,15 @@ class SQLiteEvalRunStore(EvalRunStore):
                 version = 1
             else:
                 version = int(row[0])
-            if version > SCHEMA_VERSION:
+            if version > STORE_SCHEMA_VERSION:
                 raise EvalSchemaVersionError(
-                    f"History schema {version} is newer than supported {SCHEMA_VERSION}"
+                    f"History schema {version} is newer than supported {STORE_SCHEMA_VERSION}"
                 )
-            if version < SCHEMA_VERSION and not self.writer:
+            if version < STORE_SCHEMA_VERSION and not self.writer:
                 raise EvalSchemaVersionError(
                     f"History schema {version} needs migration; open once as writer"
                 )
-            while version < SCHEMA_VERSION:
+            while version < STORE_SCHEMA_VERSION:
                 if version not in _MIGRATIONS:
                     raise EvalSchemaVersionError(f"No migration from history schema {version}")
                 for statement in _MIGRATIONS[version]:
@@ -452,5 +461,36 @@ class SQLiteEvalRunStore(EvalRunStore):
 
         return await self._write(run_id, "delete evaluation run", body)
 
+    async def save_optimization(self, record):
+        payload, trace = dump_optimization(record)
+
+        async def body(connection: Any) -> Any:
+            async with connection.execute(
+                "SELECT 1 FROM optimization_runs WHERE id = ?", (record.id,)
+            ) as cursor:
+                if await cursor.fetchone() is not None:
+                    raise EvalHistoryConflictError(f"Optimization run {record.id} already exists")
+            await connection.execute(
+                "INSERT INTO optimization_runs(id, suite, payload, trace) VALUES (?, ?, ?, ?)",
+                (record.id, record.suite, payload, trace),
+            )
+            return load_optimization(payload, trace)
+
+        return await self._write(None, "save optimization run", body)
+
+    async def list_optimizations(self, *, suite=None, limit=50, offset=0):
+        sql, params = "SELECT payload FROM optimization_runs", []
+        if suite is not None:
+            sql, params = sql + " WHERE suite = ?", [suite]
+        sql += " ORDER BY seq DESC LIMIT ? OFFSET ?"
+        rows = await self._read(None, sql, (*params, max(0, limit), max(0, offset)))
+        return [load_optimization(row[0], None) for row in rows]
+
+    async def get_optimization(self, optimization_id):
+        rows = await self._read(
+            None, "SELECT payload, trace FROM optimization_runs WHERE id = ?", (optimization_id,)
+        )
+        return load_optimization(rows[0][0], rows[0][1]) if rows else None
+
 
 __all__ = ["SQLiteEvalRunStore"]