rom-manager 1.0.0__py3-none-any.whl

rom_manager/__init__.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+"""rom-manager — ROM converter/organizer + MCP Server + A2A Agent.
+
+Convert game ROMs to Compressed Hunks of Data (CHD) or RVZ, extract archives,
+auto-rename via known game codes, and generate cue sheets. The core
+:class:`RomManager` pipeline is wrapped by an MCP server and a Pydantic-AI agent.
+"""
+
+from rom_manager.game_codes import psx_codes
+from rom_manager.rom_manager import (
+    RomManager,
+    get_directory_size,
+    get_operating_system,
+    main,
+    rom_manager,
+)
+from rom_manager.version import __author__, __credits__, __version__
+
+__all__ = [
+    "psx_codes",
+    "rom_manager",
+    "main",
+    "RomManager",
+    "get_operating_system",
+    "get_directory_size",
+    "__version__",
+    "__author__",
+    "__credits__",
+]

rom_manager/__main__.py

@@ -0,0 +1,4 @@
+from rom_manager.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

rom_manager/adapters/__init__.py

@@ -0,0 +1,22 @@
+"""Adapter layer for ROM Manager.
+
+CONCEPT:ROM-001, CONCEPT:ROM-002 — adapts the core pipeline for tool/agent
+consumption. Houses the :class:`~rom_manager.adapters.api_client.Api` facade that
+the MCP tools and the ``auth.get_client`` factory depend on.
+"""
+
+from rom_manager.adapters.api_client import (
+    Api,
+    RomManager,
+    get_directory_size,
+    get_operating_system,
+    psx_codes,
+)
+
+__all__ = [
+    "Api",
+    "RomManager",
+    "psx_codes",
+    "get_operating_system",
+    "get_directory_size",
+]

rom_manager/adapters/api_client.py

@@ -0,0 +1,147 @@
+#!/usr/bin/python
+"""Local facade over the real ROM conversion pipeline.
+
+``rom-manager`` is not a REST API; this module is an **honest local facade**. It
+re-exports the real callables from :mod:`rom_manager.rom_manager` and exposes a
+thin :class:`Api` class that the MCP tools and the local ``auth.get_client``
+factory depend on. Every method delegates to the genuine :class:`RomManager`
+pipeline so behaviour is preserved exactly.
+"""
+
+import logging
+import os
+from typing import Any
+
+from agent_utilities.base_utilities import get_logger
+
+from rom_manager.game_codes import psx_codes
+from rom_manager.rom_manager import (
+    RomManager,
+    get_directory_size,
+    get_operating_system,
+)
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "Api",
+    "RomManager",
+    "psx_codes",
+    "get_operating_system",
+    "get_directory_size",
+]
+
+
+class Api:
+    """Thin facade wrapping :class:`RomManager` for tool/agent consumption."""
+
+    __slots__ = ("directory", "iso_type", "verbose", "force")
+
+    def __init__(
+        self,
+        directory: str = os.path.curdir,
+        iso_type: str = "chd",
+        verbose: bool = False,
+        force: bool = False,
+    ) -> None:
+        """Hold conversion defaults for the facade (CONCEPT:ROM-001)."""
+        self.directory = directory
+        self.iso_type = iso_type
+        self.verbose = verbose
+        self.force = force
+
+    def _build_manager(
+        self,
+        directory: str | None = None,
+        iso_type: str | None = None,
+        verbose: bool | None = None,
+        force: bool | None = None,
+        clean_origin_files: bool = False,
+    ) -> RomManager:
+        manager = RomManager()
+        manager.directory = directory if directory is not None else self.directory
+        manager.iso_type = iso_type if iso_type is not None else self.iso_type
+        manager.verbose = verbose if verbose is not None else self.verbose
+        manager.force = force if force is not None else self.force
+        manager.clean_origin_files = clean_origin_files
+        return manager
+
+    # --- Conversion domain -------------------------------------------------
+    def convert(
+        self,
+        directory: str | None = None,
+        cpu_count: int | None = None,
+        iso_type: str | None = None,
+        verbose: bool | None = None,
+        force: bool | None = None,
+        clean_origin_files: bool = False,
+    ) -> dict[str, Any]:
+        """Run the full parallel conversion pipeline over a directory (CONCEPT:ROM-001)."""
+        manager = self._build_manager(
+            directory=directory,
+            iso_type=iso_type,
+            verbose=verbose,
+            force=force,
+            clean_origin_files=clean_origin_files,
+        )
+        before = get_directory_size(directory=manager.directory)
+        results = manager.process_parallel(cpu_count=cpu_count)
+        after = get_directory_size(directory=manager.directory)
+        return {
+            "directory": manager.directory,
+            "iso_type": manager.iso_type,
+            "files_processed": len(results) if results else 0,
+            "size_before_gb": round(before[3], 4),
+            "size_after_gb": round(after[3], 4),
+            "storage_delta_gb": round(before[3] - after[3], 4),
+        }
+
+    # alias — convert an entire directory tree
+    process_directory = convert
+
+    def process_file(
+        self,
+        file: str,
+        iso_type: str | None = None,
+        verbose: bool | None = None,
+        force: bool | None = None,
+    ) -> dict[str, Any]:
+        """Process a single ROM file through the conversion pipeline (CONCEPT:ROM-001)."""
+        manager = self._build_manager(iso_type=iso_type, verbose=verbose, force=force)
+        manager.process_file(
+            file=file,
+            logger_name=manager.logger_name,
+            logger_level=logging.WARNING,
+            logger_format=manager.logger_format,
+        )
+        return {"file": file, "status": "processed"}
+
+    def generate_cue(self, directory: str) -> dict[str, Any]:
+        """Generate a missing ``.cue`` sheet for ``.bin`` tracks in a directory."""
+        manager = self._build_manager(directory=directory)
+        cue_path = manager.cue_file_generator(directory=directory)
+        return {"directory": directory, "cue_file": cue_path}
+
+    def list_files(self, directory: str, extensions: list[str] | None = None):
+        """List ROM/archive files under a directory matching extensions."""
+        manager = self._build_manager(directory=directory)
+        exts = tuple(extensions) if extensions else manager.supported_extensions
+        return manager.get_files(directory=directory, extensions=exts)
+
+    # --- Game codes domain -------------------------------------------------
+    @staticmethod
+    def lookup_game_code(code: str) -> dict[str, Any]:
+        """Look up a single game code -> name in the PSX code registry."""
+        return {"code": code, "name": psx_codes.get(code)}
+
+    @staticmethod
+    def list_game_codes(prefix: str | None = None) -> dict[str, str]:
+        """List known game codes, optionally filtered by a code prefix."""
+        if prefix:
+            return {k: v for k, v in psx_codes.items() if k.startswith(prefix)}
+        return dict(psx_codes)
+
+    def rename_by_game_code(self, file: str) -> dict[str, Any]:
+        """Rename a file in-place using the embedded game code, if recognised."""
+        renamed = RomManager.map_game_code_name(file=file, logger=logger)
+        return {"original": file, "renamed": renamed, "changed": renamed != file}

