Koharu Hy-MT2 + Qwen pipeline

An independent, experimental Japanese-to-Korean manga translation pipeline for Koharu. This repository is not an official Koharu project and is not an upstream contribution request.

The repository contains:

• a patch pinned to Koharu commit a81c5829ea99a45e04580ff97fd6affa81b2db34 that adds a loopback-only headless Web UI, HTTP API, and MCP endpoint;

• an OpenAI-compatible translation sidecar that runs a pinned Hy-MT2 first pass, unloads it, starts an externally managed Qwen reviewer, permits one targeted repair pass, and fails closed on unresolved regions;

• process wrappers that record and later verify exact process identity before stopping or restarting Koharu or the sidecar.

It does not contain model weights, manga pages, OCR corpora, generated translations, private evaluation output, or a Qwen runtime. A private 512-page / 6,525-region pilot informed development, but none of that source material or detailed output is published here.

Architecture and boundaries

Koharu pipeline
  -> loopback OpenAI-compatible sidecar
  -> pinned Hy-MT2-7B first translation (CUDA only)
  -> Hy-MT2 process exits and releases VRAM
  -> externally owned Qwen lifecycle starts the reviewer
  -> sparse review, then at most one targeted repair
  -> deterministic validation and Koharu typography update
  -> Qwen lifecycle stops the reviewer

The sidecar binds to loopback by default. It refuses CPU fallback for Hy-MT2, refuses to translate while Qwen is already running, requires the Qwen process to report that it was started by the current request, serializes GPU jobs, and returns an error rather than silently accepting unresolved output.

Requirements

• Windows 11 and PowerShell 7

• Python 3.13

• Rust toolchain and the build dependencies required by Koharu

• a CUDA-capable NVIDIA GPU; the development configuration used a 32 GB RTX 5090

• a CUDA-enabled PyTorch build compatible with the local driver

• curl.exe

• an external OpenAI-compatible Qwen server and a lifecycle script described below

The code defaults to Qwen model ID dirk-qwen3.8-27b-q5 at http://127.0.0.1:8000/v1. Both values are configurable. Model weights and their licenses remain the operator's responsibility.

Prepare Koharu

Clone the exact upstream revision into the repository-local vendor/koharu directory and apply the pinned patch:

git clone https://github.com/mayocream/koharu.git vendor/koharu
git -C vendor/koharu checkout a81c5829ea99a45e04580ff97fd6affa81b2db34
pwsh -File .\scripts\apply-koharu-patch.ps1 -KoharuCheckout .\vendor\koharu
cargo build --manifest-path .\vendor\koharu\Cargo.toml -p koharu

The application script rejects a different commit, a dirty checkout, or a patch that does not pass git apply --check.

Prepare Python and Hy-MT2

Create a repository-owned virtual environment. Install a CUDA PyTorch build using the command appropriate for the local driver, then install the remaining pinned packages:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
# Install a compatible CUDA build of PyTorch here.
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe .\scripts\download-model.py hy-mt2-7b

download-model.py downloads only the revision recorded in config/model-lock.json and writes a local SHA-256 manifest. The model directory is ignored by Git.

Qwen lifecycle contract

The -QwenLifecycleScript argument is mandatory and machine-specific. Its script must support:

• -Operation status -Summary, returning JSON whose qwen.state and comfyui fields report off before pipeline startup;

• -Operation start-qwen, returning JSON with started_by_request: true only when this request owns the started Qwen process;

• -Operation stop-qwen, stopping only that owned process and returning JSON.

The lifecycle implementation is deliberately not bundled because Qwen runtimes, launch commands, model locations, and GPU sharing policy differ by machine.

Configure and run

In Koharu, configure the OpenAI-compatible provider to use model koharu-hy-qwen-v1 and base URL http://127.0.0.1:4020/v1. This can be saved once through Koharu's normal preferences UI before using headless mode.

Start both the sidecar and patched Koharu:

pwsh -File .\scripts\start.ps1 `
  -QwenLifecycleScript C:\path\to\your\Invoke-QwenLifecycle.ps1

Then open http://127.0.0.1:4010/. The JSON API is rooted at /api/v1, and the MCP JSON-RPC endpoint is /mcp.

Stop only the processes recorded by this repository:

pwsh -File .\scripts\stop.ps1

stop.ps1 validates each recorded executable path, start time, parent PID, creation time, and complete command line before touching a PID. If identity has changed, it retains state and refuses the stop.

Verification

Run the portable checks:

.\.venv\Scripts\python.exe -m unittest service.test_server

$scripts = Get-ChildItem .\scripts -Filter *.ps1
foreach ($script in $scripts) {
  $tokens = $null
  $errors = $null
  [void][System.Management.Automation.Language.Parser]::ParseFile($script.FullName, [ref]$tokens, [ref]$errors)
  if ($errors.Count) { throw ($errors | Out-String) }
}

For the patched Koharu checkout:

cargo test --manifest-path .\vendor\koharu\Cargo.toml -p koharu-app api::tests
cargo test --manifest-path .\vendor\koharu\Cargo.toml -p koharu-pipeline onomatopoeia_becomes_a_sound_effect_text_layer
cargo test --manifest-path .\vendor\koharu\Cargo.toml -p koharu-translator serializes_optional_koharu_region_metadata
cargo build --manifest-path .\vendor\koharu\Cargo.toml -p koharu

The CI workflow runs the portable Python tests, Python compilation, and PowerShell parser checks. Full Koharu builds and GPU/model tests remain local because they require platform-specific native and model inputs.

Limitations

• The patch is intentionally pinned to one Koharu commit; it is not claimed to apply to later revisions.

• The pipeline currently targets Japanese-to-Korean text and a fixed lettering-role policy.

• End-to-end operation requires an operator-supplied Qwen lifecycle implementation and model.

• Automated and live functional validation do not replace manual source review or an independent security audit.

AI development disclosure

Most downstream modifications were generated and revised by OpenAI Codex from user-provided requirements and iterative acceptance requests. The repository owner did not manually review the source code. Validation is based on automated tests and live functional testing in the owner's Windows/Codex environment. No independent third-party code or security audit has been performed.

In short: AI-generated, user-tested, not manually code-reviewed.

Upstream attribution and license

The Koharu patch is based on Koharu by mayocream and contributors at the exact commit identified above. See THIRD_PARTY_NOTICES.md for dependency boundaries and attribution. This repository is offered under your choice of the Apache License 2.0 or MIT License; see LICENSE-APACHE and LICENSE-MIT.