codexopt 0.1.0__py3-none-any.whl

codexopt/__init__.py

@@ -0,0 +1,4 @@
+"""codexopt package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

codexopt/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

codexopt/applier.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from datetime import datetime
+from datetime import timezone
+from pathlib import Path
+from typing import Any
+
+
+def apply_optimization_result(
+    optimization_result: dict[str, Any],
+    repo_root: Path,
+    backup_root: Path,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    backup_dir = backup_root / timestamp
+    applied: list[str] = []
+    skipped: list[str] = []
+
+    if not dry_run:
+        backup_dir.mkdir(parents=True, exist_ok=True)
+
+    for item in optimization_result.get("results", []):
+        path = Path(item["path"])
+        if item.get("delta", 0.0) <= 0.0:
+            skipped.append(f"{path} (no improvement)")
+            continue
+        if not path.exists():
+            skipped.append(f"{path} (missing)")
+            continue
+
+        new_content = str(item.get("best_content", ""))
+        current = path.read_text(encoding="utf-8", errors="replace")
+        if current == new_content:
+            skipped.append(f"{path} (no changes)")
+            continue
+
+        if dry_run:
+            applied.append(str(path))
+            continue
+
+        try:
+            rel = path.resolve().relative_to(repo_root.resolve())
+        except Exception:
+            rel = Path(path.name)
+        backup_path = backup_dir / rel
+        backup_path.parent.mkdir(parents=True, exist_ok=True)
+        backup_path.write_text(current, encoding="utf-8")
+        path.write_text(new_content, encoding="utf-8")
+        applied.append(str(path))
+
+    return {
+        "dry_run": dry_run,
+        "backup_dir": str(backup_dir),
+        "applied_count": len(applied),
+        "skipped_count": len(skipped),
+        "applied": applied,
+        "skipped": skipped,
+    }
+
+
+def print_apply_summary(result: dict[str, Any]) -> None:
+    print(f"dry_run: {result['dry_run']}")
+    print(f"applied_count: {result['applied_count']}")
+    print(f"skipped_count: {result['skipped_count']}")
+    if not result["dry_run"]:
+        print(f"backup_dir: {result['backup_dir']}")
+    for item in result["applied"]:
+        print(f"- applied: {item}")
+    for item in result["skipped"]:
+        print(f"- skipped: {item}")

codexopt/artifacts.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from datetime import timezone
+from pathlib import Path
+from typing import Any
+
+
+STATE_FILENAME = "state.json"
+
+
+def ensure_output_dirs(root_dir: Path) -> None:
+    (root_dir / "runs").mkdir(parents=True, exist_ok=True)
+    (root_dir / "backups").mkdir(parents=True, exist_ok=True)
+
+
+def load_state(root_dir: Path) -> dict[str, Any]:
+    state_path = root_dir / STATE_FILENAME
+    if not state_path.exists():
+        return {}
+    try:
+        return json.loads(state_path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def save_state(root_dir: Path, state: dict[str, Any]) -> None:
+    state_path = root_dir / STATE_FILENAME
+    state_path.write_text(json.dumps(state, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def new_run_dir(root_dir: Path, kind: str) -> tuple[str, Path]:
+    ensure_output_dirs(root_dir)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    run_id = f"{stamp}-{kind}"
+    run_dir = root_dir / "runs" / run_id
+    run_dir.mkdir(parents=True, exist_ok=False)
+    return run_id, run_dir
+
+
+def write_json(path: Path, data: dict[str, Any]) -> None:
+    path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def set_latest_run(root_dir: Path, state_key: str, run_id: str) -> None:
+    state = load_state(root_dir)
+    state[state_key] = run_id
+    save_state(root_dir, state)
+
+
+def resolve_run_id(root_dir: Path, state_key: str, explicit_run_id: str | None) -> str | None:
+    if explicit_run_id:
+        return explicit_run_id
+    state = load_state(root_dir)
+    value = state.get(state_key)
+    if isinstance(value, str):
+        return value
+    return None

codexopt/benchmark.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .types import FileScore
+
+
+def _score_agents(entry: dict[str, Any]) -> FileScore:
+    score = 1.0
+    issues: list[str] = []
+    details: dict[str, Any] = {}
+    words = int(entry.get("words", 0))
+    tokens = int(entry.get("token_estimate", 0))
+
+    if words < 80:
+        score -= 0.2
+        issues.append("too_short")
+    if words > 2400:
+        score -= min(0.35, (words - 2400) / 10000.0)
+        issues.append("too_long")
+    if tokens > 7000:
+        score -= 0.15
+        issues.append("token_heavy")
+    if "empty_agents" in entry.get("issues", []):
+        score -= 0.6
+        issues.append("empty")
+
+    details["words"] = words
+    details["token_estimate"] = tokens
+    return FileScore(
+        path=entry["path"],
+        kind="agents",
+        score=max(0.0, min(1.0, score)),
+        issues=issues,
+        details=details,
+    )
+
+
+def _score_skill(entry: dict[str, Any]) -> FileScore:
+    score = 1.0
+    issues: list[str] = []
+    details: dict[str, Any] = {}
+    words = int(entry.get("words", 0))
+    entry_issues = set(entry.get("issues", []))
+
+    if "missing_frontmatter" in entry_issues:
+        score -= 0.6
+        issues.append("missing_frontmatter")
+    if "missing_name" in entry_issues:
+        score -= 0.2
+        issues.append("missing_name")
+    if "missing_description" in entry_issues:
+        score -= 0.2
+        issues.append("missing_description")
+    if "name_too_long" in entry_issues:
+        score -= 0.15
+        issues.append("name_too_long")
+    if "description_too_long" in entry_issues:
+        score -= 0.15
+        issues.append("description_too_long")
+    if words < 40:
+        score -= 0.15
+        issues.append("too_short")
+    if words > 1800:
+        score -= min(0.25, (words - 1800) / 10000.0)
+        issues.append("too_long")
+
+    details["words"] = words
+    details["frontmatter_present"] = entry.get("metadata", {}).get("frontmatter_present", False)
+    return FileScore(
+        path=entry["path"],
+        kind="skill",
+        score=max(0.0, min(1.0, score)),
+        issues=issues,
+        details=details,
+    )
+
+
+def score_entry(entry: dict[str, Any]) -> FileScore:
+    kind = entry.get("kind")
+    if kind == "agents":
+        return _score_agents(entry)
+    return _score_skill(entry)
+
+
+def run_benchmark(scan_result: dict[str, Any]) -> dict[str, Any]:
+    scores: list[FileScore] = [score_entry(entry) for entry in scan_result["entries"]]
+    if scores:
+        overall = sum(item.score for item in scores) / len(scores)
+    else:
+        overall = 0.0
+
+    return {
+        "counts": scan_result["counts"],
+        "overall_score": round(overall, 4),
+        "files": [
+            {
+                "path": item.path,
+                "kind": item.kind,
+                "score": round(item.score, 4),
+                "issues": item.issues,
+                "details": item.details,
+            }
+            for item in scores
+        ],
+    }
+
+
+def print_benchmark_summary(result: dict[str, Any]) -> None:
+    print(f"overall_score: {result['overall_score']:.4f}")
+    for file_result in result["files"]:
+        issues = ", ".join(file_result["issues"]) if file_result["issues"] else "ok"
+        print(f"- {file_result['kind']}: {file_result['path']}")
+        print(f"  score={file_result['score']:.4f} issues={issues}")

codexopt/cli.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from .applier import apply_optimization_result
+from .applier import print_apply_summary
+from .artifacts import new_run_dir
+from .artifacts import read_json
+from .artifacts import resolve_run_id
+from .artifacts import set_latest_run
+from .artifacts import write_json
+from .benchmark import print_benchmark_summary
+from .benchmark import run_benchmark
+from .config import DEFAULT_CONFIG_FILENAME
+from .config import load_config
+from .config import write_default_config
+from .optimizer import optimize_entries
+from .optimizer import print_optimization_summary
+from .reporter import build_markdown_report
+from .scanner import print_scan_summary
+from .scanner import scan_project
+
+
+def _resolve_config(config_path: str | None) -> tuple[Any, Path]:
+    path = Path(config_path).resolve() if config_path else None
+    return load_config(path)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    path = Path(args.path or DEFAULT_CONFIG_FILENAME).resolve()
+    write_default_config(path, force=args.force)
+    print(f"wrote {path}")
+    return 0
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    cfg, _cfg_path = _resolve_config(args.config)
+    cwd = Path.cwd()
+    result = scan_project(cwd, cfg)
+
+    output_root = Path(cfg.output.root_dir)
+    run_id, run_dir = new_run_dir(output_root, "scan")
+    write_json(run_dir / "scan.json", result)
+    set_latest_run(output_root, "latest_scan_run", run_id)
+
+    print_scan_summary(result)
+    print(f"run_id: {run_id}")
+    return 0
+
+
+def cmd_benchmark(args: argparse.Namespace) -> int:
+    cfg, _cfg_path = _resolve_config(args.config)
+    cwd = Path.cwd()
+    scan_result = scan_project(cwd, cfg)
+    benchmark_result = run_benchmark(scan_result)
+
+    output_root = Path(cfg.output.root_dir)
+    run_id, run_dir = new_run_dir(output_root, "benchmark")
+    write_json(run_dir / "scan.json", scan_result)
+    write_json(run_dir / "benchmark.json", benchmark_result)
+    set_latest_run(output_root, "latest_scan_run", run_id)
+    set_latest_run(output_root, "latest_benchmark_run", run_id)
+
+    print_benchmark_summary(benchmark_result)
+    print(f"run_id: {run_id}")
+    return 0
+
+
+def _optimize(args: argparse.Namespace, kind: str) -> int:
+    cfg, _cfg_path = _resolve_config(args.config)
+    cwd = Path.cwd()
+
+    agents_patterns = args.file if kind == "agents" and args.file else None
+    skills_patterns = args.glob if kind == "skill" and args.glob else None
+
+    scan_result = scan_project(
+        cwd=cwd,
+        config=cfg,
+        agents_files=agents_patterns,
+        skills_globs=skills_patterns,
+    )
+    result = optimize_entries(
+        entries=scan_result["entries"],
+        kind=kind,
+        engine=args.engine or cfg.optimization.engine,
+        min_delta=cfg.optimization.min_apply_delta,
+        reflection_model=args.reflection_model or cfg.optimization.reflection_model,
+        max_metric_calls=args.max_metric_calls or cfg.optimization.max_metric_calls,
+    )
+
+    output_root = Path(cfg.output.root_dir)
+    run_label = "optimize-agents" if kind == "agents" else "optimize-skills"
+    run_id, run_dir = new_run_dir(output_root, run_label)
+    write_json(run_dir / "scan.json", scan_result)
+    write_json(run_dir / "optimize.json", result)
+    key = "latest_optimize_agents_run" if kind == "agents" else "latest_optimize_skills_run"
+    set_latest_run(output_root, key, run_id)
+
+    print_optimization_summary(result)
+    print(f"run_id: {run_id}")
+    return 0
+
+
+def cmd_optimize_agents(args: argparse.Namespace) -> int:
+    return _optimize(args, "agents")
+
+
+def cmd_optimize_skills(args: argparse.Namespace) -> int:
+    return _optimize(args, "skill")
+
+
+def cmd_apply(args: argparse.Namespace) -> int:
+    cfg, _cfg_path = _resolve_config(args.config)
+    output_root = Path(cfg.output.root_dir)
+
+    if args.kind == "agents":
+        state_key = "latest_optimize_agents_run"
+    else:
+        state_key = "latest_optimize_skills_run"
+
+    run_id = resolve_run_id(output_root, state_key, args.run_id)
+    if not run_id:
+        print("no optimization run found", file=sys.stderr)
+        return 2
+
+    run_dir = output_root / "runs" / run_id
+    optimize_path = run_dir / "optimize.json"
+    if not optimize_path.exists():
+        print(f"missing optimize artifact: {optimize_path}", file=sys.stderr)
+        return 2
+    optimize_result = read_json(optimize_path)
+    apply_result = apply_optimization_result(
+        optimization_result=optimize_result,
+        repo_root=Path.cwd(),
+        backup_root=output_root / "backups",
+        dry_run=args.dry_run,
+    )
+
+    apply_run_id, apply_run_dir = new_run_dir(output_root, "apply")
+    write_json(apply_run_dir / "apply.json", apply_result)
+    set_latest_run(output_root, "latest_apply_run", apply_run_id)
+
+    print_apply_summary(apply_result)
+    print(f"source_run_id: {run_id}")
+    print(f"run_id: {apply_run_id}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    cfg, _cfg_path = _resolve_config(args.config)
+    output_root = Path(cfg.output.root_dir)
+    report = build_markdown_report(output_root)
+    if args.output:
+        out = Path(args.output)
+        out.write_text(report, encoding="utf-8")
+        print(f"wrote {out}")
+    else:
+        print(report)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="codexopt", description="Optimize Codex AGENTS.md and SKILL.md")
+    parser.add_argument("--config", help="Path to codexopt.yaml", default=None)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="Write codexopt.yaml template")
+    p_init.add_argument("--path", default=None, help="Output config path")
+    p_init.add_argument("--force", action="store_true", help="Overwrite if exists")
+    p_init.set_defaults(func=cmd_init)
+
+    p_scan = sub.add_parser("scan", help="Scan AGENTS and SKILL files")
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_bench = sub.add_parser("benchmark", help="Benchmark current instruction assets")
+    p_bench.set_defaults(func=cmd_benchmark)
+
+    p_opt = sub.add_parser("optimize", help="Optimize instruction assets")
+    opt_sub = p_opt.add_subparsers(dest="target", required=True)
+
+    p_opt_agents = opt_sub.add_parser("agents", help="Optimize AGENTS files")
+    p_opt_agents.add_argument(
+        "--file",
+        action="append",
+        help="AGENTS glob pattern (can be repeated). Defaults from config.",
+    )
+    p_opt_agents.add_argument("--engine", choices=["heuristic", "gepa"], default=None)
+    p_opt_agents.add_argument("--reflection-model", default=None)
+    p_opt_agents.add_argument("--max-metric-calls", type=int, default=None)
+    p_opt_agents.set_defaults(func=cmd_optimize_agents)
+
+    p_opt_skills = opt_sub.add_parser("skills", help="Optimize SKILL files")
+    p_opt_skills.add_argument(
+        "--glob",
+        action="append",
+        help="SKILL glob pattern (can be repeated). Defaults from config.",
+    )
+    p_opt_skills.add_argument("--engine", choices=["heuristic", "gepa"], default=None)
+    p_opt_skills.add_argument("--reflection-model", default=None)
+    p_opt_skills.add_argument("--max-metric-calls", type=int, default=None)
+    p_opt_skills.set_defaults(func=cmd_optimize_skills)
+
+    p_apply = sub.add_parser("apply", help="Apply best optimized candidates")
+    p_apply.add_argument("--kind", choices=["agents", "skills"], default="agents")
+    p_apply.add_argument("--run-id", default=None, help="Optimization run id to apply")
+    p_apply.add_argument("--dry-run", action="store_true")
+    p_apply.set_defaults(func=cmd_apply)
+
+    p_report = sub.add_parser("report", help="Render markdown report from latest runs")
+    p_report.add_argument("--output", default=None, help="Optional output markdown file")
+    p_report.set_defaults(func=cmd_report)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except FileExistsError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except Exception as exc:  # pragma: no cover
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

codexopt/config.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except Exception:  # pragma: no cover
+    yaml = None
+
+
+DEFAULT_CONFIG_FILENAME = "codexopt.yaml"
+
+
+@dataclass
+class TargetsConfig:
+    agents_files: list[str] = field(
+        default_factory=lambda: ["AGENTS.md", "**/AGENTS.md", "**/AGENTS.override.md"]
+    )
+    skills_globs: list[str] = field(
+        default_factory=lambda: [".codex/skills/**/SKILL.md", "**/.codex/skills/**/SKILL.md"]
+    )
+    exclude_globs: list[str] = field(
+        default_factory=lambda: [
+            ".git/**",
+            ".codexopt/**",
+            ".venv/**",
+            "node_modules/**",
+            "reference/**",
+        ]
+    )
+
+
+@dataclass
+class OutputConfig:
+    root_dir: str = ".codexopt"
+
+
+@dataclass
+class OptimizationConfig:
+    engine: str = "heuristic"
+    min_apply_delta: float = 0.01
+    max_metric_calls: int = 60
+    reflection_model: str | None = None
+
+
+@dataclass
+class CodexOptConfig:
+    version: int = 1
+    targets: TargetsConfig = field(default_factory=TargetsConfig)
+    output: OutputConfig = field(default_factory=OutputConfig)
+    optimization: OptimizationConfig = field(default_factory=OptimizationConfig)
+
+
+def default_config() -> CodexOptConfig:
+    return CodexOptConfig()
+
+
+def _merge_dict(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in patch.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _merge_dict(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def _config_to_dict(cfg: CodexOptConfig) -> dict[str, Any]:
+    return {
+        "version": cfg.version,
+        "targets": {
+            "agents_files": cfg.targets.agents_files,
+            "skills_globs": cfg.targets.skills_globs,
+            "exclude_globs": cfg.targets.exclude_globs,
+        },
+        "output": {"root_dir": cfg.output.root_dir},
+        "optimization": {
+            "engine": cfg.optimization.engine,
+            "min_apply_delta": cfg.optimization.min_apply_delta,
+            "max_metric_calls": cfg.optimization.max_metric_calls,
+            "reflection_model": cfg.optimization.reflection_model,
+        },
+    }
+
+
+def _dict_to_config(data: dict[str, Any]) -> CodexOptConfig:
+    targets = data.get("targets", {})
+    output = data.get("output", {})
+    optimization = data.get("optimization", {})
+    return CodexOptConfig(
+        version=int(data.get("version", 1)),
+        targets=TargetsConfig(
+            agents_files=list(targets.get("agents_files", TargetsConfig().agents_files)),
+            skills_globs=list(targets.get("skills_globs", TargetsConfig().skills_globs)),
+            exclude_globs=list(targets.get("exclude_globs", TargetsConfig().exclude_globs)),
+        ),
+        output=OutputConfig(root_dir=str(output.get("root_dir", ".codexopt"))),
+        optimization=OptimizationConfig(
+            engine=str(optimization.get("engine", "heuristic")),
+            min_apply_delta=float(optimization.get("min_apply_delta", 0.01)),
+            max_metric_calls=int(optimization.get("max_metric_calls", 60)),
+            reflection_model=optimization.get("reflection_model"),
+        ),
+    )
+
+
+def load_config(path: Path | None = None) -> tuple[CodexOptConfig, Path]:
+    cfg_path = path or Path.cwd() / DEFAULT_CONFIG_FILENAME
+    cfg = default_config()
+    if not cfg_path.exists():
+        return cfg, cfg_path
+    if yaml is None:
+        raise RuntimeError("PyYAML is required to read codexopt.yaml")
+
+    raw = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
+    merged = _merge_dict(_config_to_dict(cfg), raw)
+    return _dict_to_config(merged), cfg_path
+
+
+def write_default_config(path: Path, force: bool = False) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists; pass --force to overwrite")
+    if yaml is None:
+        raise RuntimeError("PyYAML is required to write codexopt.yaml")
+
+    data = _config_to_dict(default_config())
+    rendered = yaml.safe_dump(data, sort_keys=False)
+    path.write_text(rendered, encoding="utf-8")