Add sandboxed code migration agent cookbook

Author: kkahadze-oai

authors.yaml

@@ -3,6 +3,11 @@
 # You can optionally customize how your information shows up cookbook.openai.com over here.
 # If your information is not present here, it will be pulled from your GitHub profile.
 
+kkahadze-oai:
+  name: "Konstantine Kahadze"
+  website: "https://www.linkedin.com/in/kahadze/"
+  avatar: "https://avatars.githubusercontent.com/kkahadze-oai"
+
 zhenweig-cerebras:
   name: "Zhenwei Gao"
   website: "https://www.linkedin.com/in/zhenwei-gao/"

examples/agents_sdk/sandboxed-code-migration/.gitignore

@@ -0,0 +1,6 @@
+outputs/*
+!outputs/.gitkeep
+.env.local
+__pycache__/
+.pytest_cache/
+.venv/

examples/agents_sdk/sandboxed-code-migration/assets/sandbox-as-a-tool-architecture.svg

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+EXAMPLE_ROOT = Path(__file__).resolve().parent
+
+EXPECTED_PATCH_MARKERS = {
+    "support_reply_service": [
+        "customer_support_bot/client.py",
+        "customer_support_bot/replies.py",
+    ],
+    "case_summary_service": [
+        "case_summary_service/client.py",
+        "case_summary_service/summaries.py",
+    ],
+}
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    with path.open(encoding="utf-8") as handle:
+        payload = json.load(handle)
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain a JSON object.")
+    return payload
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    events: list[dict[str, Any]] = []
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        payload = json.loads(line)
+        if not isinstance(payload, dict):
+            raise ValueError(f"{path}:{line_number} must contain a JSON object.")
+        events.append(payload)
+    return events
+
+
+def require_output(path: Path) -> None:
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Missing {path}. Run the full migration agent before running artifact evals."
+        )
+    if path.stat().st_size == 0:
+        raise ValueError(f"{path} is empty.")
+
+
+def require_contains(text: str, marker: str, *, artifact: str) -> None:
+    if marker not in text:
+        raise ValueError(f"Expected {artifact} to contain {marker!r}.")
+
+
+def require_result_value(result: dict[str, Any], field: str, marker: str) -> None:
+    value = result.get(field)
+    if not isinstance(value, str) or marker not in value:
+        raise ValueError(f"Expected result[{field!r}] to contain {marker!r}.")
+
+
+def validate_migration_artifacts(output_dir: Path, *, task_name: str | None = None) -> None:
+    report_path = output_dir / "migration_report.md"
+    patch_path = output_dir / "migration.patch"
+    result_path = output_dir / "migration_result.json"
+    audit_path = output_dir / "migration_audit.jsonl"
+
+    for path in [report_path, patch_path, result_path, audit_path]:
+        require_output(path)
+
+    result = read_json(result_path)
+    patch = patch_path.read_text(encoding="utf-8")
+    report = report_path.read_text(encoding="utf-8")
+    audit_events = read_jsonl(audit_path)
+
+    require_result_value(result, "baseline_test_command", "unittest")
+    require_result_value(result, "check_command", "compileall")
+    require_result_value(result, "final_test_command", "unittest")
+
+    final_test_result = str(result.get("final_test_result", "")).lower()
+    if "pass" not in final_test_result and "ok" not in final_test_result:
+        raise ValueError("Expected final_test_result to describe a passing test run.")
+
+    changed_files = result.get("changed_files")
+    if not isinstance(changed_files, list) or not changed_files:
+        raise ValueError("Expected result['changed_files'] to be a non-empty list.")
+
+    require_contains(patch, "responses.create", artifact=str(patch_path))
+    require_contains(patch, "output_text", artifact=str(patch_path))
+    for marker in EXPECTED_PATCH_MARKERS.get(task_name or "", []):
+        require_contains(patch, marker, artifact=str(patch_path))
+    require_contains(patch, "tests/", artifact=str(patch_path))
+
+    require_contains(report.lower(), "responses", artifact=str(report_path))
+    require_contains(report.lower(), "test", artifact=str(report_path))
+
+    if not any(event.get("event") == "host_artifacts_written" for event in audit_events):
+        raise ValueError("Expected audit log to include a host_artifacts_written event.")
+
+
+def validate_output_root(output_dir: Path) -> None:
+    batch_summary_path = output_dir / "batch_summary.json"
+    if not batch_summary_path.exists():
+        validate_migration_artifacts(output_dir)
+        return
+
+    batch_summary = read_json(batch_summary_path)
+    task_summaries = batch_summary.get("task_summaries")
+    if not isinstance(task_summaries, list) or not task_summaries:
+        raise ValueError("Expected batch_summary.json to include task_summaries.")
+
+    for summary in task_summaries:
+        if not isinstance(summary, dict):
+            raise ValueError("Each task summary must be a JSON object.")
+        task_name = summary.get("task_name")
+        task_output_dir = summary.get("output_dir")
+        if not isinstance(task_name, str) or not isinstance(task_output_dir, str):
+            raise ValueError("Each task summary must include task_name and output_dir.")
+        validate_migration_artifacts(Path(task_output_dir), task_name=task_name)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Validate generated migration-agent artifacts.")
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=EXAMPLE_ROOT / "outputs",
+        help=(
+            "Directory containing batch_summary.json or a single task's "
+            "migration_report.md, migration.patch, migration_result.json, "
+            "and migration_audit.jsonl."
+        ),
+    )
+    args = parser.parse_args()
+
+    try:
+        validate_output_root(args.output_dir)
+    except Exception as exc:
+        raise SystemExit(f"Artifact eval failed: {exc}") from exc
+
+    print(f"Migration artifact evals passed for {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

examples/agents_sdk/sandboxed-code-migration/evals.py

@@ -0,0 +1,45 @@
+# Code migration agent
+
+You are migrating the mounted repo under `repo/`.
+
+## Mission
+
+- Migrate the repo according to `repo/MIGRATION.md`.
+- Preserve the public function signatures and behavior.
+- Run the baseline test command before editing.
+- Edit the app code and its tests.
+- Run the check command named in `repo/MIGRATION.md` after editing.
+- Run the final test command named in `repo/MIGRATION.md` after editing.
+- Return structured output that includes the exact commands, pass/fail summaries,
+  changed files, a Markdown migration report, and the patch you applied.
+
+## Required command pattern
+
+Each migration brief in `repo/MIGRATION.md` includes a validation pipeline.
+Use the exact baseline, check, and final test commands from that brief.
+
+Run all three commands from `repo/`.
+
+## Editing rules
+
+- Keep the migration narrow. Do not rewrite the sample app.
+- Prefer `apply_patch` for edits.
+- When using `apply_patch`, use workspace-relative paths such as `repo/customer_support_bot/replies.py`.
+- Do not edit files outside `repo/`.
+- Do not install packages.
+- Do not place API keys, environment variables, or real OpenAI calls in tests.
+- The final tests must use a fake client; they should not call the network.
+- Include a patch in `migration_patch`. If you use `apply_patch`, you may return the same patch text.
+- The sandbox image may not have `git`. Do not require `git diff`; keep enough
+  patch text from your `apply_patch` calls to return the migration diff.
+
+## Suggested loop
+
+1. Inspect `repo/MIGRATION.md`, the app files it names, and the tests it names.
+2. Run the baseline test command from the migration brief.
+3. Patch the client wrapper and reply call site.
+4. Patch tests.
+5. Run the check command from the migration brief.
+6. Run the final test command from the migration brief.
+7. Inspect the changed files and assemble the migration patch from the patch text you applied.
+8. Return the structured result.

examples/agents_sdk/sandboxed-code-migration/migration_agent/AGENTS.md

@@ -0,0 +1 @@
+

examples/agents_sdk/sandboxed-code-migration/outputs/.gitkeep

@@ -0,0 +1,33 @@
+# Migration request: Chat Completions to Responses
+
+Migrate this case summary service from the legacy Chat Completions call shape to
+the Responses API call shape.
+
+## Current structure
+
+- `case_summary_service/client.py` contains the OpenAI client wrapper.
+- `case_summary_service/summaries.py` builds the summary prompt and calls the wrapper.
+- `tests/` contains offline fakes for the legacy Chat Completions shape.
+
+## Target shape
+
+- In `case_summary_service/client.py`, call `client.responses.create(...)`
+  instead of `client.chat.completions.create(...)`.
+- Keep the same `model` argument.
+- Replace the wrapper's `messages` argument with an `input_items` argument.
+- In `case_summary_service/summaries.py`, pass the two-message system/user
+  conversation as `input_items`.
+- Forward `input_items` as the Responses API `input` argument.
+- Keep `temperature=0`.
+- Return `response.output_text` instead of `completion.choices[0].message.content`.
+- Preserve the `summarize_case(client, *, model, case_notes)` function signature.
+- Update client-wrapper and summary tests to fake the Responses API instead of
+  Chat Completions.
+- Tests must remain offline; do not import or instantiate the real OpenAI client.
+
+## Required validation pipeline
+
+- Before editing, run baseline tests: `python -m unittest discover -s tests -t .`.
+- After editing, run the compile/check command: `python -m compileall -q case_summary_service tests`.
+- After the compile/check command passes, run final tests: `python -m unittest discover -s tests -t .`.
+- Validate with `python -m unittest discover -s tests -t .`.

examples/agents_sdk/sandboxed-code-migration/repo_fixtures/case_summary_service/MIGRATION.md

@@ -0,0 +1,6 @@
+# Case summary service
+
+Small offline fixture for the sandboxed migration cookbook.
+
+The pre-migration service wraps a Chat Completions call and uses it to summarize
+internal case notes. Tests use fakes; they should never call the network.

examples/agents_sdk/sandboxed-code-migration/repo_fixtures/case_summary_service/README.md

@@ -0,0 +1,3 @@
+from .summaries import summarize_case
+
+__all__ = ["summarize_case"]

examples/agents_sdk/sandboxed-code-migration/repo_fixtures/case_summary_service/case_summary_service/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def complete_summary_prompt(
+    client: Any,
+    *,
+    model: str,
+    messages: list[dict[str, str]],
+) -> str:
+    completion = client.chat.completions.create(
+        model=model,
+        messages=messages,
+        temperature=0,
+    )
+    return completion.choices[0].message.content