rom_manager/agent_data/IDENTITY.md

@@ -0,0 +1,21 @@
+# IDENTITY.md - ROM Manager Agent Identity
+
+## [default]
+ * **Name:** ROM Manager
+ * **Role:** Agent for converting and organizing game ROMs (CHD/RVZ)
+ * **Emoji:** 👾
+
+ ### System Prompt
+ You are the ROM Manager Agent.
+ You must always first run `list_skills` to show all skills.
+ Then, use the `mcp-client` universal skill and check the reference documentation for `rom-manager.md` to discover the exact tags and tools available for your capabilities.
+
+ ### Capabilities
+ - **ROM Conversion**: Convert game ROMs to CHD (`chdman`) or RVZ (`dolphin-tool`), extract archives, and generate `.cue` sheets via the `conversion` tool domain (CONCEPT:ROM-001).
+ - **Game Codes / Naming**: Resolve game/serial codes to titles and rename ROM files using the embedded code registry via the `game-codes` tool domain (CONCEPT:ROM-002).
+ - **MCP Operations**: Leverage the `mcp-client` skill to interact with the target MCP server. Refer to `rom-manager.md` for specific tool capabilities.
+ - **Custom Agent**: Handle custom tasks or general tasks.
+
+ ### Safety
+ - Always recommend backing up ROMs before running destructive (`clean_origin_files`/delete) operations.
+ - Verify the external `chdman` / `dolphin-tool` binaries are installed before attempting conversions.

rom_manager/agent_server.py

