codex-sdk-rs 0.1.0

Rust SDK for the OpenAI Codex app server
Documentation
from __future__ import annotations

import argparse
import ast
import difflib
import hashlib
import json
import re
import subprocess
import tempfile
from pathlib import Path
from typing import Any, Iterable


REPOSITORY = "https://github.com/openai/codex.git"
TRACKED_GROUPS = {
    "package_and_docs": ("README.md", "pyproject.toml", "docs/*.md"),
    "source": ("src/openai_codex/**/*.py",),
    "tests": ("tests/*.py",),
}


def command(*args: str, cwd: Path | None = None) -> str:
    return subprocess.run(
        args,
        cwd=cwd,
        check=True,
        text=True,
        stdout=subprocess.PIPE,
    ).stdout.strip()


def checkout(ref: str, destination: Path) -> tuple[Path, str]:
    command(
        "git",
        "clone",
        "--quiet",
        "--filter=blob:none",
        "--no-checkout",
        REPOSITORY,
        str(destination),
    )
    command("git", "sparse-checkout", "init", "--cone", cwd=destination)
    command("git", "sparse-checkout", "set", "sdk/python", cwd=destination)
    command("git", "fetch", "--quiet", "--depth=1", "origin", ref, cwd=destination)
    command("git", "checkout", "--quiet", "FETCH_HEAD", cwd=destination)
    return destination / "sdk/python", command("git", "rev-parse", "HEAD", cwd=destination)


def source_revision(source: Path) -> tuple[Path, str]:
    if (source / "sdk/python/pyproject.toml").is_file():
        sdk = source / "sdk/python"
        repository = source
    elif (source / "pyproject.toml").is_file() and (source / "src/openai_codex").is_dir():
        sdk = source
        repository = source
        while repository != repository.parent and not (repository / ".git").exists():
            repository = repository.parent
    else:
        raise SystemExit(f"{source} is neither an openai/codex checkout nor sdk/python")
    try:
        revision = command("git", "rev-parse", "HEAD", cwd=repository)
    except subprocess.CalledProcessError:
        revision = "unknown"
    return sdk, revision


def parse_module(path: Path) -> ast.Module:
    return ast.parse(path.read_text(encoding="utf-8"), filename=str(path))


def literal_string_list(module: ast.Module, name: str) -> list[str]:
    for node in module.body:
        if isinstance(node, (ast.Assign, ast.AnnAssign)):
            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
            if any(isinstance(target, ast.Name) and target.id == name for target in targets):
                value = ast.literal_eval(node.value)
                return list(value)
    raise ValueError(f"{name} not found")


def annotation(node: ast.expr | None) -> str | None:
    return ast.unparse(node) if node is not None else None


def default_value(node: ast.expr | None) -> str | None:
    return ast.unparse(node) if node is not None else None


