rom-manager 1.0.0__tar.gz

rom_manager-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Audel Rouhi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rom_manager-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include requirements.txt
+recursive-include rom_manager *.py *.json
+recursive-include rom_manager/agent_data *

rom_manager-1.0.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: rom-manager
+Version: 1.0.0
+Summary: ROM Converter/Organizer (CHD/RVZ) + MCP Server + A2A Agent
+Author-email: Audel Rouhi <knucklessg1@gmail.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: Public Domain
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-utilities>=0.47.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: mcp
+Requires-Dist: agent-utilities[mcp]>=0.47.0; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: agent-utilities[agent,logfire]>=0.47.0; extra == "agent"
+Requires-Dist: logfire>=2.0.0; extra == "agent"
+Provides-Extra: native
+Requires-Dist: patool>=2.1.1; extra == "native"
+Provides-Extra: convert
+Requires-Dist: patool>=2.1.1; extra == "convert"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp>=1.27.0; extra == "otel"
+Provides-Extra: all
+Requires-Dist: rom-manager[agent,mcp,native,otel]>=1.0.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# ROM Manager
+## CLI or API | MCP | Agent
+
+![PyPI - Version](https://img.shields.io/pypi/v/rom-manager)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+![PyPI - Downloads](https://img.shields.io/pypi/dd/rom-manager)
+![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/rom-manager)
+![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/rom-manager)
+![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/rom-manager)
+![PyPI - License](https://img.shields.io/pypi/l/rom-manager)
+![GitHub](https://img.shields.io/github/license/Knuckles-Team/rom-manager)
+![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/rom-manager)
+![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/rom-manager)
+![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/rom-manager)
+![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/rom-manager)
+![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/rom-manager)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/rom-manager)
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/rom-manager)
+
+*Version: 1.0.0*
+
+> **Documentation** — Installation, deployment, and usage across the API, CLI, and
+> MCP interfaces, plus the integrated A2A agent server, are maintained in the
+> [official documentation](https://knuckles-team.github.io/rom-manager/).
+
+> ⚠️ **Back up your ROMs before working with this tool.** Conversion and the
+> `--delete` / `clean_origin_files` options are destructive to source files.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Architecture](#architecture)
+- [Usage (CLI or API)](#usage-cli-or-api)
+- [MCP](#mcp)
+- [Agent](#agent)
+- [Environment Variables](#environment-variables)
+- [Security & Governance](#security--governance)
+- [External Binary Dependencies](#external-binary-dependencies)
+- [Installation](#installation)
+- [Deployment (agent_server.py)](#deployment-agent_serverpy)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Overview
+
+**ROM Manager** is a production-grade ROM converter/organizer with an integrated
+Model Context Protocol (MCP) server and Agent-to-Agent (A2A) agent. It extracts
+archives, auto-renames ROMs via a known game-code registry, converts ISO/WBFS
+images to **CHD** (`chdman`) or **RVZ** (`dolphin-tool`), generates missing `.cue`
+sheets, and cleans up source files — in parallel.
+
+Unlike network connectors, ROM Manager is a **local tool**: there is no service
+URL and no credentials.
+
+---
+
+## Key Features
+
+- **Real conversion pipeline:** parallel extract → rename → convert (CHD/RVZ) → cleanup.
+- **Consolidated Action-Routed MCP Tools:** two togglable domains (`conversion`,
+  `game-codes`) minimize token overhead and IDE tool bloat.
+- **Integrated Graph Agent:** built-in Pydantic-AI agent (AG-UI / ACP).
+- **Native Telemetry & Tracing:** OpenTelemetry exports out of the box.
+- **Lazy native deps:** archive backends are optional extras, imported only when used.
+
+---
+
+## Architecture
+
+ROM Manager keeps a single, well-factored pipeline behind three entry surfaces
+(CLI, MCP server, A2A agent). The orchestrator (`RomManager`) composes focused
+responsibility layers and shells out to external conversion binaries:
+
+```mermaid
+flowchart LR
+    subgraph Entry["Entry Surfaces"]
+        CLI["CLI<br/>rom-manager"]
+        MCP["MCP Server<br/>rom-manager-mcp<br/>(CONCEPT:ROM-001/002)"]
+        AGENT["A2A Agent<br/>rom-manager-agent"]
+    end
+
+    CLI --> RM
+    MCP --> API["api_client.Api<br/>(facade)"]
+    AGENT --> MCP
+    API --> RM
+
+    subgraph Pipeline["RomManager orchestrator"]
+        RM["RomManager"] --> ARCH["archives.py<br/>extract + cue"]
+        RM --> NAME["naming.py<br/>game-code rename"]
+        RM --> CONV["conversion.py<br/>command + runner seam"]
+    end
+
+    ARCH --> P7Z["7z / patool"]
+    CONV --> CHDMAN["chdman (CHD)"]
+    CONV --> DOLPHIN["dolphin-tool (RVZ)"]
+    NAME --> CODES["game_codes.py<br/>(PSX registry, DATA)"]
+```
+
+| Layer | Module | Responsibility |
+|-------|--------|----------------|
+| Orchestrator | `rom_manager/rom_manager.py` | Pipeline composition + CLI (`RomManager`, `rom_manager()`). |
+| Archives | `rom_manager/archives.py` | Archive detection, extraction, `.cue` generation. |
+| Conversion | `rom_manager/conversion.py` | `chdman`/`dolphin-tool` command building + runner seam. |
+| Naming | `rom_manager/naming.py` | Game-code lookup + in-place rename. |
+| Data | `rom_manager/game_codes.py` | Verbatim PSX serial→title registry (DATA). |
+| Facade | `rom_manager/api_client.py` | `Api` wrapper consumed by MCP tools/agent. |
+
+---
+
+## Usage (CLI or API)
+
+This package wraps a local ROM conversion pipeline (`rom_manager.rom_manager.RomManager`).
+Use it via the CLI or the `rom_manager.api_client.Api` facade.
+
+```bash
+rom-manager --directory "/games/PSX/" --iso chd --verbose
+```
+
+| Flag | Long | Description |
+|------|------|-------------|
+| `-c` | `--cpu-count` | Limit max CPUs for parallel processing |
+| `-d` | `--directory` | Directory to process ROMs |
+| `-i` | `--iso` | Conversion target: `rvz` or `chd` |
+| `-f` | `--force` | Force overwrite of existing `.chd` files |
+| `-v` | `--verbose` | Display all output messages |
+| `-x` | `--delete` | Delete original files after processing |
+
+Detailed API usage is in [docs/usage.md](docs/usage.md).
+
+---
+
+## MCP
+
+This server utilizes dynamic Action-Routed tools to optimize token overhead and
+maximize IDE compatibility.
+
+### Available MCP Tools
+| Tool Module | Toggle Env Var | Enabled by Default | Description & Actions |
+|-------------|----------------|--------------------|------------------------|
+| **Conversion** | `CONVERSIONTOOL` | `True` | Manage ROM conversion operations (CONCEPT:ROM-001). Actions: `convert`, `process_directory`, `process_file`, `generate_cue`, `list_files`. |
+| **Game Codes** | `GAMECODESTOOL` | `True` | Manage game code lookup and naming (CONCEPT:ROM-002). Actions: `lookup`, `list`, `rename`. |
+
+### Dynamic Tool Selection
+
+Each domain is gated by an environment toggle (default `True`). Set a toggle to
+`False` to omit that tool from the registered surface.
+
+### Running the MCP server
+
+```bash
+# stdio (default)
+rom-manager-mcp
+
+# Streamable HTTP
+rom-manager-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+#### stdio client config
+
+```json
+{
+  "mcpServers": {
+    "rom-manager": {
+      "command": "uv",
+      "args": ["run", "rom-manager-mcp"],
+      "env": { "ROM_DIRECTORY": "/games", "CONVERSIONTOOL": "True", "GAMECODESTOOL": "True" }
+    }
+  }
+}
+```
+
+#### Docker
+
+```bash
+docker run --rm -it -v /games:/games -e ROM_DIRECTORY=/games \
+  -p 8000:8000 -e TRANSPORT=streamable-http knucklessg1/rom-manager:latest
+```
+
+---
+
+## Agent
+
+ROM Manager ships a Pydantic-AI agent (`rom-manager-agent`) that calls the MCP
+tool surface and exposes an AG-UI web interface. Its identity lives in
+`rom_manager/agent_data/IDENTITY.md`.
+
+```bash
+rom-manager-agent --web
+```
+
+---
+
+## Environment Variables
+
+All settings are optional — ROM Manager runs with sensible defaults and requires
+no credentials. Copy [`.env.example`](.env.example) to `.env` to override.
+
+### Application Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ROM_DIRECTORY` | `.` (cwd) | Default directory of ROMs to process when none is supplied. |
+| `ROM_ISO_TYPE` | `chd` | Conversion target: `chd` (chdman) or `rvz` (dolphin-tool). |
+| `ROM_VERBOSE` | `False` | Emit verbose conversion output. |
+| `ROM_FORCE` | `False` | Force overwrite of existing converted files. |
+| `CONVERSIONTOOL` | `True` | Toggle registration of the **conversion** MCP tool domain (`CONCEPT:ROM-001`). |
+| `GAMECODESTOOL` | `True` | Toggle registration of the **game-codes** MCP tool domain (`CONCEPT:ROM-002`). |
+
+> CPU count and "delete originals" are exposed as CLI flags (`--cpu-count` /
+> `--delete`) and MCP action params (`cpu_count` / `clean_origin_files`) rather
+> than environment variables.
+
+### MCP / Framework Variables (agent-utilities)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HOST` | `0.0.0.0` | Bind host for HTTP/SSE transports. |
+| `PORT` | `8000` | Bind port for HTTP/SSE transports. |
+| `TRANSPORT` | `stdio` | MCP transport: `stdio`, `streamable-http`, or `sse`. |
+| `AUTH_TYPE` | `none` | MCP authentication mode (this local tool needs none). |
+| `FASTMCP_LOG_LEVEL` | `ERROR` | FastMCP internal log verbosity (pinned at startup). |
+| `ENABLE_OTEL` | `True` | Enable OpenTelemetry export of traces/metrics. |
+| `EUNOMIA_TYPE` | `none` | Eunomia authorization mode: `none`, `embedded`, or `remote`. |
+| `EUNOMIA_POLICY_FILE` | `mcp_policies.json` | Path to the Eunomia policy file when embedded. |
+
+### Terminal Variables
+
+These are set automatically by the server to keep stdio transport clean; you do
+not normally set them yourself.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NO_COLOR` | `1` | Disable ANSI colour codes in child tooling output. |
+| `TERM` | `dumb` | Force a dumb terminal so progress output does not corrupt the stdio channel. |
+
+---
+
+## Security & Governance
+
+- **No credentials:** ROM Manager is a local tool with no service URL/token.
+- **Eunomia policies & OpenTelemetry:** inherited from the `agent-utilities`
+  middleware (see `.env.example`).
+- **Destructive-op safety:** the agent recommends backing up ROMs before
+  `clean_origin_files`/delete operations.
+
+---
+
+## External Binary Dependencies
+
+Conversion *actions* shell out to native tools (the Python package installs fine
+without them):
+
+- **`chdman`** (CHD) — `apt install mame-tools` (Ubuntu) or MAME tools on Windows.
+- **`dolphin-tool`** (RVZ) — see the Dolphin emulator docs.
+- **`7z` / archive backends** (extraction) — `apt install p7zip-full`; pair with
+  the `rom-manager[native]` extra (`patool`).
+
+---
+
+## Installation
+
+```bash
+pip install rom-manager            # core CLI + Api
+pip install "rom-manager[mcp]"     # + MCP server
+pip install "rom-manager[agent]"   # + A2A agent
+pip install "rom-manager[native]"  # + patool (archive extraction)
+pip install "rom-manager[all]"     # everything
+```
+
+---
+
+## Deployment (agent_server.py)
+
+`rom-manager-agent` (entry point `rom_manager.agent_server:agent_server`) starts a
+Pydantic-AI A2A agent that auto-discovers the MCP tool surface from
+`mcp_config.json` and can expose an AG-UI web interface.
+
+```bash
+# Local: web UI on the default host/port, OTEL enabled
+rom-manager-agent --web --otel \
+  --provider openai --model-id gpt-4o-mini \
+  --host 0.0.0.0 --port 8080
+```
+
+Container deployment (compose):
+
+```yaml
+# docker/agent.compose.yml (excerpt)
+services:
+  rom-manager-agent:
+    image: knucklessg1/rom-manager:latest
+    command: ["rom-manager-agent", "--web"]
+    environment:
+      ROM_DIRECTORY: /games
+      TRANSPORT: streamable-http
+      HOST: 0.0.0.0
+      PORT: 8080
+      ENABLE_OTEL: "True"
+      AUTH_TYPE: none
+    volumes:
+      - /srv/roms:/games
+    ports:
+      - "8080:8080"
+```
+
+The MCP server (`rom-manager-mcp`) deploys the same way; see
+[docs/deployment.md](docs/deployment.md) for the full compose/Swarm recipes.
+
+---
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Deployment](docs/deployment.md)
+- [Usage (API / CLI / MCP)](docs/usage.md)
+- [Overview](docs/overview.md)
+- [Concepts (`CONCEPT:ROM-*`)](docs/concepts.md)
+
+---
+
+## Contributing
+
+Contributions are welcome. Run `pre-commit run --all-files` before opening a PR.
+Preserve the real conversion pipeline — wrap `RomManager`, do not break it.
+
+## License
+
+MIT © Knuckles-Team