cogames 0.3.49__py3-none-any.whl → 0.3.64__py3-none-any.whl

cogames/cli/client.py

@@ -13,6 +13,26 @@ from cogames.cli.login import CoGamesAuthenticator
 T = TypeVar("T")
 
 
+def fetch_default_season(server_url: str) -> SeasonInfo:
+    with httpx.Client(base_url=server_url, timeout=10.0) as client:
+        resp = client.get("/tournament/seasons")
+        resp.raise_for_status()
+        seasons = resp.json()
+        for s in seasons:
+            if s.get("is_default"):
+                return SeasonInfo.model_validate(s)
+        if seasons:
+            return SeasonInfo.model_validate(seasons[0])
+    raise RuntimeError("No seasons available from server")
+
+
+def fetch_season_info(server_url: str, season_name: str) -> SeasonInfo:
+    with httpx.Client(base_url=server_url, timeout=10.0) as client:
+        resp = client.get(f"/tournament/seasons/{season_name}")
+        resp.raise_for_status()
+        return SeasonInfo.model_validate(resp.json())
+
+
 class PolicyVersionInfo(BaseModel):
     id: uuid.UUID
     policy_id: uuid.UUID
@@ -26,14 +46,27 @@ class PolicyVersionInfo(BaseModel):
 class PoolInfo(BaseModel):
     name: str
     description: str
+    config_id: str | None = None
 
 
 class SeasonInfo(BaseModel):
     name: str
+    version: int
+    canonical: bool
     summary: str
+    entry_pool: str | None = None
+    leaderboard_pool: str | None = None
+    is_default: bool = False
     pools: list[PoolInfo]
 
 
+class SeasonVersionInfo(BaseModel):
+    version: int
+    canonical: bool
+    disabled_at: str | None
+    created_at: str
+
+
 class LeaderboardEntry(BaseModel):
     rank: int
     policy: PolicyVersionSummary
@@ -147,8 +180,18 @@ class TournamentServerClient:
     def get_seasons(self) -> list[SeasonInfo]:
         return self._get("/tournament/seasons", list[SeasonInfo])
 
-    def get_leaderboard(self, season_name: str) -> list[LeaderboardEntry]:
-        return self._get(f"/tournament/seasons/{season_name}/leaderboard", list[LeaderboardEntry])
+    def get_config(self, config_id: str) -> dict[str, Any]:
+        return self._get(f"/tournament/configs/{config_id}")
+
+    def get_season_versions(self, season_name: str) -> list[SeasonVersionInfo]:
+        return self._get(f"/tournament/seasons/{season_name}/versions", list[SeasonVersionInfo])
+
+    def get_leaderboard(self, season_name: str, include_hidden_seasons: bool = False) -> list[LeaderboardEntry]:
+        return self._get(
+            f"/tournament/seasons/{season_name}/leaderboard",
+            list[LeaderboardEntry],
+            params={"include_hidden": "true"} if include_hidden_seasons else None,
+        )
 
     def get_my_policy_versions(
         self,
@@ -182,21 +225,32 @@ class TournamentServerClient:
             json={"policy_version_id": str(policy_version_id)},
         )
 
-    def get_season_policies(self, season_name: str, mine: bool = False) -> list[SeasonPolicyEntry]:
+    def get_season_policies(
+        self, season_name: str, mine: bool = False, include_hidden_seasons: bool = False
+    ) -> list[SeasonPolicyEntry]:
+        params: dict[str, str] = {}
+        if mine:
+            params["mine"] = "true"
+        if include_hidden_seasons:
+            params["include_hidden"] = "true"
+
         return self._get(
             f"/tournament/seasons/{season_name}/policies",
             list[SeasonPolicyEntry],
-            params={"mine": "true"} if mine else None,
+            params=params if params else None,
         )
 
     def get_presigned_upload_url(self) -> dict[str, Any]:
         return self._post("/stats/policies/submit/presigned-url", timeout=60.0)
 
