zylon-ai/private-gpt · error · ImportError

Harmony parser dependencies are not installed. Install with

Error message

Harmony parser dependencies are not installed. Install with one of: `uv sync --inexact --extra llm-openai` or `uv sync --inexact --extra llm-openai-compatible`.

What it means

The Harmony text parser lazily imports openai_harmony (needed to parse gpt-oss Harmony-format model output). If the package is absent, _load_openai_harmony re-raises ImportError with an install hint naming the project extras that provide it: llm-openai or llm-openai-compatible.

Source

Thrown at private_gpt/components/llm/text_parsers/harmony_text_parser.py:20

import importlib
import logging
from typing import TYPE_CHECKING, Any

from llama_index.core.base.llms.types import ChatMessage, ChatResponse, MessageRole

from private_gpt.components.llm.text_parsers.text_parser_base import TextParserBase
from private_gpt.utils.dependencies import format_missing_dependency_message

if TYPE_CHECKING:
    from private_gpt.components.llm.tokenizers.tokenizer_base import TokenizerBase


def _load_openai_harmony() -> Any:
    try:
        return importlib.import_module("openai_harmony")
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Harmony parser",
                extras=("llm-openai", "llm-openai-compatible"),
            )
        ) from e


def get_encoding() -> Any:
    harmony = _load_openai_harmony()
    return harmony.load_harmony_encoding(harmony.HarmonyEncodingName.HARMONY_GPT_OSS)


logger = logging.getLogger(__name__)


class HarmonyTextParser(TextParserBase):
    def __init__(self, tokenizer: TokenizerBase, **kwargs: Any) -> None:
        super().__init__(tokenizer, **kwargs)

View on GitHub (pinned to 4a030776a3)

Solutions

Install the required extra: uv sync --inexact --extra llm-openai (or --extra llm-openai-compatible).
Verify openai_harmony is importable in the runtime environment: python -c "import openai_harmony".
Alternatively switch to a text parser/prompt style that does not need Harmony if you are not using gpt-oss models.

Example fix

# before: minimal install, parser import fails at runtime
# after
uv sync --inexact --extra llm-openai

Defensive patterns

Strategy: validation

Validate before calling

def harmony_available() -> bool:
    try:
        import openai_harmony  # noqa: F401
        return True
    except ImportError:
        return False

assert harmony_available(), 'install: uv sync --inexact --extra llm-openai'

Try / catch

try:
    from private_gpt.components.llm.text_parsers.harmony_text_parser import get_encoding
except ImportError as e:
    raise RuntimeError('Harmony parsing unavailable; install llm-openai extra') from e

Prevention

Install the extras your selected model backends need at image build time.
Add an import-capability check at startup when enabling gpt-oss style output parsing.
Keep dependency extras pinned in CI so missing packages fail the build, not runtime.

When it happens

Trigger: Selecting the harmony text parser (or an OpenAI/gpt-oss integration that uses it) in an environment where the llm-openai / llm-openai-compatible extras were not installed. The import is attempted on first use, so the error surfaces at request time, not at startup.

Common situations: Running a minimal install (`uv sync` without extras) but pointing config at a gpt-oss model; production images built from a slim dependency set; partial dependency upgrades that dropped the extra.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/ca1be8cf3bb7932f. Report an issue: GitHub.