odysseus-dev/odysseus · error · HTTPException

Boogu MLX serving requires boogu-image-mlx in the launch Pyt

Error message

Boogu MLX serving requires boogu-image-mlx in the launch Python. Install with: python -m pip install -U git+https://github.com/xocialize/boogu-image-mlx.git

What it means

Raised by _generate_boogu in scripts/mlx_image_server.py with HTTP 503 when the in-process import of boogu_image_mlx (BooguImagePipeline) or PIL fails. Unlike the mflux/HiDream paths, Boogu generation runs inside the server process, so the boogu-image-mlx package must be installed in the launch Python.

Source

Thrown at scripts/mlx_image_server.py:292

        "--height",
        str(height),
        "--num-inference-steps",
        str(steps),
        "--no-snap-resolution",
    ]
    env = os.environ.copy()
    proc = subprocess.run(cmd, env=env, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    if proc.returncode != 0:
        detail = (proc.stderr or proc.stdout or "HiDream generator failed").strip()
        raise HTTPException(500, detail[-4000:])


def _generate_boogu(model: str, prompt: str, out_path: Path, width: int, height: int, steps: int) -> None:
    try:
        from boogu_image_mlx.pipeline_mlx import BooguImagePipeline
        from PIL import Image
    except Exception as e:
        raise HTTPException(
            503,
            "Boogu MLX serving requires boogu-image-mlx in the launch Python. "
            "Install with: python -m pip install -U git+https://github.com/xocialize/boogu-image-mlx.git",
        ) from e

    model_path = _snapshot_path(model)
    vlm_model = (_args.vlm_model or os.environ.get("ODYSSEUS_MLX_IMAGE_VLM_MODEL") or "").strip()
    if not vlm_model:
        raise HTTPException(
            422,
            "This MLX image pipeline requires a companion vision-language model. "
            "Relaunch with --vlm-model <repo_or_path> or set ODYSSEUS_MLX_IMAGE_VLM_MODEL.",
        )
    try:
        pipe = BooguImagePipeline.from_pretrained(
            str(model_path),
            vlm_model,
        )

View on GitHub (pinned to f9235ebbf1)

Solutions

1. Install exactly as instructed: python -m pip install -U git+https://github.com/xocialize/boogu-image-mlx.git
2. Install into the same interpreter that launches mlx_image_server.py (check sys.executable in logs)
3. Also ensure Pillow is present since the same try block imports it

Example fix

# before
python scripts/mlx_image_server.py --model xocialize/boogu-image  # 503
# after
python -m pip install -U git+https://github.com/xocialize/boogu-image-mlx.git
python scripts/mlx_image_server.py --model xocialize/boogu-image

import importlib.util, sys, subprocess
if importlib.util.find_spec('boogu_image_mlx') is None:
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-U',
        'git+https://github.com/xocialize/boogu-image-mlx.git'])

def boogu_available() -> bool:
    import importlib.util
    return importlib.util.find_spec('boogu_image_mlx') is not None

When it happens

Trigger: POST /v1/images/generations with a model matched by _is_boogu when 'from boogu_image_mlx.pipeline_mlx import BooguImagePipeline' raises ImportError/ModuleNotFoundError.

Common situations: boogu-image-mlx is only distributed via GitHub (not PyPI), so plain pip install boogu misses it; installed into a different venv than the server; Pillow missing in the same environment triggers the same raise.

Related errors

• huggingface_hub is required to download MLX image model snap
• Pillow is required for MLX image edit bridge inputs.
• Pillow is required for MLX image edit bridge masks.
• {cli} not found in PATH or next to {sys.executable}. Install
• This MLX image pipeline requires a companion vision-language

AI-assisted analysis of odysseus-dev/odysseus@f9235ebbf1 (2026-08-14). Data as JSON: /api/errors/185be35ab2510296. Report an issue: GitHub.