-    def complete_policy_upload(self, upload_id: str, name: str) -> dict[str, Any]:
+    def complete_policy_upload(self, upload_id: str, name: str, season: str | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"upload_id": upload_id, "name": name}
+        if season is not None:
+            payload["season"] = season
         return self._post(
             "/stats/policies/submit/complete",
             timeout=120.0,
-            json={"upload_id": upload_id, "name": name},
+            json=payload,
         )
 
     def update_policy_version_tags(self, policy_version_id: uuid.UUID, tags: dict[str, str]) -> dict[str, Any]:

cogames/cli/docsync/_nb_md_directive_processing.py

@@ -0,0 +1,180 @@
+"""
+Convert notebook to markdown using nbconvert.
+"""
+
+import nbformat
+from nbconvert.preprocessors import Preprocessor
+
+_COLAB_URL_BASE = "https://colab.research.google.com/github/Metta-AI/cogames/blob/main"
+
+
+class DirectivePreprocessor(Preprocessor):
+    """Process directives in code cells."""
+
+    def preprocess_cell(self, cell, resources, index):
+        del index  # unused
+
+        # Handle <<colab-link>> placeholder in markdown cells
+        if cell.cell_type == "markdown" and "<<colab-link>>" in cell.source:
+            notebook_relpath = resources["notebook_relpath"]
+            colab_url = f"{_COLAB_URL_BASE}/{notebook_relpath}"
+            cell.source = cell.source.replace("<<colab-link>>", colab_url)
+            return cell, resources
+
+        if cell.cell_type != "code":
+            return cell, resources
+
+        source = cell.source
+        if not source.strip():
+            return cell, resources
+
+        lines = source.split("\n")
+        first_line = lines[0].strip()
+
+        if not (first_line.startswith("# <<") and ">>" in first_line):
+            return cell, resources
+
+        # Extract directive from "# <<directive>>" format
+        directive = first_line[4 : first_line.index(">>")].strip()
+        rest_source = "\n".join(lines[1:])
+
+        if directive == "hide":
+            # Mark cell for removal
+            cell.source = ""
+            cell.outputs = []
+            cell.metadata["remove_cell"] = True
+
+        elif directive == "hide-input":
+            # Keep outputs, hide code using TagRemovePreprocessor
+            cell.source = rest_source
+            cell.metadata.setdefault("tags", []).append("remove_input")
+
+        elif directive == "hide-output":
+            # Keep code, hide outputs
+            cell.source = rest_source
+            cell.outputs = []
+
+        elif directive == "collapse-input":
+            # Will be handled in post-processing
+            cell.source = rest_source
+            cell.metadata["collapse_input"] = True
+
+        elif directive == "collapse-output":
+            # Will be handled in post-processing
+            cell.source = rest_source
+            cell.metadata["collapse_output"] = True
+
+        return cell, resources
+
+    def preprocess(self, nb, resources):
+        # First pass: process directives
+        nb, resources = super().preprocess(nb=nb, resources=resources)
+
+        # Second pass: remove cells marked for removal
+        nb.cells = [cell for cell in nb.cells if not cell.get("metadata", {}).get("remove_cell", False)]
+
+        # Also remove empty code cells (from hide-input with no output)
+        nb.cells = [
+            cell for cell in nb.cells if not (cell.cell_type == "code" and not cell.source.strip() and not cell.outputs)
+        ]
+
+        return nb, resources
+
+
+def directive_post_process(*, md: str, nb: nbformat.NotebookNode) -> str:
+    """Wrap collapsed cells in <details> tags."""
+
+    # Build list of (collapse_input, collapse_output) for each code cell that has visible code.
+    # Skip cells with "remove_input" tag since their code block is removed from markdown.
+    collapse_info = []
+    for cell in nb.cells:
+        if cell.cell_type == "code" and cell.source.strip():
+            meta = cell.get("metadata", {})
+            tags = meta.get("tags", [])
+            # Skip cells whose input is removed (no code block in markdown)
+            if "remove_input" in tags:
+                continue
+            collapse_info.append(
+                (
+                    meta.get("collapse_input", False),
+                    meta.get("collapse_output", False),
+                )
+            )
+
+    if not any(collapse_input or collapse_output for collapse_input, collapse_output in collapse_info):
+        return md
+
+    # Process markdown line by line
+    # nbconvert outputs: ```python ... ``` for code, then indented lines for output
+    lines = md.split("\n")
+    result = []
+    code_cell_idx = 0
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+
+        # Detect start of code block
+        if line.startswith("```python"):
+            code_block_lines = [line]
+            i += 1
+
+            # Collect code block
+            while i < len(lines) and not (lines[i].startswith("```") and len(lines[i].strip()) == 3):
+                code_block_lines.append(lines[i])
+                i += 1
+            if i < len(lines):
+                code_block_lines.append(lines[i])  # closing ```
+                i += 1
+
+            # Check for collapse_input
+            collapse_input = False
+            collapse_output = False
+            if code_cell_idx < len(collapse_info):
+                collapse_input, collapse_output = collapse_info[code_cell_idx]
+
+            # Output code block (possibly wrapped)
+            if collapse_input:
+                result.append("<details>")
+                result.append("<summary>Code</summary>")
+                result.append("")
+                result.extend(code_block_lines)
+                result.append("")
+                result.append("</details>")
+            else:
+                result.extend(code_block_lines)
+
+            # Collect output (indented lines or empty lines between code and next content)
+            output_lines = []
+            while i < len(lines):
+                # Output lines are typically indented with 4 spaces
+                if lines[i].startswith("    ") or lines[i] == "":
+                    output_lines.append(lines[i])
+                    i += 1
+                else:
+                    break
+
+            # Strip trailing empty lines from output
+            while output_lines and output_lines[-1] == "":
+                output_lines.pop()
+
+            # Output the output (possibly wrapped)
+            if output_lines:
+                if collapse_output:
+                    result.append("")
+                    result.append("<details>")
+                    result.append("<summary>Output</summary>")
+                    result.append("")
+                    result.extend(output_lines)
+                    result.append("")
+                    result.append("</details>")
+                else:
+                    result.extend(output_lines)
+
+            result.append("")  # blank line after cell
+            code_cell_idx += 1
+        else:
+            result.append(line)
+            i += 1
+
+    return "\n".join(result)

