@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/autoresearch/scripts/init_research.py

@@ -0,0 +1,401 @@
+"""
+init_research.py — Scaffold a new autoresearch-skill project directory.
+
+Usage:
+    python init_research.py --goal "..." --metric "..." --direction {maximize|minimize} \
+        [--target "..."] [--max-iterations 10] [--output ./my-research/]
+"""
+
+import argparse
+import math
+import os
+import secrets
+import stat
+import sys
+import textwrap
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Tuple
+
+RESEARCH_TEMPLATE = """\
+# Research: {title}
+
+## Goal
+{goal}
+
+## Success Metric
+- **Metric:** {metric}
+- **Target:** {target}
+- **Direction:** {direction}
+
+## Constraints
+- **Max iterations:** {max_iterations}
+- **Time budget per experiment:** 5 minutes
+- **Pause for review every:** never
+- **Evaluator:** {evaluator}
+- **Keep policy:** {keep_policy}
+- **Guard:** {guard}
+- **Noise runs:** {noise_runs}
+- **Min delta:** {min_delta}
+
+## Current Approach
+_Describe your current baseline here._
+
+## Search Space
+- **Allowed changes:** _Define what the agent can modify._
+- **Forbidden changes:** _Define what must NOT change._
+
+## Context & References
+_Add relevant papers, docs, or URLs here._
+
+---
+
+## History
+| # | Change | Metric | Result | Timestamp |
+|---|--------|--------|--------|-----------|
+| 0 | Baseline | TBD | -- | {date} |
+"""
+
+LOG_TEMPLATE = """\
+# Research Log
+
+> Auto-generated by init_research.py on {date}
+> Goal: {goal}
+
+---
+
+"""
+
+TSV_HEADER = "iteration\tmetric_value\tdelta\tdelta_pct\tstatus\tdescription\tevaluator_source\ttimestamp\n"
+TSV_BASELINE = "0\tTBD\t-\t-\tbaseline\tInitial state\tagent\t{date}\n"
+
+MANAGED_FILE_LEAVES = (
+    "research.md",
+    "research_log.md",
+    "autoresearch-results.tsv",
+    "final_report.md",
+    "progress.png",
+    "autoresearch-run-state.json",
+    ".autoresearch-loop.pid",
+)
+
+
+def fail(code: str, message: str) -> None:
+    print(f"Error: {code}: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def preflight_capabilities() -> None:
+    """Fail before mutation unless the required Python/POSIX descriptor APIs exist."""
+    required_dir_fd = (os.open, os.mkdir, os.stat, os.unlink, os.link)
+    supported = (
+        sys.version_info >= (3, 8)
+        and hasattr(os, "O_DIRECTORY")
+        and hasattr(os, "O_NOFOLLOW")
+        and all(function in os.supports_dir_fd for function in required_dir_fd)
+        and os.listdir in os.supports_fd
+        and os.link in os.supports_follow_symlinks
+    )
+    if not supported:
+        fail(
+            "BLOCKED_UNSUPPORTED_PYTHON_POSIX_RUNTIME",
+            "requires Python 3.8+ with O_DIRECTORY, O_NOFOLLOW, dir_fd, fd-listdir, and no-follow link support",
+        )
+
+
+def open_safe_directory(path: Path) -> Tuple[int, Path]:
+    """Create/open path one component at a time without following symlinks."""
+    absolute = Path(os.path.abspath(os.fspath(path)))
+    parts = absolute.parts
+    if not parts or not absolute.is_absolute():
+        fail("UNSAFE_OUTPUT_PATH", "output must resolve to an absolute filesystem path")
+
+    flags = os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_CLOEXEC", 0)
+    nofollow = getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(parts[0], flags | nofollow)
+    try:
+        for index, part in enumerate(parts[1:], start=1):
+            try:
+                info = os.stat(part, dir_fd=fd, follow_symlinks=False)
+            except FileNotFoundError:
+                try:
+                    os.mkdir(part, 0o755, dir_fd=fd)
+                except FileExistsError:
+                    pass
+                info = os.stat(part, dir_fd=fd, follow_symlinks=False)
+            if stat.S_ISLNK(info.st_mode):
+                fail("UNSAFE_OUTPUT_SYMLINK", f"output component is a symlink: {absolute}")
+            if not stat.S_ISDIR(info.st_mode):
+                fail("UNSAFE_OUTPUT_PATH", f"output component is not a directory: {absolute}")
+            next_fd = os.open(part, flags | nofollow, dir_fd=fd)
+            try:
+                verify_directory_identity(
+                    Path(os.path.join(*parts[: index + 1])),
+                    next_fd,
+                    info,
+                    compare_ctime=index == len(parts) - 1,
+                )
+            except BaseException:
+                os.close(next_fd)
+                raise
+            os.close(fd)
+            fd = next_fd
+        verify_directory_identity(absolute, fd)
+        return fd, absolute
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def _directory_identity(
+    info: os.stat_result,
+    *,
+    include_ctime: bool = True,
+) -> Tuple[int, int, Optional[int], Optional[int]]:
+    identity = (info.st_dev, info.st_ino, getattr(info, "st_birthtime_ns", None))
+    return (*identity, info.st_ctime_ns if include_ctime else None)
+
+
+def verify_directory_identity(
+    path: Path,
+    fd: int,
+    expected: Optional[os.stat_result] = None,
+    *,
+    compare_ctime: bool = True,
+) -> None:
+    """Reject replacement of the opened output directory before each mutation."""
+    try:
+        named = os.stat(path, follow_symlinks=False)
+    except OSError as error:
+        fail("UNSAFE_OUTPUT_SWAP", f"output directory identity changed: {error}")
+    opened = os.fstat(fd)
+    if stat.S_ISLNK(named.st_mode) or not stat.S_ISDIR(named.st_mode):
+        fail("UNSAFE_OUTPUT_SYMLINK", f"output directory is no longer a real directory: {path}")
+    if expected is not None:
+        # The parent descriptor anchors this component.  Comparing the stale
+        # pre-open snapshot with the opened descriptor catches a replacement
+        # without rejecting an unrelated ctime change in an ancestor while
+        # the path is being walked.
+        if _directory_identity(expected, include_ctime=compare_ctime) != _directory_identity(
+            opened,
+            include_ctime=compare_ctime,
+        ):
+            fail("UNSAFE_OUTPUT_SWAP", f"output directory identity changed: {path}")
+        return
+    if _directory_identity(named) != _directory_identity(opened):
+        fail("UNSAFE_OUTPUT_SWAP", f"output directory identity changed: {path}")
+
+
+def leaf_info(fd: int, leaf: str) -> Optional[os.stat_result]:
+    try:
+        return os.stat(leaf, dir_fd=fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return None
+
+
+def reject_unsafe_leaf(fd: int, leaf: str, *, directory: bool = False) -> None:
+    info = leaf_info(fd, leaf)
+    if info is None:
+        return
+    expected = stat.S_ISDIR(info.st_mode) if directory else stat.S_ISREG(info.st_mode)
+    if stat.S_ISLNK(info.st_mode) or not expected:
+        fail("UNSAFE_GENERATED_LEAF", f"generated leaf has unsafe type: {leaf}")
+
+
+def remove_regular_leaf(fd: int, root: Path, leaf: str) -> None:
+    reject_unsafe_leaf(fd, leaf)
+    if leaf_info(fd, leaf) is not None:
+        verify_directory_identity(root, fd)
+        os.unlink(leaf, dir_fd=fd)
+
+
+def write_new_leaf(fd: int, root: Path, leaf: str, text: str) -> None:
+    """Create a leaf without overwrite; a competing leaf creation fails closed."""
+    verify_directory_identity(root, fd)
+    if leaf_info(fd, leaf) is not None:
+        fail("UNSAFE_GENERATED_LEAF", f"generated leaf appeared during scaffold: {leaf}")
+    temp = f".{leaf}.tmp-{os.getpid()}-{secrets.token_hex(6)}"
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    temp_fd = None
+    temp_created = False
+    try:
+        temp_fd = os.open(temp, flags, 0o600, dir_fd=fd)
+        temp_created = True
+        try:
+            data = text.encode("utf-8")
+            while data:
+                written = os.write(temp_fd, data)
+                data = data[written:]
+            os.fsync(temp_fd)
+        finally:
+            os.close(temp_fd)
+            temp_fd = None
+        verify_directory_identity(root, fd)
+        os.link(temp, leaf, src_dir_fd=fd, dst_dir_fd=fd, follow_symlinks=False)
+    except FileExistsError:
+        fail("UNSAFE_GENERATED_LEAF", f"generated leaf appeared during scaffold: {leaf}")
+    finally:
+        if temp_fd is not None:
+            try:
+                os.close(temp_fd)
+            except OSError:
+                pass
+        if temp_created:
+            try:
+                os.unlink(temp, dir_fd=fd)
+            except FileNotFoundError:
+                pass
+
+
+def goal_to_title(goal: str) -> str:
+    """Convert a goal string to a short title (first 8 words, title-cased)."""
+    words = goal.split()
+    short = " ".join(words[:8])
+    if len(words) > 8:
+        short += "..."
+    return short.title()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Scaffold a new autoresearch-skill project.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""\
+            Example:
+              python init_research.py \\
+                --goal "Optimize sorting algorithm performance" \\
+                --metric "execution_time_seconds" \\
+                --direction minimize \\
+                --target "< 0.5" \\
+                --max-iterations 20 \\
+                --output ./sort-research/
+        """),
+    )
+    parser.add_argument("--goal", required=True, help="Research goal description.")
+    parser.add_argument("--metric", required=True, help="Metric name to track (e.g. accuracy, execution_time_seconds).")
+    parser.add_argument(
+        "--direction",
+        required=True,
+        choices=["maximize", "minimize"],
+        help="Whether to maximize or minimize the metric.",
+    )
+    parser.add_argument("--target", default="TBD", help="Target value or expression (e.g. '> 0.9', '< 0.5'). Default: TBD")
+    parser.add_argument("--max-iterations", type=int, default=20, metavar="N", help="Maximum number of iterations. Default: 20")
+    parser.add_argument("--output", default="./research/", metavar="PATH", help="Output directory. Default: ./research/")
+    parser.add_argument("--evaluator", default=None, metavar="CMD",
+        help="Evaluator command (e.g. 'python evaluate.py'). Must output JSON {pass:bool, score?:number}.")
+    parser.add_argument("--keep-policy", default="score_improvement",
+        choices=["score_improvement", "pass_only"],
+        help="Keep policy: score_improvement (default) or pass_only.")
+    parser.add_argument("--guard", default=None, metavar="CONDITION",
+        help="Guard condition that must remain true (e.g. 'all unit tests pass'). Hard stop if violated.")
+    parser.add_argument("--noise-runs", type=int, default=1, metavar="N",
+        help="Number of runs to median over for noisy metrics. Default: 1")
+    parser.add_argument("--min-delta", type=float, default=0.0, metavar="DELTA",
+        help="Minimum improvement required to keep a change. Default: 0 (any improvement counts).")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite this scaffold's generated files in a non-empty output directory.",
+    )
+    return parser.parse_args()
+
+
+def scaffold(goal: str, metric: str, direction: str, target: str, max_iterations: int, output: Path,
+             evaluator: Optional[str] = None, keep_policy: str = "score_improvement",
+             guard: Optional[str] = None, noise_runs: int = 1, min_delta: float = 0.0,
+             force: bool = False) -> None:
+    date = datetime.now().strftime("%Y-%m-%d")
+    title = goal_to_title(goal)
+    evaluator_str = f"`{evaluator}`" if evaluator else "_(none — agent judges manually)_"
+    guard_str = guard if guard else "_(none)_"
+
+    fd, output = open_safe_directory(output)
+    try:
+        entries = os.listdir(fd)
+        if entries and not force:
+            fail(
+                "OUTPUT_NOT_EMPTY",
+                f"output directory '{output}' already exists and is not empty. "
+                "Use --force to overwrite generated files.",
+            )
+        reject_unsafe_leaf(fd, "workspace", directory=True)
+        for leaf in MANAGED_FILE_LEAVES:
+            reject_unsafe_leaf(fd, leaf)
+        if force:
+            for leaf in MANAGED_FILE_LEAVES:
+                remove_regular_leaf(fd, output, leaf)
+        if leaf_info(fd, "workspace") is None:
+            verify_directory_identity(output, fd)
+            os.mkdir("workspace", 0o755, dir_fd=fd)
+
+    # Write research.md
+        research_text = RESEARCH_TEMPLATE.format(
+            title=title,
+            goal=goal,
+            metric=metric,
+            target=target,
+            direction=direction,
+            max_iterations=max_iterations,
+            evaluator=evaluator_str,
+            keep_policy=keep_policy,
+            guard=guard_str,
+            noise_runs=noise_runs,
+            min_delta=min_delta,
+            date=date,
+        )
+        write_new_leaf(fd, output, "research.md", research_text)
+
+    # Write research_log.md
+        write_new_leaf(fd, output, "research_log.md", LOG_TEMPLATE.format(date=date, goal=goal))
+
+    # Write autoresearch-results.tsv
+        write_new_leaf(fd, output, "autoresearch-results.tsv", TSV_HEADER + TSV_BASELINE.format(date=date))
+        verify_directory_identity(output, fd)
+    finally:
+        os.close(fd)
+
+    # Print success message
+    print(f"\nResearch project scaffolded at: {output.resolve()}")
+    print(f"\nFiles created:")
+    print(f"  {output / 'research.md'}")
+    print(f"  {output / 'research_log.md'}")
+    print(f"  {output / 'autoresearch-results.tsv'}")
+    print(f"  {output / 'workspace'}/")
+    print(f"\nNext steps:")
+    print(f"  1. Open research.md and fill in 'Current Approach' and 'Search Space'.")
+    print(f"  2. Add context (papers, docs, code) under 'Context & References'.")
+    print(f"  3. Run your baseline experiment and record it in the History table.")
+    print(f"  4. Start iterating: modify → measure → log → repeat.")
+    print("  5. Select $litcodex:autoresearch, approve a plan, then select $litcodex:start-work.")
+
+
+def main() -> None:
+    args = parse_args()
+    if args.max_iterations < 1:
+        fail("INVALID_BUDGET", "--max-iterations must be >= 1")
+    if args.noise_runs < 1:
+        fail("INVALID_BUDGET", "--noise-runs must be >= 1")
+    if not math.isfinite(args.min_delta) or args.min_delta < 0:
+        fail("INVALID_BUDGET", "--min-delta must be finite and >= 0")
+    preflight_capabilities()
+    output = Path(args.output)
+
+    scaffold(
+        goal=args.goal,
+        metric=args.metric,
+        direction=args.direction,
+        target=args.target,
+        max_iterations=args.max_iterations,
+        output=output,
+        evaluator=args.evaluator,
+        keep_policy=args.keep_policy,
+        guard=args.guard,
+        noise_runs=args.noise_runs,
+        min_delta=args.min_delta,
+        force=args.force,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/marketplace/plugins/litcodex/skills/autoresearch/scripts/style_presets.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Optional matplotlib style presets for installed LitCodex autoresearch runs.
+
+Call rcparams() before plt.subplots() or plt.figure(). Matplotlib snapshots rcParams
+when a figure is constructed, so a later call is silently ignored and every preset
+below — dpi, legend framing, the Okabe-Ito cycle, tick direction — is lost.
+"""
+
+import importlib
+import json
+import sys
+from typing import Dict
+
+
+OKABE_ITO = [
+    "#E69F00",
+    "#56B4E9",
+    "#009E73",
+    "#F0E442",
+    "#0072B2",
+    "#D55E00",
+    "#CC79A7",
+    "#000000",
+]
+
+
+def matplotlib_available() -> bool:
+    """Return whether the optional plotting dependency imports successfully."""
+    try:
+        importlib.import_module("matplotlib")
+    except Exception:
+        return False
+    return True
+
+
+def preflight_report() -> Dict[str, object]:
+    """Return a stable, non-installing optional dependency verdict."""
+    available = matplotlib_available()
+    return {
+        "available": available,
+        "code": (
+            "OPTIONAL_MATPLOTLIB_READY"
+            if available
+            else "BLOCKED_OPTIONAL_MATPLOTLIB_UNAVAILABLE"
+        ),
+    }
+
+
+def rcparams() -> None:
+    """Apply the retained style after an explicit dependency preflight."""
+    if not matplotlib_available():
+        raise RuntimeError("BLOCKED_OPTIONAL_MATPLOTLIB_UNAVAILABLE")
+
+    import matplotlib as mpl
+    from matplotlib import font_manager, rcParams
+
+    rcParams["font.family"] = "sans-serif"
+    available_fonts = {font.name for font in font_manager.fontManager.ttflist}
+    if "Pretendard" in available_fonts:
+        rcParams["font.sans-serif"] = ["Pretendard"]
+    elif "Arial" in available_fonts:
+        rcParams["font.sans-serif"] = ["Arial"]
+
+    rcParams.update(
+        {
+            "font.size": 14,
+            "axes.titlesize": 18,
+            "axes.titleweight": "normal",
+            "axes.titlepad": 10,
+            "axes.labelsize": 16,
+            "axes.labelweight": "normal",
+            "axes.labelpad": 8,
+            "axes.linewidth": 1,
+            "axes.edgecolor": "black",
+            "axes.labelcolor": "black",
+            "axes.axisbelow": True,
+            "axes.grid": False,
+            "axes.prop_cycle": mpl.cycler(color=OKABE_ITO),
+            "xtick.labelsize": 12,
+            "ytick.labelsize": 12,
+            "xtick.direction": "in",
+            "ytick.direction": "in",
+            "xtick.minor.visible": True,
+            "ytick.minor.visible": True,
+            "xtick.major.width": 1,
+            "ytick.major.width": 1,
+            "xtick.minor.width": 0.5,
+            "ytick.minor.width": 0.5,
+            "xtick.major.size": 5,
+            "ytick.major.size": 5,
+            "xtick.minor.size": 3,
+            "ytick.minor.size": 3,
+            "xtick.major.pad": 7,
+            "ytick.major.pad": 7,
+            "xtick.color": "black",
+            "ytick.color": "black",
+            "figure.figsize": (5, 4),
+            "figure.dpi": 100,
+            "figure.facecolor": "white",
+            "figure.autolayout": False,
+            "lines.linewidth": 1.5,
+            "lines.markersize": 5,
+            "lines.markeredgewidth": 0.5,
+            "legend.fontsize": 12,
+            "legend.frameon": True,
+            "legend.edgecolor": "black",
+            "legend.framealpha": 1,
+            "legend.loc": "best",
+            "savefig.dpi": 600,
+            "savefig.bbox": "tight",
+            "savefig.pad_inches": 0.05,
+            "savefig.transparent": False,
+            "savefig.facecolor": "white",
+            "image.cmap": "viridis",
+        }
+    )
+
+
+if __name__ == "__main__":
+    if sys.argv[1:] != ["--check"]:
+        print("Usage: python style_presets.py --check", file=sys.stderr)
+        raise SystemExit(2)
+    print(json.dumps(preflight_report(), sort_keys=True))