@@ -0,0 +1,96 @@
+#!/usr/bin/python
+"""ROM Manager A2A agent server.
+
+CONCEPT:ROM-001, CONCEPT:ROM-002 — exposes the ROM conversion and game-codes
+tool domains over an A2A/AG-UI surface. The agent is driven by the
+agent-utilities router, the integration point for the cross-project bridge
+capabilities CONCEPT:ORCH-1.2 (Confidence-Gated Router), CONCEPT:OS-5.2
+(Cognitive Scheduler) and CONCEPT:KG-2.0 (Knowledge Graph Core ingestion of the
+tool surface).
+"""
+
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "1.0.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    """Launch the ROM Manager A2A agent (CONCEPT:ROM-001, CONCEPT:ORCH-1.2)."""
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "ROM Manager")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get(
+            "description",
+            "AI agent for converting and organizing game ROMs (CHD/RVZ).",
+        ),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    # Start server using the auto-discovery pattern (from mcp_config.json)
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

rom_manager/api_client.py

@@ -0,0 +1,22 @@
+"""Backwards-compatible shim re-exporting the API facade adapter.
+
+The real implementation now lives in :mod:`rom_manager.adapters.api_client` (the
+adapter layer). This shim preserves the historical ``rom_manager.api_client``
+import path used by ``auth.get_client`` and the MCP tools. CONCEPT:ROM-001.
+"""
+
+from rom_manager.adapters.api_client import (
+    Api,
+    RomManager,
+    get_directory_size,
+    get_operating_system,
+    psx_codes,
+)
+
+__all__ = [
+    "Api",
+    "RomManager",
+    "psx_codes",
+    "get_operating_system",
+    "get_directory_size",
+]

rom_manager/archives.py

@@ -0,0 +1,24 @@
+"""Backwards-compatible shim re-exporting the archives domain module.
+
+The real implementation now lives in :mod:`rom_manager.core.archives` (the
+domain layer). This shim preserves the historical ``rom_manager.archives``
+import path. CONCEPT:ROM-001.
+"""
+
+from rom_manager.core.archives import (
+    ARCHIVE_FORMATS,
+    cue_file_generator,
+    extract_archive,
+    get_files,
+    is_archive,
+    pad_leading_zero,
+)
+
+__all__ = [
+    "ARCHIVE_FORMATS",
+    "cue_file_generator",
+    "extract_archive",
+    "get_files",
+    "is_archive",
+    "pad_leading_zero",
+]

rom_manager/auth.py

@@ -0,0 +1,47 @@
+"""ROM Manager local configuration / client factory.
+
+Unlike network-backed connectors (e.g. ``gitlab-api``), ``rom-manager`` is a
+**local CLI tool**: it extracts archives, renames ROMs via known game codes, and
+converts ISO/WBFS images to CHD/RVZ using locally-installed binaries
+(``chdman`` / ``dolphin-tool``). There is therefore **no service URL and no
+required credentials**.
+
+This module mirrors the ecosystem ``auth.py`` shape (a ``get_client`` factory
+the MCP tools depend on) but degrades to a no-op/local configuration. The only
+recognised setting is the optional ``ROM_DIRECTORY`` environment variable, used
+as the default working directory when none is supplied.
+"""
+
+import os
+
+from agent_utilities.base_utilities import get_logger, to_boolean
+
+from rom_manager.api_client import Api
+
+logger = get_logger(__name__)
+
+
+def get_client(
+    directory: str | None = None,
+    iso_type: str = os.getenv("ROM_ISO_TYPE", "chd"),
+    verbose: bool = to_boolean(string=os.getenv("ROM_VERBOSE", "False")),
+    force: bool = to_boolean(string=os.getenv("ROM_FORCE", "False")),
+    config: dict | None = None,
+) -> Api:
+    """Factory returning the local ROM Manager :class:`Api` facade (CONCEPT:ROM-001).
+
+    No credentials are required. ``directory`` defaults to ``ROM_DIRECTORY`` (or
+    the current working directory). ``iso_type`` selects the conversion target
+    (``chd`` or ``rvz``).
+    """
+    resolved_directory = directory or os.getenv("ROM_DIRECTORY") or os.path.curdir
+    logger.info(
+        "Creating local ROM Manager client",
+        extra={"directory": resolved_directory, "iso_type": iso_type},
+    )
+    return Api(
+        directory=resolved_directory,
+        iso_type=iso_type if iso_type in ("chd", "rvz") else "chd",
+        verbose=verbose,
+        force=force,
+    )

rom_manager/conversion.py

@@ -0,0 +1,15 @@
+"""Backwards-compatible shim re-exporting the conversion domain module.
+
+The real implementation now lives in :mod:`rom_manager.core.conversion` (the
+domain layer). This shim preserves the historical ``rom_manager.conversion``
+import path. CONCEPT:ROM-001.
+"""
+
+from rom_manager.core.conversion import (
+    Converter,
+    Runner,
+    build_convert_command,
+    run_command,
+)
+
+__all__ = ["Converter", "Runner", "build_convert_command", "run_command"]

rom_manager/core/__init__.py

@@ -0,0 +1,12 @@
+"""Domain (core) layer for ROM Manager.
+
+CONCEPT:ROM-001, CONCEPT:ROM-002 — the pure pipeline responsibilities, free of
+transport/CLI concerns: archive handling, conversion command construction, and
+game-code naming. The top-level orchestrator (:class:`rom_manager.rom_manager.
+RomManager`) composes these. Thin re-export shims at the package root
+(``rom_manager.archives`` etc.) preserve the historical import paths.
+"""
+
+from rom_manager.core import archives, conversion, naming
+
+__all__ = ["archives", "conversion", "naming"]

rom_manager/core/archives.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python
+"""Archive extraction and ``.cue`` sheet generation.
+
+CONCEPT:ROM-001 — ROM Conversion (pre-processing stage). Owns the archive
+responsibilities split out of the former ``rom_manager`` god-module: detecting
+supported archive formats, extracting them (via the optional ``patool`` native
+extra), and synthesising missing ``.cue`` sheets from ``.bin`` tracks.
+"""
+
+import glob
+import logging
+import os
+
+# Supported archive container formats (extraction inputs).
+ARCHIVE_FORMATS: tuple[str, ...] = (
+    ".7z",
+    ".zip",
+    ".tar.gz",
+    ".gz",
+    ".gzip",
+    ".bz2",
+    ".bzip2",
+    ".rar",
+    ".tar",
+)
+
+_NULL_LOGGER = logging.getLogger("rom_manager.archives")
+_NULL_LOGGER.addHandler(logging.NullHandler())
+
+
+def is_archive(file: str) -> bool:
+    """Return ``True`` if ``file`` has a supported archive extension."""
+    return file.lower().endswith(ARCHIVE_FORMATS)
+
+
+def get_files(directory, extensions) -> list[str]:
+    """Recursively list files under ``directory`` matching ``extensions``."""
+    matching_files = []
+    for root, _dirs, files in os.walk(directory):
+        for file in files:
+            if any(file.endswith(ext) for ext in extensions):
+                matching_files.append(os.path.join(root, file))
+    return matching_files
+
+
+def pad_leading_zero(number) -> str:
+    """Zero-pad ``number`` to a two-character track index (e.g. ``2`` -> ``02``)."""
+    padded = "0" + str(number)
+    return padded[-2:]
+
+
+def cue_file_generator(directory, logger=None) -> str:
+    """Generate a ``.cue`` sheet from the ``.bin`` tracks in ``directory``.
+
+    CONCEPT:ROM-001 — emits a standard CD cue sheet (track 01 ``MODE2/2352``,
+    subsequent tracks ``AUDIO``) so ``chdman`` can ingest multi-track ``.bin``
+    images. Returns the path to the (existing or newly written) cue file.
+    """
+    file_names = get_files(directory=directory, extensions=[".bin"])
+    first_file = file_names.pop(0)
+    first_file = os.path.basename(first_file)
+    sheet = (
+        f'FILE "{first_file}" BINARY\n  TRACK 01 MODE2/2352\n    INDEX 01 00:00:00\n'
+    )
+    track_counter = 2
+    for file_name in file_names:
+        sheet += (
+            f'FILE "{file_name}" BINARY\n'
+            f"  TRACK {pad_leading_zero(track_counter)} AUDIO\n"
+            f"    INDEX 00 00:00:00\n"
+            f"    INDEX 01 00:02:00\n"
+        )
+        track_counter += 1
+    cue_file_path = os.path.join(
+        directory, f"{os.path.splitext(os.path.basename(first_file))[0]}.cue"
+    )
+    if not os.path.exists(cue_file_path):
+        with open(cue_file_path, "w") as cue_file:
+            cue_file.write(sheet)
+    return cue_file_path
+
+
+def extract_archive(archive, archive_directory, verbose=False, logger=None) -> None:
+    """Extract ``archive`` into ``archive_directory`` and backfill cue sheets.
+
+    CONCEPT:ROM-001 — the archive pre-processing stage of the conversion
+    pipeline. ``patool`` is imported lazily so the core package installs without
+    native extras; install with ``rom-manager[native]`` for extraction.
+    """
+    log = logger or _NULL_LOGGER
+    try:
+        import patoolib as patool
+    except ImportError as e:  # pragma: no cover - optional native dependency
+        raise ImportError(
+            "Archive extraction requires the 'patool' library. "
+            "Install the native extras with: pip install 'rom-manager[native]'"
+        ) from e
+
+    log.info(f"Extracting {archive} to {archive_directory}...")
+    verbosity = 1 if verbose else -1
+    try:
+        patool.extract_archive(archive, outdir=archive_directory, verbosity=verbosity)
+    except patool.util.PatoolError as e:
+        log.info(f"Unable to extract: {archive}\nError: {e}")
+
+    log.info(f"Finished extracting {archive} to {archive_directory}")
+    log.info("Generating any missing cue file(s)")
+    if glob.glob(os.path.join(str(archive_directory), "*.bin")) and not glob.glob(
+        os.path.join(str(archive_directory), "*.cue")
+    ):
+        cue_file_generator(archive_directory, logger=log)
+    log.info("Finished generating missing cue file(s)")