cogames/cli/docsync/_nb_md_sync.py

@@ -0,0 +1,103 @@
+"""
+Convert notebook to markdown using nbconvert.
+"""
+
+from pathlib import Path
+from typing import TypedDict
+
+import nbformat
+from nbconvert import MarkdownExporter
+from nbconvert.preprocessors import TagRemovePreprocessor
+
+from cogames.cli.docsync._nb_md_directive_processing import DirectivePreprocessor, directive_post_process
+from cogames.cli.docsync._utils import clean_notebook_metadata, run_notebook
+
+
+class NotebookResources(TypedDict):
+    """Resources returned by nbconvert."""
+
+    outputs: dict[str, bytes]
+    output_files_dir: str
+
+
+def convert_nb_to_md_in_memory(
+    *, nb_path: Path, cogames_root: Path, notebook_relpath: Path | None = None
+) -> tuple[str, NotebookResources]:
+    """Convert .ipynb to .md and resource files using nbconvert.
+
+    Args:
+        nb_path: Path to the notebook file to read.
+        cogames_root: Root path for cogames package (used to compute relative path if notebook_relpath not provided).
+        notebook_relpath: Optional override for the relative path used in Colab URL generation.
+            Useful when the notebook is in a temp directory but we need the original relative path.
+    """
+
+    # This tells nbconvert where we'll write output files later, so it can reference them now.
+    output_files_dir = f"{nb_path.stem}_files"
+
+    exporter = MarkdownExporter()
+    exporter.register_preprocessor(DirectivePreprocessor, enabled=True)
+
+    # Register TagRemovePreprocessor to properly hide input for # <<hide-input>> cells.
+    # This removes the code block entirely rather than leaving an empty code block.
+    tag_remove_preprocessor = TagRemovePreprocessor()
+    tag_remove_preprocessor.remove_input_tags = {"remove_input"}
+    exporter.register_preprocessor(tag_remove_preprocessor, enabled=True)
+
+    nb = nbformat.read(nb_path, as_version=4)
+    if notebook_relpath is None:
+        notebook_relpath = nb_path.relative_to(cogames_root)
+    md, resources = exporter.from_notebook_node(
+        nb=nb,
+        resources={
+            "output_files_dir": output_files_dir,
+            "notebook_relpath": notebook_relpath,
+        },
+    )
+
+    # Run preprocessor again on nb to set collapse metadata (nbconvert modifies a copy internally).
+    DirectivePreprocessor().preprocess(nb=nb, resources={"notebook_relpath": notebook_relpath})
+    md = directive_post_process(md=md, nb=nb)
+
+    return md, resources
+
+
+def _write_notebook_output(*, to_dir: Path, name: str, md: str, resources: NotebookResources) -> None:
+    """Write notebook output to the given directory."""
+
+    # Write resources (images, etc.)
+    # Note: filename keys already include the subdirectory (e.g., "test_files/output_0_0.png")
+    output_files = resources["outputs"]
+    output_files_dir = resources["output_files_dir"]
+    if len(output_files) > 0:
+        files_dir = to_dir / output_files_dir
+        files_dir.mkdir(exist_ok=True)
+        for filename, data in output_files.items():
+            (to_dir / filename).write_bytes(data)
+
+    # Write markdown.
+    output_path = to_dir / f"{name}.md"
+    output_path.write_text(md)
+
+
+def convert_nb_to_md(*, nb_path: Path, should_rerun: bool, cogames_root: Path) -> None:
+    """Export a notebook to markdown in the same directory.
+
+    Args:
+        nb_path: Path to the notebook file.
+        should_rerun: Whether to re-run the notebook before exporting.
+        cogames_root: Root path for cogames package, used to compute the relative
+            path for Colab URL generation.
+    """
+    # Resolve to absolute paths for consistent handling (macOS symlinks /var -> /private/var)
+    nb_path = nb_path.resolve()
+    cogames_root = cogames_root.resolve()
+
+    if should_rerun:
+        run_notebook(nb_path=nb_path)
+
+    md, resources = convert_nb_to_md_in_memory(nb_path=nb_path, cogames_root=cogames_root)
+
+    _write_notebook_output(to_dir=nb_path.parent, name=nb_path.stem, md=md, resources=resources)
+
+    clean_notebook_metadata(nb_path=nb_path)