def function_contract(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
    prefix = "async " if isinstance(node, ast.AsyncFunctionDef) else ""
    returns = f" -> {annotation(node.returns)}" if node.returns is not None else ""
    return f"{prefix}def {node.name}({ast.unparse(node.args)}){returns}"


def public_classes(source_dir: Path, exports: set[str]) -> dict[str, Any]:
    classes: dict[str, Any] = {}
    for path in sorted(source_dir.glob("*.py")):
        for node in parse_module(path).body:
            if not isinstance(node, ast.ClassDef) or node.name not in exports:
                continue
            methods = {
                child.name: function_contract(child)
                for child in node.body
                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
                and not child.name.startswith("_")
            }
            fields = {}
            for child in node.body:
                if isinstance(child, ast.AnnAssign) and isinstance(child.target, ast.Name):
                    default = (
                        f" = {default_value(child.value)}" if child.value is not None else ""
                    )
                    fields[child.target.id] = f"{annotation(child.annotation)}{default}"
            classes[node.name] = {
                "defined_in": path.name,
                "fields": fields,
                "methods": methods,
            }
    return classes


def request_methods(source_dir: Path) -> list[str]:
    methods = set()
    for path in sorted(source_dir.glob("*.py")):
        for node in ast.walk(parse_module(path)):
            if not isinstance(node, ast.Call) or not node.args:
                continue
            if not isinstance(node.func, ast.Attribute) or node.func.attr not in {"request", "notify"}:
                continue
            first = node.args[0]
            if isinstance(first, ast.Constant) and isinstance(first.value, str):
                methods.add(first.value)
    return sorted(methods)


def notification_registry(path: Path) -> dict[str, str]:
    module = parse_module(path)
    for node in module.body:
        if not isinstance(node, ast.AnnAssign):
            continue
        if not isinstance(node.target, ast.Name) or node.target.id != "NOTIFICATION_MODELS":
            continue
        if not isinstance(node.value, ast.Dict):
            break
        return {
            ast.literal_eval(key): value.id
            for key, value in zip(node.value.keys, node.value.values)
            if isinstance(value, ast.Name)
        }
    raise ValueError("NOTIFICATION_MODELS not found")


def tracked_files(sdk: Path, patterns: Iterable[str]) -> Iterable[Path]:
    paths = set()
    for pattern in patterns:
        paths.update(path for path in sdk.glob(pattern) if path.is_file())
    return sorted(paths)


def sha256(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()


def grouped_sha256(sdk: Path, patterns: Iterable[str]) -> str:
    digest = hashlib.sha256()
    for path in tracked_files(sdk, patterns):
        digest.update(str(path.relative_to(sdk)).encode())
        digest.update(b"\0")
        digest.update(path.read_bytes())
        digest.update(b"\0")
    return digest.hexdigest()


def generated_model_summary(path: Path) -> dict[str, Any]:
    classes = [node.name for node in parse_module(path).body if isinstance(node, ast.ClassDef)]
    return {
        "class_count": len(classes),
        "sha256": sha256(path),
    }


def build_contract(sdk: Path, revision: str) -> dict[str, Any]:
    package = sdk / "src/openai_codex"
    root_exports = literal_string_list(parse_module(package / "__init__.py"), "__all__")
    type_exports = literal_string_list(parse_module(package / "types.py"), "__all__")
    exports = set(root_exports) | set(type_exports)
    pyproject = (sdk / "pyproject.toml").read_text(encoding="utf-8")
    runtime = re.search(r'"openai-codex-cli-bin==([^"]+)"', pyproject)

    return {
        "schema_version": 1,
        "upstream": {
            "repository": REPOSITORY,
            "revision": revision,
            "sdk_path": "sdk/python",
            "runtime_version": runtime.group(1) if runtime else None,
        },
        "public_root_exports": root_exports,
        "public_type_exports": type_exports,
        "public_classes": public_classes(package, exports),
        "rpc_methods": request_methods(package),
        "notification_models": notification_registry(
            package / "generated/notification_registry.py"
        ),
        "generated_protocol": generated_model_summary(package / "generated/v2_all.py"),
        "file_group_sha256": {
            group: grouped_sha256(sdk, patterns)
            for group, patterns in TRACKED_GROUPS.items()
        },
    }


def encoded(contract: dict[str, Any]) -> str:
    return json.dumps(contract, indent=2, sort_keys=True) + "\n"


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Capture or verify the public contract of openai/codex sdk/python."
    )
    parser.add_argument("--ref", default="main", help="upstream Git ref to inspect")
    parser.add_argument("--source", type=Path, help="existing checkout or sdk/python directory")
    parser.add_argument(
        "--snapshot",
        type=Path,
        default=Path("upstream/python-sdk-contract.json"),
    )
    mode = parser.add_mutually_exclusive_group(required=True)
    mode.add_argument("--check", action="store_true")
    mode.add_argument("--write", action="store_true")
    args = parser.parse_args()

    with tempfile.TemporaryDirectory(prefix="codex-sdk-upstream-") as temp:
        if args.source is not None:
            sdk, revision = source_revision(args.source.resolve())
        else:
            sdk, revision = checkout(args.ref, Path(temp) / "codex")
        actual = encoded(build_contract(sdk, revision))

    if args.write:
        args.snapshot.parent.mkdir(parents=True, exist_ok=True)
        args.snapshot.write_text(actual, encoding="utf-8")
        print(f"wrote {args.snapshot} for {revision}")
        return 0

    if not args.snapshot.exists():
        print(f"missing snapshot: {args.snapshot}")
        return 1
    expected = args.snapshot.read_text(encoding="utf-8")
    if expected == actual:
        print(f"upstream Python SDK contract matches {revision}")
        return 0
    print(
        "".join(
            difflib.unified_diff(
                expected.splitlines(keepends=True),
                actual.splitlines(keepends=True),
                fromfile=str(args.snapshot),
                tofile=f"openai/codex@{revision}:sdk/python",
            )
        )
    )
    return 1


if __name__ == "__main__":
    raise SystemExit(main())