{"record":{"id":"ca1be8cf3bb7932f","repo":"zylon-ai/private-gpt","slug":"harmony-parser-dependencies-are-not-installed-ins","errorCode":null,"errorMessage":"Harmony parser dependencies are not installed. Install with one of: `uv sync --inexact --extra llm-openai` or `uv sync --inexact --extra llm-openai-compatible`.","messagePattern":"Harmony parser dependencies are not installed\\. Install with one of: `uv sync --inexact --extra llm-openai` or `uv sync --inexact --extra llm-openai-compatible`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/llm/text_parsers/harmony_text_parser.py","lineNumber":20,"sourceCode":"\nimport importlib\nimport logging\nfrom typing import TYPE_CHECKING, Any\n\nfrom llama_index.core.base.llms.types import ChatMessage, ChatResponse, MessageRole\n\nfrom private_gpt.components.llm.text_parsers.text_parser_base import TextParserBase\nfrom private_gpt.utils.dependencies import format_missing_dependency_message\n\nif TYPE_CHECKING:\n    from private_gpt.components.llm.tokenizers.tokenizer_base import TokenizerBase\n\n\ndef _load_openai_harmony() -> Any:\n    try:\n        return importlib.import_module(\"openai_harmony\")\n    except ImportError as e:\n        raise ImportError(\n            format_missing_dependency_message(\n                \"Harmony parser\",\n                extras=(\"llm-openai\", \"llm-openai-compatible\"),\n            )\n        ) from e\n\n\ndef get_encoding() -> Any:\n    harmony = _load_openai_harmony()\n    return harmony.load_harmony_encoding(harmony.HarmonyEncodingName.HARMONY_GPT_OSS)\n\n\nlogger = logging.getLogger(__name__)\n\n\nclass HarmonyTextParser(TextParserBase):\n    def __init__(self, tokenizer: TokenizerBase, **kwargs: Any) -> None:\n        super().__init__(tokenizer, **kwargs)","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/llm/text_parsers/harmony_text_parser.py#L2-L38","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: minimal install, parser import fails at runtime\n# after\nuv sync --inexact --extra llm-openai","handlingStrategy":"validation","validationCode":"def harmony_available() -> bool:\n    try:\n        import openai_harmony  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nassert harmony_available(), 'install: uv sync --inexact --extra llm-openai'","typeGuard":null,"tryCatchPattern":"try:\n    from private_gpt.components.llm.text_parsers.harmony_text_parser import get_encoding\nexcept ImportError as e:\n    raise RuntimeError('Harmony parsing unavailable; install llm-openai extra') from e","preventionTips":["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."],"tags":["dependencies","import","openai","installation"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}