cogames/cli/docsync/_nb_py_sync.py

@@ -0,0 +1,122 @@
+"""Convert notebook to/from Python using jupytext."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+import jupytext
+import questionary
+import typer
+
+from cogames.cli.docsync._utils import clean_notebook_metadata, lint_py_file, py_nb_content_equal, run_notebook
+
+
+def convert_nb_to_py(*, nb_path: Path, py_path: Path) -> None:
+    """Convert .ipynb to .py percent format using jupytext."""
+    nb = jupytext.read(nb_path)
+    jupytext.write(nb, py_path, fmt="py:percent")
+    lint_py_file(py_path)
+
+
+def convert_py_to_nb(*, py_path: Path, nb_path: Path, should_rerun: bool) -> None:
+    """Convert .py to .ipynb using jupytext, optionally execute."""
+    nb = jupytext.read(py_path)
+    jupytext.write(nb, nb_path)
+
+    if should_rerun:
+        run_notebook(nb_path=nb_path)
+
+    clean_notebook_metadata(nb_path=nb_path)
+
+
+def _format_mtime(path: Path) -> str:
+    """Format file mtime with millisecond precision."""
+    mtime = path.stat().st_mtime
+    dt = datetime.fromtimestamp(mtime)
+    ms = int((mtime % 1) * 1000)
+    return f"{dt.strftime('%Y-%m-%d %H:%M:%S')}.{ms:03d}"
+
+
+def _prompt_sync_direction(*, py_path: Path, nb_path: Path) -> Literal["py", "nb", "skip"]:
+    """Prompt user to choose sync direction. Returns 'py', 'nb', or 'skip'."""
+    nb_mtime = nb_path.stat().st_mtime
+    py_mtime = py_path.stat().st_mtime
+    py_newer = py_mtime > nb_mtime
+
+    # Format: ".ipynb → .py     (newer)  2026-01-21 10:30:15.456"
+    #         "   .py → .ipynb           2026-01-22 15:45:32.123"
+    newer_tag = "(newer)"
+    blank_pad = " " * len(newer_tag)
+    nb_label = f".ipynb → .py     {newer_tag if not py_newer else blank_pad}  {_format_mtime(nb_path)}"
+    py_label = f"   .py → .ipynb  {newer_tag if py_newer else blank_pad}  {_format_mtime(py_path)}"
+
+    choice = questionary.select(
+        f"{py_path.stem}.py and {py_path.stem}.ipynb are out of sync. Which should be source of truth?",
+        choices=[nb_label, py_label, "Skip"],
+    ).ask()
+
+    if choice is None:
+        return "skip"
+    elif ".py →" in choice:
+        return "py"
+    elif ".ipynb →" in choice:
+        return "nb"
+    else:
+        return "skip"
+
+
+def sync_nb_and_py_by_user_choice(*, py_path: Path, nb_path: Path, should_rerun: bool) -> bool:
+    """Sync .py/.ipynb with each other based on user selection. Returns whether notebook was re-run.
+
+    Args:
+        py_path: Path to .py file
+        nb_path: Path to .ipynb file
+        should_rerun: Whether to re-run notebook after syncing py->nb
+    """
+
+    if py_path.exists() and nb_path.exists():
+        # Check if content is already equal (no sync needed)
+        if py_nb_content_equal(py_path=py_path, nb_path=nb_path):
+            typer.echo(f"  {py_path.name} and {nb_path.name} are already in sync")
+            return False
+
+        # Prompt user to choose sync direction
+        choice = _prompt_sync_direction(py_path=py_path, nb_path=nb_path)
+
+        # Perform sync based on user choice
+        match choice:
+            case "py":
+                typer.echo("  Syncing .py → .ipynb...")
+                convert_py_to_nb(py_path=py_path, nb_path=nb_path, should_rerun=should_rerun)
+                typer.echo(f"  Synced {py_path.name} → {nb_path.name}")
+                py_path.touch()  # Touch source so it stays "newer"
+                return should_rerun
+            case "nb":
+                typer.echo("  Syncing .ipynb → .py...")
+                convert_nb_to_py(nb_path=nb_path, py_path=py_path)
+                typer.echo(f"  Synced {nb_path.name} → {py_path.name}")
+                nb_path.touch()  # Touch source so it stays "newer"
+                return False
+            case "skip":
+                typer.echo(f"  Skipping {py_path.stem}")
+                return False
+
+    elif py_path.exists():
+        typer.echo(f"  Only {py_path.name} exists, creating .ipynb...")
+        convert_py_to_nb(py_path=py_path, nb_path=nb_path, should_rerun=should_rerun)
+        typer.echo(f"  Created {nb_path.name}")
+        # Touch the original file (not the created one)
+        py_path.touch()
+        return should_rerun
+
+    elif nb_path.exists():
+        typer.echo(f"  Only {nb_path.name} exists, creating .py...")
+        convert_nb_to_py(nb_path=nb_path, py_path=py_path)
+        typer.echo(f"  Created {py_path.name}")
+        # Touch the original file (not the created one)
+        nb_path.touch()
+        return False
+
+    else:
+        typer.echo(f"  Error: neither {py_path.name} nor {nb_path.name} exist", err=True)
+        raise typer.Exit(1)

cogames/cli/docsync/_three_way_sync.py

@@ -0,0 +1,115 @@
+"""Three-way sync between .py, .ipynb, and .md files."""
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+import typer
+
+from cogames.cli.docsync._nb_md_sync import convert_nb_to_md, convert_nb_to_md_in_memory
+from cogames.cli.docsync._nb_py_sync import convert_nb_to_py, sync_nb_and_py_by_user_choice
+from cogames.cli.docsync._utils import files_equal, lint_py_file
+
+
+def get_stem_paths(*, cogames_root: Path) -> list[Path]:
+    """Get all notebook stem paths (README + tutorials/*)."""
+    stem_paths: list[Path] = []
+
+    # README notebook at root
+    readme_nb_path = cogames_root / "README.ipynb"
+    if readme_nb_path.exists():
+        stem_paths.append(readme_nb_path.with_suffix(""))
+
+    # Notebooks in tutorials directory
+    tutorials_dir = cogames_root / "tutorials"
+    if tutorials_dir.exists():
+        stem_paths.extend(sorted({nb_path.with_suffix("") for nb_path in tutorials_dir.glob("*.ipynb")}))
+
+    return stem_paths
+
+
+def sync_stem_three_way(*, stem_path: Path, should_rerun: bool, cogames_root: Path) -> None:
+    """Sync .py and .ipynb with each other based on mtime, then export to .md."""
+
+    py_path = stem_path.with_suffix(".py")
+    nb_path = stem_path.with_suffix(".ipynb")
+
+    did_rerun = sync_nb_and_py_by_user_choice(
+        py_path=py_path,
+        nb_path=nb_path,
+        should_rerun=should_rerun,
+    )
+
+    typer.echo(f"  Exporting {nb_path.name} to markdown...")
+    still_should_rerun = should_rerun and not did_rerun
+    convert_nb_to_md(nb_path=nb_path, should_rerun=still_should_rerun, cogames_root=cogames_root)
+    typer.echo(f"  Exported {nb_path.name} → {nb_path.stem}.md")
+
+
+def is_stem_in_sync_three_way(*, stem_path: Path, should_rerun: bool, cogames_root: Path) -> list[str]:
+    """Check if .py, .ipynb, .md for a stem are in sync. Returns list of errors."""
+    errors: list[str] = []
+    py_path = stem_path.with_suffix(".py")
+    nb_path = stem_path.with_suffix(".ipynb")
+    md_path = stem_path.with_suffix(".md")
+
+    # All three files must exist
+    if not py_path.exists():
+        errors.append(f"{py_path.name} is missing")
+    if not md_path.exists():
+        errors.append(f"{md_path.name} is missing")
+    if not nb_path.exists():
+        errors.append(f"{nb_path.name} is missing")
+        return errors  # Can't check further without .ipynb
+
+    # Work with a temp copy of the notebook to avoid modifying original
+    # Maintain directory structure so relative_to(cogames_root) works
+    with tempfile.TemporaryDirectory() as tmpdir:
+        notebook_relpath = nb_path.relative_to(cogames_root)
+        tmp_nb_path = Path(tmpdir) / notebook_relpath
+        tmp_nb_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(nb_path, tmp_nb_path)
+
+        # Optionally re-run the notebook (in original working dir so paths work)
+        if should_rerun:
+            typer.echo(f"  Re-running {nb_path.name}...")
+            result = subprocess.run(
+                ["jupyter", "execute", str(tmp_nb_path), "--inplace"],
+                cwd=nb_path.parent,  # Use original working dir for relative paths
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                errors.append(f"{nb_path.name} failed to execute: {result.stderr}")
+                return errors
+
+        # Convert temp .ipynb -> temp .py, compare with existing .py
+        if py_path.exists():
+            tmp_py_path = Path(tmpdir) / py_path.name
+            convert_nb_to_py(nb_path=tmp_nb_path, py_path=tmp_py_path)
+            # Copy and format existing .py for fair comparison
+            tmp_existing_py = Path(tmpdir) / f"existing_{py_path.name}"
+            shutil.copy(py_path, tmp_existing_py)
+            lint_py_file(tmp_existing_py)
+            if not files_equal(tmp_py_path, tmp_existing_py):
+                errors.append(f"{py_path.name} doesn't match {nb_path.name}")
+
+        # Convert temp .ipynb -> temp .md, compare with existing .md and resources
+        if md_path.exists():
+            md_content, resources = convert_nb_to_md_in_memory(nb_path=tmp_nb_path, cogames_root=Path(tmpdir))
+            tmp_md_path = Path(tmpdir) / md_path.name
+            tmp_md_path.write_text(md_content)
+            if not files_equal(tmp_md_path, md_path):
+                errors.append(f"{md_path.name} doesn't match {nb_path.name}")
+
+            # Compare resources (images, etc.)
+            output_files = resources["outputs"]
+            for filename, generated_data in output_files.items():
+                existing_path = nb_path.parent / filename
+                if not existing_path.exists():
+                    errors.append(f"{filename} is missing")
+                elif existing_path.read_bytes() != generated_data:
+                    errors.append(f"{filename} doesn't match {nb_path.name}")
+
+    return errors