kgmodule-utils 0.3.1__tar.gz → 0.4.0__tar.gz

{kgmodule_utils-0.3.1 → kgmodule_utils-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kgmodule-utils
-Version: 0.3.1
+Version: 0.4.0
 Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
 License: Elastic-2.0
 License-File: LICENSE
@@ -14,11 +14,21 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: semantic
+Provides-Extra: synthesis
+Provides-Extra: synthesis-mflux
+Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis"
+Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis-mflux"
 Requires-Dist: lancedb (>=0.19.0) ; extra == "semantic"
+Requires-Dist: mflux (>=0.9.0) ; extra == "synthesis-mflux"
 Requires-Dist: numpy (>=1.24.0) ; extra == "semantic"
+Requires-Dist: openai (>=1.30.0) ; extra == "synthesis"
+Requires-Dist: openai (>=1.30.0) ; extra == "synthesis-mflux"
+Requires-Dist: pillow (>=10.0.0) ; extra == "synthesis"
+Requires-Dist: pillow (>=10.0.0) ; extra == "synthesis-mflux"
 Requires-Dist: sentence-transformers (>=5.4.1) ; extra == "semantic"
 Requires-Dist: torch (>=2.5.1) ; extra == "semantic"
 Requires-Dist: transformers (>=4.40.0,<4.57) ; extra == "semantic"
+Requires-Dist: ty (>=0.0.44,<0.0.45)
 Project-URL: Repository, https://github.com/Flux-Frontiers/kg_utils
 Description-Content-Type: text/markdown
 

{kgmodule_utils-0.3.1 → kgmodule_utils-0.4.0}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "kgmodule-utils"
-version = "0.3.1"
+version = "0.4.0"
 description = "Shared types, graph store, semantic index, and pipeline base for the KGModule SDK"
 readme = "README.md"
 license = { text = "Elastic-2.0" }
@@ -26,7 +26,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 requires-python = ">=3.12,<3.14"
-dependencies = []
+dependencies = ["ty (>=0.0.44,<0.0.45)"]
 
 [project.optional-dependencies]
 semantic = [
@@ -36,6 +36,17 @@ semantic = [
     "torch>=2.5.1",
     "transformers>=4.40.0,<4.57",
 ]
+synthesis = [
+    "httpx>=0.27.0",
+    "openai>=1.30.0",
+    "pillow>=10.0.0",
+]
+synthesis-mflux = [
+    "httpx>=0.27.0",
+    "openai>=1.30.0",
+    "pillow>=10.0.0",
+    "mflux>=0.9.0",
+]
 
 [project.urls]
 Repository = "https://github.com/Flux-Frontiers/kg_utils"
@@ -58,7 +69,7 @@ pytest     = "^8.0.0"
 pytest-cov = "^5.0.0"
 black      = ">=22.0"
 ruff       = ">=0.4.0"
-mypy       = ">=1.10.0"
+ty         = ">=0.0.41"
 
 [tool.black]
 line-length    = 100
@@ -76,22 +87,3 @@ init-hook = "import sys; sys.path.insert(0, 'src')"
 disable = [
     "missing-module-docstring",
 ]
-
-[tool.mypy]
-python_version     = "3.12"
-strict             = true
-warn_unused_ignores = true
-disallow_untyped_defs = true
-
-[[tool.mypy.overrides]]
-module = [
-    "sentence_transformers.*",
-    "transformers.*",
-    "numpy.*",
-    "lancedb",
-]
-ignore_missing_imports = true
-
-[[tool.mypy.overrides]]
-module = "kg_utils.embedder"
-disallow_untyped_calls = false

{kgmodule_utils-0.3.1 → kgmodule_utils-0.4.0}/src/kg_utils/__init__.py

@@ -11,10 +11,15 @@ Sub-packages / modules:
                           kg_model_cache_dir(), resolve_model_path().
     kg_utils.embedder   — Concrete SentenceTransformerEmbedder, get_embedder(),
                           wrap_embedder(), load_sentence_transformer().
+    kg_utils.synthesis  — Unified text + image synthesis: TextSynthesizer, ImageSynthesizer.
+                          Backends: omlx | ollama | openai (text);
+                                    mflux-local | mflux-serve | openai (image).
 
 Optional extras
 ---------------
-    pip install 'kgmodule-utils[semantic]'   # lancedb + sentence-transformers
+    pip install 'kgmodule-utils[semantic]'         # lancedb + sentence-transformers
+    pip install 'kgmodule-utils[synthesis]'        # httpx + openai + pillow
+    pip install 'kgmodule-utils[synthesis-mflux]'  # + mflux (Apple Silicon local gen)
 """
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"

{kgmodule_utils-0.3.1 → kgmodule_utils-0.4.0}/src/kg_utils/pipeline.py

@@ -38,7 +38,7 @@ from __future__ import annotations
 import re
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from kg_utils.semantic import (
     DEFAULT_MODEL,
@@ -715,7 +715,7 @@ class KGModule(ABC):
                     file_nlines=len(lines),
                 )
             if n.get("qualname") and n.get("_span"):
-                spans_by_qualname[(mp, n["qualname"])] = n["_span"]
+                spans_by_qualname[(mp, n["qualname"])] = cast(tuple[int, int], n["_span"])
 
         raw_nodes.sort(key=lambda x: x["_rank_key"])
 

kgmodule_utils-0.4.0/src/kg_utils/synthesis/__init__.py

@@ -0,0 +1,79 @@
+"""kg_utils.synthesis — Unified text and image synthesis backends.
+
+Text backends  (TextBackend):
+    omlx    — local oMLX / vLLM  (OpenAI wire protocol; MLX chain-of-thought suppressed)
+    ollama  — local Ollama        (OpenAI wire protocol; no api_key required)
+    openai  — OpenAI cloud API    (requires OPENAI_API_KEY or SYNTH_API_KEY)
+
+Image backends  (ImageBackend):
+    mflux-local  — local Flux2Klein via mflux  (Apple Silicon only)
+    mflux-serve  — HTTP proxy to mflux-serve   (runs anywhere)
+    openai       — OpenAI DALL-E               (requires OPENAI_API_KEY or IMAGE_API_KEY)
+
+Env vars
+--------
+Text synthesis:
+    SYNTH_BACKEND   omlx | ollama | openai          (default: omlx)
+    SYNTH_ENDPOINT  override base URL
+    SYNTH_API_KEY   bearer token / OpenAI key
+    SYNTH_MODEL     model-id override
+    Legacy aliases: VLLM_ENDPOINT_URL → SYNTH_ENDPOINT
+                    VLLM_API_KEY      → SYNTH_API_KEY
+                    VLLM_MODEL        → SYNTH_MODEL
+
+Image synthesis:
+    IMAGE_BACKEND   mflux-local | mflux-serve | openai   (default: mflux-serve)
+    IMAGE_ENDPOINT  mflux-serve base URL
+    IMAGE_API_KEY   OpenAI key (also reads OPENAI_API_KEY)
+    IMAGE_MODEL     model-id override
+    IMAGE_STEPS     inference steps  (default: 4, mflux backends only)
+    Legacy alias:   GUTENKG_IMAGE_MODEL → IMAGE_MODEL
+
+Quick start
+-----------
+    from kg_utils.synthesis import text_synthesizer_from_env, image_synthesizer_from_env
+
+    text  = text_synthesizer_from_env()
+    image = image_synthesizer_from_env()
+
+    answer = text.synthesize_rag(query, hits)
+    b64    = image.generate_b64(prompt)
+    rewritten_prompt, err = text.rewrite_for_image(corpus_passage)
+"""
+
+from __future__ import annotations
+
+from kg_utils.synthesis._config import (
+    ImageBackend,
+    ImageConfig,
+    TextBackend,
+    TextConfig,
+    image_config_from_env,
+    text_config_from_env,
+)
+from kg_utils.synthesis._image import ImageSynthesizer
+from kg_utils.synthesis._text import TextSynthesizer
+
+
+def text_synthesizer_from_env() -> TextSynthesizer:
+    """Build a TextSynthesizer configured from the current process environment."""
+    return TextSynthesizer(text_config_from_env())
+
+
+def image_synthesizer_from_env() -> ImageSynthesizer:
+    """Build an ImageSynthesizer configured from the current process environment."""
+    return ImageSynthesizer(image_config_from_env())
+
+
+__all__ = [
+    "TextBackend",
+    "ImageBackend",
+    "TextConfig",
+    "ImageConfig",
+    "TextSynthesizer",
+    "ImageSynthesizer",
+    "text_synthesizer_from_env",
+    "image_synthesizer_from_env",
+    "text_config_from_env",
+    "image_config_from_env",
+]

kgmodule_utils-0.4.0/src/kg_utils/synthesis/_config.py

@@ -0,0 +1,155 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""Synthesis backend configuration — enums, dataclasses, and env-var factories."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import Enum
+
+
+class TextBackend(str, Enum):
+    """LLM backend for text synthesis."""
+
+    OMLX = "omlx"  # local oMLX / vLLM — OpenAI wire protocol with MLX thinking suppression
+    OLLAMA = "ollama"  # local Ollama       — OpenAI wire protocol, no api_key required
+    OPENAI = "openai"  # OpenAI cloud API   — requires OPENAI_API_KEY / SYNTH_API_KEY
+
+
+class ImageBackend(str, Enum):
+    """Image generation backend."""
+
+    MFLUX_LOCAL = "mflux-local"  # local Flux2Klein via mflux (Apple Silicon only)
+    MFLUX_SERVE = "mflux-serve"  # HTTP proxy to a running mflux-serve instance
+    OPENAI = "openai"  # OpenAI DALL-E — requires OPENAI_API_KEY / IMAGE_API_KEY
+
+
+# Per-backend defaults — filled in when the user has not provided an override.
+_TEXT_DEFAULTS: dict[TextBackend, dict[str, str]] = {
+    TextBackend.OMLX: {
+        "endpoint": "http://localhost:8080/v1",
+        "model": "Qwen3-4B-Instruct-2507-MLX-8bit",
+    },
+    TextBackend.OLLAMA: {
+        "endpoint": "http://localhost:11434/v1",
+        "model": "hf.co/unsloth/Qwen3-4B-Instruct-2507-GGUF:Q8_0",
+    },
+    TextBackend.OPENAI: {
+        "endpoint": "https://api.openai.com/v1",
+        "model": "gpt-4o-mini",
+    },
+}
+
+_IMAGE_DEFAULTS: dict[ImageBackend, dict[str, str]] = {
+    ImageBackend.MFLUX_LOCAL: {
+        "model": "mlx-community/flux2-klein-4b-4bit",
+    },
+    ImageBackend.MFLUX_SERVE: {
+        "server_url": "http://localhost:8090",
+        "model": "flux2-klein-4b",
+    },
+    ImageBackend.OPENAI: {
+        "model": "dall-e-3",
+    },
+}
+
+
+@dataclass
+class TextConfig:
+    """Configuration for a text synthesis backend.
+
+    :param backend: Which LLM provider to use.
+    :param endpoint: Base URL override (empty = use backend default).
+    :param api_key: Bearer token / OpenAI key (empty = not required for omlx/ollama).
+    :param model: Model-id override (empty = use backend default).
+    :param max_tokens: Maximum tokens in the generated response.
+    :param suppress_thinking: Strip ``<think>`` blocks and pass ``extra_body`` to disable
+                              chain-of-thought for oMLX backends.
+    """
+
+    backend: TextBackend = TextBackend.OMLX
+    endpoint: str = ""
+    api_key: str = ""
+    model: str = ""
+    max_tokens: int = 2048
+    suppress_thinking: bool = True
+
+    def resolved_endpoint(self) -> str:
+        return self.endpoint or _TEXT_DEFAULTS[self.backend]["endpoint"]
+
+    def resolved_model(self) -> str:
+        return self.model or _TEXT_DEFAULTS[self.backend]["model"]
+
+
+@dataclass
+class ImageConfig:
+    """Configuration for an image synthesis backend.
+
+    :param backend: Which image provider to use.
+    :param server_url: mflux-serve base URL override (empty = use backend default).
+    :param api_key: OpenAI API key (empty = read from OPENAI_API_KEY at call time).
+    :param model: Model-id override (empty = use backend default).
+    :param steps: Inference steps for mflux backends (ignored for OpenAI).
+    """
+
+    backend: ImageBackend = ImageBackend.MFLUX_SERVE
+    server_url: str = ""
+    api_key: str = ""
+    model: str = ""
+    steps: int = 4
+
+    def resolved_server_url(self) -> str:
+        return self.server_url or _IMAGE_DEFAULTS[self.backend].get("server_url", "")
+
+    def resolved_model(self) -> str:
+        return self.model or _IMAGE_DEFAULTS[self.backend].get("model", "")
+
+
+# ---------------------------------------------------------------------------
+# Env-var factories
+# ---------------------------------------------------------------------------
+
+
+def text_config_from_env() -> TextConfig:
+    """Build a TextConfig from environment variables.
+
+    Reads ``SYNTH_BACKEND`` (default ``omlx``) plus endpoint/key/model overrides.
+    Legacy vars ``VLLM_ENDPOINT_URL``, ``VLLM_API_KEY``, and ``VLLM_MODEL`` are
+    honoured as fallbacks so existing deployments need no changes.
+    """
+    backend_str = os.environ.get("SYNTH_BACKEND", "omlx")
+    try:
+        backend = TextBackend(backend_str)
+    except ValueError:
+        backend = TextBackend.OMLX
+
+    endpoint = os.environ.get("SYNTH_ENDPOINT") or os.environ.get("VLLM_ENDPOINT_URL") or ""
+    api_key = (
+        os.environ.get("SYNTH_API_KEY")
+        or os.environ.get("VLLM_API_KEY")
+        or os.environ.get("OPENAI_API_KEY")
+        or ""
+    )
+    model = os.environ.get("SYNTH_MODEL") or os.environ.get("VLLM_MODEL") or ""
+    return TextConfig(backend=backend, endpoint=endpoint, api_key=api_key, model=model)
+
+
+def image_config_from_env() -> ImageConfig:
+    """Build an ImageConfig from environment variables.
+
+    Reads ``IMAGE_BACKEND`` (default ``mflux-serve``) plus server-url/key/model/steps overrides.
+    Legacy var ``GUTENKG_IMAGE_MODEL`` is honoured as a fallback for ``IMAGE_MODEL``.
+    """
+    backend_str = os.environ.get("IMAGE_BACKEND", "mflux-serve")
+    try:
+        backend = ImageBackend(backend_str)
+    except ValueError:
+        backend = ImageBackend.MFLUX_SERVE
+
+    server_url = os.environ.get("IMAGE_ENDPOINT") or ""
+    api_key = os.environ.get("IMAGE_API_KEY") or os.environ.get("OPENAI_API_KEY") or ""
+    model = os.environ.get("IMAGE_MODEL") or os.environ.get("GUTENKG_IMAGE_MODEL") or ""
+    steps = int(os.environ.get("IMAGE_STEPS", "4"))
+    return ImageConfig(
+        backend=backend, server_url=server_url, api_key=api_key, model=model, steps=steps
+    )

kgmodule_utils-0.4.0/src/kg_utils/synthesis/_image.py

@@ -0,0 +1,235 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""ImageSynthesizer — unified image generation across mflux-local, mflux-serve, and DALL-E."""
+
+from __future__ import annotations
+
+import base64
+import random
+from io import BytesIO
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from PIL.Image import Image as PILImage  # type: ignore[import-unresolved]
+
+from kg_utils.synthesis._config import ImageBackend, ImageConfig
+
+# ---------------------------------------------------------------------------
+# Aspect-ratio → pixel dimension tables
+# ---------------------------------------------------------------------------
+
+# Used by mflux backends (arbitrary resolution).
+_MFLUX_SIZES: dict[str, tuple[int, int]] = {
+    "1:1": (1024, 1024),
+    "3:2": (1536, 1024),
+    "2:3": (1024, 1536),
+    "16:9": (1536, 864),
+    "9:16": (864, 1536),
+    "4:3": (1365, 1024),
+    "3:4": (1024, 1365),
+}
+
+# DALL-E 3 only supports three sizes; map aspect ratios to the nearest valid option.
+_DALLE3_SIZES: dict[str, str] = {
+    "1:1": "1024x1024",
+    "3:2": "1792x1024",
+    "2:3": "1024x1792",
+    "16:9": "1792x1024",
+    "9:16": "1024x1792",
+    "4:3": "1792x1024",
+    "3:4": "1024x1792",
+}
+
+
+# ---------------------------------------------------------------------------
+# Synthesizer
+# ---------------------------------------------------------------------------
+
+
+class ImageSynthesizer:
+    """Unified image generation across mflux-local, mflux-serve, and OpenAI DALL-E.
+
+    All ``generate*`` methods return a PIL ``Image`` — callers that need a base64
+    string (e.g. HTTP wire responses) should use ``generate_b64()``.  A per-instance
+    mflux model cache avoids reloading across calls to the same synthesizer.
+
+    :param config: Backend configuration produced by ``image_config_from_env()`` or
+                   built directly as an ``ImageConfig`` dataclass.
+    """
+
+    def __init__(self, config: ImageConfig) -> None:
+        self._cfg = config
+        self._mflux_model: Any = None
+        self._mflux_model_name: str | None = None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _load_mflux(self, model_name: str) -> Any:
+        if self._mflux_model is not None and self._mflux_model_name == model_name:
+            return self._mflux_model
+        from mflux.models.flux2.variants.txt2img.flux2_klein import Flux2Klein  # type: ignore
+
+        self._mflux_model = Flux2Klein(model_path=model_name)
+        self._mflux_model_name = model_name
+        return self._mflux_model
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def generate(
+        self,
+        prompt: str,
+        *,
+        aspect_ratio: str = "3:2",
+        seed: int | None = None,
+        steps: int | None = None,
+        model: str | None = None,
+    ) -> PILImage:
+        """Generate an image and return a PIL Image.
+
+        :param prompt: Text description of the scene to generate.
+        :param aspect_ratio: One of 1:1, 3:2, 2:3, 16:9, 9:16, 4:3, 3:4.
+        :param seed: Random seed for reproducibility (random int if omitted).
+        :param steps: Override inference steps (mflux backends only; ignored for OpenAI).
+        :param model: Override the configured model for this single call.
+        :returns: PIL Image.
+        """
+        cfg = self._cfg
+        effective_steps = steps if steps is not None else cfg.steps
+        effective_model = model or cfg.resolved_model()
+
+        if cfg.backend == ImageBackend.MFLUX_LOCAL:
+            return self._generate_local(
+                prompt,
+                model=effective_model,
+                seed=seed,
+                steps=effective_steps,
+                aspect_ratio=aspect_ratio,
+            )
+        elif cfg.backend == ImageBackend.MFLUX_SERVE:
+            return self._generate_via_server(
+                prompt,
+                server_url=cfg.resolved_server_url(),
+                seed=seed,
+                steps=effective_steps,
+                aspect_ratio=aspect_ratio,
+            )
+        else:
+            return self._generate_openai(
+                prompt,
+                model=effective_model,
+                aspect_ratio=aspect_ratio,
+            )
+
+    def generate_b64(
+        self,
+        prompt: str,
+        *,
+        aspect_ratio: str = "3:2",
+        seed: int | None = None,
+        steps: int | None = None,
+        model: str | None = None,
+    ) -> str:
+        """Generate an image and return it as a base64-encoded PNG string.
+
+        Convenience wrapper around ``generate()`` for HTTP wire responses.
+
+        :param prompt: Text description of the scene to generate.
+        :param aspect_ratio: One of 1:1, 3:2, 2:3, 16:9, 9:16, 4:3, 3:4.
+        :param seed: Random seed for reproducibility.
+        :param steps: Override inference steps (mflux backends only).
+        :param model: Override the configured model for this single call.
+        :returns: Base64-encoded PNG string.
+        """
+        img = self.generate(prompt, aspect_ratio=aspect_ratio, seed=seed, steps=steps, model=model)
+        buf = BytesIO()
+        img.save(buf, format="PNG")
+        return base64.b64encode(buf.getvalue()).decode()
+
+    # ------------------------------------------------------------------
+    # Backend implementations
+    # ------------------------------------------------------------------
+
+    def _generate_local(
+        self,
+        prompt: str,
+        *,
+        model: str,
+        seed: int | None,
+        steps: int,
+        aspect_ratio: str,
+    ) -> PILImage:
+        width, height = _MFLUX_SIZES.get(aspect_ratio, _MFLUX_SIZES["3:2"])
+        effective_seed = seed if seed is not None else random.randint(0, 2**31 - 1)
+        flux = self._load_mflux(model)
+        result = flux.generate_image(
+            seed=effective_seed,
+            prompt=prompt,
+            width=width,
+            height=height,
+            guidance=1.0,
+            num_inference_steps=steps,
+            scheduler="flow_match_euler_discrete",
+        )
+        return result.image
+
+    def _generate_via_server(
+        self,
+        prompt: str,
+        *,
+        server_url: str,
+        seed: int | None,
+        steps: int,
+        aspect_ratio: str,
+    ) -> PILImage:
+        import httpx
+        from PIL import Image  # type: ignore[import-unresolved]
+
+        width, height = _MFLUX_SIZES.get(aspect_ratio, _MFLUX_SIZES["3:2"])
+        payload: dict[str, Any] = {
+            "prompt": prompt,
+            "n": 1,
+            "size": f"{width}x{height}",
+            "num_inference_steps": steps,
+            "response_format": "b64_json",
+        }
+        if seed is not None:
+            payload["seed"] = seed
+
+        resp = httpx.post(
+            server_url.rstrip("/") + "/v1/images/generations",
+            json=payload,
+            timeout=httpx.Timeout(connect=5.0, read=300.0, write=10.0, pool=5.0),
+        )
+        resp.raise_for_status()
+        b64 = resp.json()["data"][0]["b64_json"]
+        return Image.open(BytesIO(base64.b64decode(b64)))
+
+    def _generate_openai(
+        self,
+        prompt: str,
+        *,
+        model: str,
+        aspect_ratio: str,
+    ) -> PILImage:
+        import os
+
+        from openai import OpenAI  # type: ignore[import-unresolved]
+        from PIL import Image  # type: ignore[import-unresolved]
+
+        cfg = self._cfg
+        api_key = cfg.api_key or os.environ.get("OPENAI_API_KEY", "")
+        size = _DALLE3_SIZES.get(aspect_ratio, _DALLE3_SIZES["3:2"])
+
+        client = OpenAI(api_key=api_key)
+        resp = client.images.generate(
+            model=model,
+            prompt=prompt,
+            n=1,
+            size=size,  # type: ignore[arg-type]
+            response_format="b64_json",
+        )
+        b64 = (resp.data[0].b64_json or "") if resp.data else ""
+        return Image.open(BytesIO(base64.b64decode(b64)))

kgmodule_utils-0.4.0/src/kg_utils/synthesis/_text.py

@@ -0,0 +1,178 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""TextSynthesizer — unified LLM completion across oMLX, Ollama, and OpenAI backends."""
+
+from __future__ import annotations
+
+import re
+
+from kg_utils.synthesis._config import TextBackend, TextConfig
+
+# ---------------------------------------------------------------------------
+# System prompts
+# ---------------------------------------------------------------------------
+
+_RAG_SYSTEM = (
+    "You are a literary guide to the Project Gutenberg corpus. "
+    "Answer the question using ONLY the provided source passages. "
+    "Do NOT use any prior knowledge — if something is in the passages, "
+    "report it; if it is not in the passages, say so. "
+    "Never contradict or override what the passages say based on what "
+    "you believe to be true. Be concise and specific. "
+    "Cite the author and work when relevant."
+)
+
+_IMAGE_REWRITE_SYSTEM = (
+    "You are an expert art director. Given a passage of historical text, write a single concise "
+    "image generation prompt (one paragraph, no bullet points, no quotation marks) that vividly "
+    "describes the scene for a text-to-image model. Focus on visual elements: setting, lighting, "
+    "figures, mood, and artistic style. Do NOT include any text, labels, captions, or words in "
+    "the scene description. Output ONLY the prompt, nothing else."
+)
+
+
+# ---------------------------------------------------------------------------
+# Synthesizer
+# ---------------------------------------------------------------------------
+
+
+class TextSynthesizer:
+    """Unified text completion client across oMLX, Ollama, and OpenAI backends.
+
+    Uses the ``openai`` Python package for all three — each backend is just a
+    different ``base_url`` and optionally an ``extra_body`` for thinking suppression.
+
+    :param config: Backend configuration produced by ``text_config_from_env()`` or
+                   built directly as a ``TextConfig`` dataclass.
+    """
+
+    def __init__(self, config: TextConfig) -> None:
+        self._cfg = config
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _client(self):  # type: ignore[no-untyped-def]
+        from openai import OpenAI  # type: ignore[import-unresolved]
+
+        cfg = self._cfg
+        api_key = cfg.api_key or "not-needed"
+        return OpenAI(base_url=cfg.resolved_endpoint(), api_key=api_key)
+
+    def _extra_body(self) -> dict | None:
+        if self._cfg.suppress_thinking and self._cfg.backend == TextBackend.OMLX:
+            return {"think": False, "chat_template_kwargs": {"enable_thinking": False}}
+        return None
+
+    @staticmethod
+    def _strip_thinking(text: str) -> str:
+        return re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL).strip()
+
+    def _complete(
+        self,
+        messages: list[dict],
+        *,
+        model: str | None = None,
+        max_tokens: int | None = None,
+        temperature: float = 0.7,
+    ) -> str | None:
+        try:
+            client = self._client()
+            mdl = model or self._cfg.resolved_model()
+            extra = self._extra_body()
+            kwargs: dict = {
+                "model": mdl,
+                "messages": messages,
+                "max_tokens": max_tokens or self._cfg.max_tokens,
+                "temperature": temperature,
+            }
+            if extra:
+                kwargs["extra_body"] = extra
+            resp = client.chat.completions.create(**kwargs)
+            raw = (resp.choices[0].message.content or "").strip()
+            return self._strip_thinking(raw) or None
+        except Exception:  # noqa: BLE001
+            return None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def list_models(self) -> list[str]:
+        """Return the model IDs available at the configured endpoint.
+
+        :returns: List of model ID strings; empty list on failure or if the
+                  endpoint does not support the ``/v1/models`` route.
+        """
+        try:
+            return [m.id for m in self._client().models.list().data if m.id]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def synthesize_rag(
+        self,
+        query: str,
+        snippets: list[dict],
+        *,
+        model: str | None = None,
+        max_k: int = 12,
+        system: str | None = None,
+    ) -> str | None:
+        """Synthesize a grounded answer from corpus retrieval snippets.
+
+        Formats snippet metadata (genre · author · title) as a structured context
+        block, then calls the configured LLM to answer *only* from those passages.
+
+        :param query: Natural-language question.
+        :param snippets: Hit dicts from KGRAG — must contain a ``content`` key.
+        :param model: Override the configured model for this single call.
+        :param max_k: Maximum number of snippets included in the context window.
+        :param system: Override the default RAG system prompt.
+        :returns: Synthesized answer, or ``None`` on failure or when no snippets
+                  carry content.
+        """
+        items = [s for s in snippets[:max_k] if (s.get("content") or "").strip()]
+        if not items:
+            return None
+
+        ctx_parts: list[str] = []
+        for s in items:
+            genre = s.get("genre", s.get("kg_kind", ""))
+            author = s.get("author") or ""
+            title = s.get("title") or s.get("name") or ""
+            header = " · ".join(x for x in [genre, author, title] if x)
+            ctx_parts.append(f"[{header}]\n{s['content'].strip()}")
+
+        ctx = "\n\n".join(ctx_parts)
+        messages = [
+            {"role": "system", "content": system or _RAG_SYSTEM},
+            {"role": "user", "content": f"Source passages:\n{ctx}\n\nQuestion: {query}"},
+        ]
+        return self._complete(messages, model=model, temperature=0.3)
+
+    def rewrite_for_image(
+        self,
+        corpus_text: str,
+        *,
+        model: str | None = None,
+    ) -> tuple[str, str | None]:
+        """Rewrite a historical corpus passage into an image-generation prompt.
+
+        Uses the same backend and model as RAG synthesis so no second model load
+        is required.  Pass ``model=`` to use a lighter model for this step if
+        synthesis and rewrite are called from the same hot path.
+
+        :param corpus_text: Raw historical passage to convert into a visual scene.
+        :param model: Override the configured model for this single call.
+        :returns: ``(prompt, error)`` — prompt is the rewritten scene description
+                  (falls back to the original text on failure); error is ``None``
+                  on success or a short message otherwise.
+        """
+        messages = [
+            {"role": "system", "content": _IMAGE_REWRITE_SYSTEM},
+            {"role": "user", "content": corpus_text},
+        ]
+        result = self._complete(messages, model=model, max_tokens=300, temperature=0.7)
+        if result is None:
+            return corpus_text, "synthesis returned no content"
+        return result, None