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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kgmodule-utils
-Version: 0.4.0
+Version: 0.4.2
 Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
 License: Elastic-2.0
 License-File: LICENSE
@@ -35,7 +35,7 @@ Description-Content-Type: text/markdown
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
+[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
 [![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 
@@ -67,6 +67,7 @@ Every KGModule implementation — [PyCodeKG](https://github.com/Flux-Frontiers/p
 - **`kg_utils.embedder`** — `get_embedder()`, `wrap_embedder()`, `load_sentence_transformer()` factory functions
 - **`kg_utils.embed`** — `Embedder` protocol, `DEFAULT_MODEL`, `KNOWN_MODELS`, `resolve_model_path()`
 - **`kg_utils.snapshots`** — `Snapshot`, `SnapshotManager`, `SnapshotManifest` for temporal metric tracking
+- **`kg_utils.synthesis`** — Unified text + image synthesis: oMLX, Ollama, and OpenAI text backends; mflux-local, mflux-serve, and DALL-E image backends; all env-var configurable
 
 ---
 
@@ -86,11 +87,23 @@ pip install kgmodule-utils
 pip install 'kgmodule-utils[semantic]'
 ```
 
+### With text + image synthesis (oMLX / Ollama / OpenAI / mflux-serve)
+
+```bash
+pip install 'kgmodule-utils[synthesis]'
+```
+
+### With local mflux image generation (Apple Silicon, includes synthesis)
+
+```bash
+pip install 'kgmodule-utils[synthesis-mflux]'
+```
+
 ### In a Poetry project
 
 ```toml
 [tool.poetry.dependencies]
-kgmodule-utils = { version = ">=0.3.1", extras = ["semantic"] }
+kgmodule-utils = { version = ">=0.4.0", extras = ["semantic", "synthesis"] }
 ```
 
 ---
@@ -217,6 +230,23 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
 | `SnapshotManager` | Capture, persist, load, list, diff, and prune snapshots |
 | `SnapshotManifest` | Fast-lookup index with format versioning |
 
+### `kg_utils.synthesis`
+
+> Full reference: [docs/synthesis.md](docs/synthesis.md)
+
+| Class / function | Description |
+|---|---|
+| `TextBackend` | Enum: `omlx` \| `ollama` \| `openai` |
+| `ImageBackend` | Enum: `mflux-local` \| `mflux-serve` \| `openai` |
+| `TextConfig` | Backend config dataclass with `resolved_endpoint()` / `resolved_model()` |
+| `ImageConfig` | Backend config dataclass with `resolved_server_url()` / `resolved_model()` |
+| `TextSynthesizer` | `list_models()`, `synthesize_rag()`, `rewrite_for_image()` |
+| `ImageSynthesizer` | `generate()` → PIL Image, `generate_b64()` → base64 PNG |
+| `text_config_from_env()` | Build `TextConfig` from `SYNTH_*` env vars |
+| `image_config_from_env()` | Build `ImageConfig` from `IMAGE_*` env vars |
+| `text_synthesizer_from_env()` | Convenience: config + synthesizer in one call |
+| `image_synthesizer_from_env()` | Convenience: config + synthesizer in one call |
+
 ---
 
 ## Project Structure
@@ -224,6 +254,8 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
 ```
 KG_utils/
 ├── pyproject.toml
+├── docs/
+│   └── synthesis.md          # Synthesis sub-package reference
 ├── src/
 │   └── kg_utils/
 │       ├── __init__.py
@@ -235,17 +267,25 @@ KG_utils/
 │       ├── module.py         # Re-export shim
 │       ├── embed.py          # Embedder protocol, model registry
 │       ├── embedder.py       # SentenceTransformerEmbedder factory functions
-│       └── snapshots/
-│           ├── __init__.py
-│           ├── models.py     # Snapshot, SnapshotManifest, PruneResult
-│           └── manager.py    # SnapshotManager
+│       ├── snapshots/
+│       │   ├── __init__.py
+│       │   ├── models.py     # Snapshot, SnapshotManifest, PruneResult
+│       │   └── manager.py    # SnapshotManager
+│       └── synthesis/
+│           ├── __init__.py   # Public API + factory functions
+│           ├── _config.py    # TextBackend, ImageBackend, TextConfig, ImageConfig, env factories
+│           ├── _text.py      # TextSynthesizer
+│           └── _image.py     # ImageSynthesizer
 └── tests/
-    ├── test_store.py          # GraphStore unit tests
-    ├── test_pipeline_utils.py # Pipeline utility function tests
-    ├── test_pipeline_module.py # End-to-end integration tests (--integration)
-    ├── test_types.py          # Spec dataclass and KGExtractor tests
-    ├── test_snapshots.py      # Snapshot lifecycle tests
-    └── test_integration.py    # Cross-module integration tests
+    ├── test_store.py               # GraphStore unit tests
+    ├── test_pipeline_utils.py      # Pipeline utility function tests
+    ├── test_pipeline_module.py     # End-to-end integration tests (--integration)
+    ├── test_types.py               # Spec dataclass and KGExtractor tests
+    ├── test_snapshots.py           # Snapshot lifecycle tests
+    ├── test_integration.py         # Cross-module integration tests
+    ├── test_synthesis_config.py    # Config defaults and env-var priority chains (44 tests)
+    ├── test_synthesis_text.py      # TextSynthesizer with mocked openai client (38 tests)
+    └── test_synthesis_image.py     # ImageSynthesizer with mocked backends (34 tests)
 ```
 
 ---

{kgmodule_utils-0.4.0 → kgmodule_utils-0.4.2}/README.md

@@ -1,7 +1,7 @@
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
+[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
 [![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 
@@ -33,6 +33,7 @@ Every KGModule implementation — [PyCodeKG](https://github.com/Flux-Frontiers/p
 - **`kg_utils.embedder`** — `get_embedder()`, `wrap_embedder()`, `load_sentence_transformer()` factory functions
 - **`kg_utils.embed`** — `Embedder` protocol, `DEFAULT_MODEL`, `KNOWN_MODELS`, `resolve_model_path()`
 - **`kg_utils.snapshots`** — `Snapshot`, `SnapshotManager`, `SnapshotManifest` for temporal metric tracking
+- **`kg_utils.synthesis`** — Unified text + image synthesis: oMLX, Ollama, and OpenAI text backends; mflux-local, mflux-serve, and DALL-E image backends; all env-var configurable
 
 ---
 
@@ -52,11 +53,23 @@ pip install kgmodule-utils
 pip install 'kgmodule-utils[semantic]'
 ```
 
+### With text + image synthesis (oMLX / Ollama / OpenAI / mflux-serve)
+
+```bash
+pip install 'kgmodule-utils[synthesis]'
+```
+
+### With local mflux image generation (Apple Silicon, includes synthesis)
+
+```bash
+pip install 'kgmodule-utils[synthesis-mflux]'
+```
+
 ### In a Poetry project
 
 ```toml
 [tool.poetry.dependencies]
-kgmodule-utils = { version = ">=0.3.1", extras = ["semantic"] }
+kgmodule-utils = { version = ">=0.4.0", extras = ["semantic", "synthesis"] }
 ```
 
 ---
@@ -183,6 +196,23 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
 | `SnapshotManager` | Capture, persist, load, list, diff, and prune snapshots |
 | `SnapshotManifest` | Fast-lookup index with format versioning |
 
+### `kg_utils.synthesis`
+
+> Full reference: [docs/synthesis.md](docs/synthesis.md)
+
+| Class / function | Description |
+|---|---|
+| `TextBackend` | Enum: `omlx` \| `ollama` \| `openai` |
+| `ImageBackend` | Enum: `mflux-local` \| `mflux-serve` \| `openai` |
+| `TextConfig` | Backend config dataclass with `resolved_endpoint()` / `resolved_model()` |
+| `ImageConfig` | Backend config dataclass with `resolved_server_url()` / `resolved_model()` |
+| `TextSynthesizer` | `list_models()`, `synthesize_rag()`, `rewrite_for_image()` |
+| `ImageSynthesizer` | `generate()` → PIL Image, `generate_b64()` → base64 PNG |
+| `text_config_from_env()` | Build `TextConfig` from `SYNTH_*` env vars |
+| `image_config_from_env()` | Build `ImageConfig` from `IMAGE_*` env vars |
+| `text_synthesizer_from_env()` | Convenience: config + synthesizer in one call |
+| `image_synthesizer_from_env()` | Convenience: config + synthesizer in one call |
+
 ---
 
 ## Project Structure
@@ -190,6 +220,8 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
 ```
 KG_utils/
 ├── pyproject.toml
+├── docs/
+│   └── synthesis.md          # Synthesis sub-package reference
 ├── src/
 │   └── kg_utils/
 │       ├── __init__.py
@@ -201,17 +233,25 @@ KG_utils/
 │       ├── module.py         # Re-export shim
 │       ├── embed.py          # Embedder protocol, model registry
 │       ├── embedder.py       # SentenceTransformerEmbedder factory functions
-│       └── snapshots/
-│           ├── __init__.py
-│           ├── models.py     # Snapshot, SnapshotManifest, PruneResult
-│           └── manager.py    # SnapshotManager
+│       ├── snapshots/
+│       │   ├── __init__.py
+│       │   ├── models.py     # Snapshot, SnapshotManifest, PruneResult
+│       │   └── manager.py    # SnapshotManager
+│       └── synthesis/
+│           ├── __init__.py   # Public API + factory functions
+│           ├── _config.py    # TextBackend, ImageBackend, TextConfig, ImageConfig, env factories
+│           ├── _text.py      # TextSynthesizer
+│           └── _image.py     # ImageSynthesizer
 └── tests/
-    ├── test_store.py          # GraphStore unit tests
-    ├── test_pipeline_utils.py # Pipeline utility function tests
-    ├── test_pipeline_module.py # End-to-end integration tests (--integration)
-    ├── test_types.py          # Spec dataclass and KGExtractor tests
-    ├── test_snapshots.py      # Snapshot lifecycle tests
-    └── test_integration.py    # Cross-module integration tests
+    ├── test_store.py               # GraphStore unit tests
+    ├── test_pipeline_utils.py      # Pipeline utility function tests
+    ├── test_pipeline_module.py     # End-to-end integration tests (--integration)
+    ├── test_types.py               # Spec dataclass and KGExtractor tests
+    ├── test_snapshots.py           # Snapshot lifecycle tests
+    ├── test_integration.py         # Cross-module integration tests
+    ├── test_synthesis_config.py    # Config defaults and env-var priority chains (44 tests)
+    ├── test_synthesis_text.py      # TextSynthesizer with mocked openai client (38 tests)
+    └── test_synthesis_image.py     # ImageSynthesizer with mocked backends (34 tests)
 ```
 
 ---

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

@@ -10,7 +10,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "kgmodule-utils"
-version = "0.4.0"
+version = "0.4.2"
 description = "Shared types, graph store, semantic index, and pipeline base for the KGModule SDK"
 readme = "README.md"
 license = { text = "Elastic-2.0" }

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

@@ -14,6 +14,8 @@ Sub-packages / modules:
     kg_utils.synthesis  — Unified text + image synthesis: TextSynthesizer, ImageSynthesizer.
                           Backends: omlx | ollama | openai (text);
                                     mflux-local | mflux-serve | openai (image).
+    kg_utils.worker     — RunPod worker protocol helpers and WorkerClient for /runsync calls.
+    kg_utils.retrieval  — Shared retrieval helpers: hit_to_dict, attach_content_by_sqlite.
 
 Optional extras
 ---------------
@@ -22,4 +24,4 @@ Optional extras
     pip install 'kgmodule-utils[synthesis-mflux]'  # + mflux (Apple Silicon local gen)
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

kgmodule_utils-0.4.2/src/kg_utils/retrieval/__init__.py

@@ -0,0 +1,5 @@
+"""Shared retrieval helpers for serializing and enriching KG hits."""
+
+from kg_utils.retrieval.hits import attach_content_by_sqlite, hit_to_dict
+
+__all__ = ["hit_to_dict", "attach_content_by_sqlite"]

kgmodule_utils-0.4.2/src/kg_utils/retrieval/hits.py

@@ -0,0 +1,75 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""Hit serialization and content hydration helpers for KG retrieval responses."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+__all__ = ["hit_to_dict", "attach_content_by_sqlite"]
+
+
+def _is_diary_kind(kind_value: Any) -> bool:
+    kind_str = str(kind_value)
+    return kind_str == "KGKind.DIARY" or kind_str.lower().endswith("diary")
+
+
+def hit_to_dict(hit: Any, include_diary_timestamp: bool = False) -> dict:
+    """Serialize a KGRAG hit object into a plain dictionary.
+
+    :param hit: Hit-like object with standard retrieval attributes.
+    :param include_diary_timestamp: Include ``timestamp`` field for diary hits.
+    :returns: Serialized hit dictionary.
+    """
+    out = {
+        "kg_name": hit.kg_name,
+        "kg_kind": str(hit.kg_kind),
+        "node_id": hit.node_id,
+        "name": hit.name,
+        "kind": hit.kind,
+        "score": round(float(hit.score), 4),
+        "summary": hit.summary,
+        "source_path": hit.source_path,
+    }
+    if include_diary_timestamp:
+        out["timestamp"] = hit.name if _is_diary_kind(hit.kg_kind) else None
+    return out
+
+
+def attach_content_by_sqlite(hits: list[dict], kg_sqlite_map: dict[str, Path]) -> None:
+    """Attach full node text under ``content`` via batched SQLite lookups.
+
+    Missing or unreadable databases are ignored to preserve permissive behavior.
+
+    :param hits: Mutable hit dictionaries. Each hit should include ``kg_name`` and ``node_id``.
+    :param kg_sqlite_map: Mapping of KG name to sqlite database path.
+    """
+    by_kg: dict[str, list[dict]] = defaultdict(list)
+    for hit in hits:
+        by_kg[hit.get("kg_name", "")].append(hit)
+
+    for kg_name, kg_hits in by_kg.items():
+        db_path = kg_sqlite_map.get(kg_name)
+        if not db_path or not Path(db_path).exists():
+            continue
+
+        ids = [h.get("node_id") for h in kg_hits if h.get("node_id")]
+        if not ids:
+            continue
+
+        text_by_id: dict[str, str] = {}
+        try:
+            with sqlite3.connect(str(db_path)) as con:
+                placeholders = ",".join("?" * len(ids))
+                query = f"SELECT id, text FROM nodes WHERE id IN ({placeholders})"
+                for node_id, text in con.execute(query, ids):
+                    text_by_id[node_id] = text or ""
+        except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+            continue
+
+        for hit in kg_hits:
+            node_id = hit.get("node_id")
+            if node_id:
+                hit["content"] = text_by_id.get(node_id, "")

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

@@ -53,6 +53,11 @@ from kg_utils.synthesis._config import (
 )
 from kg_utils.synthesis._image import ImageSynthesizer
 from kg_utils.synthesis._text import TextSynthesizer
+from kg_utils.synthesis.factory import (
+    image_synth_for_backend,
+    normalize_openai_base_url,
+    text_synth_for_backend,
+)
 
 
 def text_synthesizer_from_env() -> TextSynthesizer:
@@ -76,4 +81,7 @@ __all__ = [
     "image_synthesizer_from_env",
     "text_config_from_env",
     "image_config_from_env",
+    "normalize_openai_base_url",
+    "text_synth_for_backend",
+    "image_synth_for_backend",
 ]

{kgmodule_utils-0.4.0 → kgmodule_utils-0.4.2}/src/kg_utils/synthesis/_config.py

@@ -21,7 +21,7 @@ class ImageBackend(str, Enum):
 
     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
+    OPENAI = "openai"  # OpenAI gpt-image-1 — requires OPENAI_API_KEY / IMAGE_API_KEY
 
 
 # Per-backend defaults — filled in when the user has not provided an override.
@@ -49,7 +49,7 @@ _IMAGE_DEFAULTS: dict[ImageBackend, dict[str, str]] = {
         "model": "flux2-klein-4b",
     },
     ImageBackend.OPENAI: {
-        "model": "dall-e-3",
+        "model": "gpt-image-1",
     },
 }
 

{kgmodule_utils-0.4.0 → kgmodule_utils-0.4.2}/src/kg_utils/synthesis/_image.py

@@ -39,6 +39,17 @@ _DALLE3_SIZES: dict[str, str] = {
     "3:4": "1024x1792",
 }
 
+# gpt-image-1 supports portrait/landscape 1024×1536 instead of 1792-wide.
+_GPT_IMAGE_SIZES: dict[str, str] = {
+    "1:1": "1024x1024",
+    "3:2": "1536x1024",
+    "2:3": "1024x1536",
+    "16:9": "1536x1024",
+    "9:16": "1024x1536",
+    "4:3": "1536x1024",
+    "3:4": "1024x1536",
+}
+
 
 # ---------------------------------------------------------------------------
 # Synthesizer
@@ -221,7 +232,13 @@ class ImageSynthesizer:
 
         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"])
+
+        # gpt-image-1 uses different valid sizes and does not accept response_format.
+        # dall-e-3 returns a URL by default; gpt-image-1 returns b64_json by default.
+        if model.startswith("gpt-image"):
+            size = _GPT_IMAGE_SIZES.get(aspect_ratio, _GPT_IMAGE_SIZES["3:2"])
+        else:
+            size = _DALLE3_SIZES.get(aspect_ratio, _DALLE3_SIZES["3:2"])
 
         client = OpenAI(api_key=api_key)
         resp = client.images.generate(
@@ -229,7 +246,13 @@ class ImageSynthesizer:
             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)))
+        item = resp.data[0] if resp.data else None
+        if item and item.b64_json:
+            return Image.open(BytesIO(base64.b64decode(item.b64_json)))
+        if item and item.url:
+            import httpx  # type: ignore[import-unresolved]
+
+            raw = httpx.get(item.url, timeout=httpx.Timeout(30.0)).content
+            return Image.open(BytesIO(raw))
+        raise RuntimeError("OpenAI image response contained neither b64_json nor url")

kgmodule_utils-0.4.2/src/kg_utils/synthesis/factory.py

@@ -0,0 +1,97 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""Synthesis backend factory helpers for per-request backend overrides."""
+
+from __future__ import annotations
+
+import os
+
+from kg_utils.synthesis._config import (
+    ImageBackend,
+    ImageConfig,
+    TextBackend,
+    TextConfig,
+)
+from kg_utils.synthesis._image import ImageSynthesizer
+from kg_utils.synthesis._text import TextSynthesizer
+
+__all__ = [
+    "normalize_openai_base_url",
+    "text_synth_for_backend",
+    "image_synth_for_backend",
+]
+
+
+def normalize_openai_base_url(endpoint: str) -> str:
+    """Normalize an OpenAI-wire endpoint so it ends with /v1.
+
+    Returns an empty string when endpoint is empty.
+    """
+    ep = (endpoint or "").strip().rstrip("/")
+    if not ep:
+        return ""
+    if ep.endswith("/v1"):
+        return ep
+    return f"{ep}/v1"
+
+
+def text_synth_for_backend(backend: str, fallback: TextSynthesizer) -> TextSynthesizer:
+    """Return a TextSynthesizer configured for a specific backend override.
+
+    Unknown or empty backend strings return ``fallback``.
+    """
+    backend_str = (backend or "").strip().lower()
+    if not backend_str:
+        return fallback
+
+    try:
+        selected = TextBackend(backend_str)
+    except ValueError:
+        return fallback
+
+    if selected == TextBackend.OMLX:
+        endpoint = os.environ.get("SYNTH_ENDPOINT") or os.environ.get("VLLM_ENDPOINT_URL") or ""
+        endpoint = normalize_openai_base_url(endpoint)
+        api_key = os.environ.get("SYNTH_API_KEY") or os.environ.get("VLLM_API_KEY") or ""
+        model = os.environ.get("SYNTH_MODEL") or os.environ.get("VLLM_MODEL") or ""
+        return TextSynthesizer(
+            TextConfig(backend=selected, endpoint=endpoint, api_key=api_key, model=model)
+        )
+
+    if selected == TextBackend.OLLAMA:
+        endpoint = os.environ.get("OLLAMA_ENDPOINT") or ""
+        return TextSynthesizer(TextConfig(backend=selected, endpoint=endpoint))
+
+    if selected == TextBackend.OPENAI:
+        api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("SYNTH_API_KEY") or ""
+        return TextSynthesizer(TextConfig(backend=selected, api_key=api_key))
+
+    return fallback
+
+
+def image_synth_for_backend(backend: str, fallback: ImageSynthesizer) -> ImageSynthesizer:
+    """Return an ImageSynthesizer configured for a specific backend override.
+
+    Unknown or empty backend strings return ``fallback``.
+    """
+    backend_str = (backend or "").strip().lower()
+    if not backend_str:
+        return fallback
+
+    try:
+        selected = ImageBackend(backend_str)
+    except ValueError:
+        return fallback
+
+    if selected == ImageBackend.OPENAI:
+        api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("IMAGE_API_KEY") or ""
+        return ImageSynthesizer(ImageConfig(backend=selected, api_key=api_key))
+
+    if selected == ImageBackend.MFLUX_SERVE:
+        server_url = os.environ.get("IMAGE_ENDPOINT") or ""
+        return ImageSynthesizer(ImageConfig(backend=selected, server_url=server_url))
+
+    if selected == ImageBackend.MFLUX_LOCAL:
+        model = os.environ.get("IMAGE_MODEL") or os.environ.get("GUTENKG_IMAGE_MODEL") or ""
+        return ImageSynthesizer(ImageConfig(backend=selected, model=model))
+
+    return fallback

kgmodule_utils-0.4.2/src/kg_utils/worker/__init__.py

@@ -0,0 +1,17 @@
+"""Worker protocol helpers and client for RunPod ``/runsync`` endpoints."""
+
+from kg_utils.worker.client import (
+    WorkerClient,
+    WorkerError,
+    decode_worker_response,
+    extract_worker_error,
+)
+from kg_utils.worker.ops import handle_aux_ops
+
+__all__ = [
+    "WorkerClient",
+    "WorkerError",
+    "decode_worker_response",
+    "extract_worker_error",
+    "handle_aux_ops",
+]

kgmodule_utils-0.4.2/src/kg_utils/worker/client.py

@@ -0,0 +1,196 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""RunPod worker client utilities for chat and handler front-ends.
+
+This module centralizes payload construction and response/error decoding for
+``/runsync`` worker calls used by Streamlit clients.
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+
+
+class WorkerError(Exception):
+    """Raised when a worker response contains a structured application-level error."""
+
+
+def _format_error_data(error_data: object) -> str:
+    if isinstance(error_data, str):
+        try:
+            decoded = json.loads(error_data)
+        except (ValueError, TypeError):
+            return error_data
+        if isinstance(decoded, dict):
+            err_type = decoded.get("error_type", "Unknown")
+            err_msg = decoded.get("error_message", str(decoded))
+            return f"{err_type}: {err_msg}"
+        return str(decoded)
+
+    if isinstance(error_data, dict):
+        err_type = error_data.get("error_type", "Unknown")
+        err_msg = error_data.get("error_message", str(error_data))
+        return f"{err_type}: {err_msg}"
+
+    return str(error_data)
+
+
+def extract_worker_error(data: object) -> str | None:
+    """Extract a readable worker error from a raw RunPod response payload."""
+    if not isinstance(data, dict):
+        return str(data)
+
+    if data.get("status") == "FAILED" or "error_type" in data:
+        return _format_error_data(data.get("error", data))
+
+    out = data.get("output")
+    if isinstance(out, dict) and isinstance(out.get("error"), str):
+        return out["error"]
+
+    return None
+
+
+def decode_worker_response(data: object) -> dict:
+    """Decode a worker response payload and raise WorkerError on application errors."""
+    error = extract_worker_error(data)
+    if error:
+        raise WorkerError(error)
+
+    if not isinstance(data, dict):
+        raise WorkerError(f"unexpected worker response type: {type(data).__name__}")
+
+    out = data.get("output", data)
+    if not isinstance(out, dict):
+        raise WorkerError(f"unexpected worker output type: {type(out).__name__}")
+    return out
+
+
+class WorkerClient:
+    """Small client for RunPod ``/runsync`` worker endpoints."""
+
+    def __init__(self, base_url: str, secret: str = "") -> None:
+        self._base_url = base_url.rstrip("/")
+        self._secret = secret
+
+    def _post(self, payload: dict, timeout: httpx.Timeout) -> dict:
+        resp = httpx.post(f"{self._base_url}/runsync", json=payload, timeout=timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def list_models(self, backend: str = "") -> tuple[list[str], str]:
+        payload: dict = {"input": {"op": "models"}}
+        if backend:
+            payload["input"]["backend"] = backend
+        if self._secret:
+            payload["input"]["secret"] = self._secret
+
+        try:
+            data = self._post(
+                payload,
+                timeout=httpx.Timeout(connect=5.0, read=20.0, write=5.0, pool=5.0),
+            )
+            out = data.get("output", {}) if isinstance(data, dict) else {}
+            if not isinstance(out, dict):
+                return [], ""
+            return out.get("models", []), out.get("default", "")
+        except Exception:  # noqa: BLE001
+            return [], ""
+
+    def rewrite(
+        self,
+        text: str,
+        backend: str = "",
+        model: str = "",
+    ) -> tuple[str, str | None]:
+        payload: dict = {"input": {"op": "rewrite", "text": text}}
+        if backend:
+            payload["input"]["backend"] = backend
+        if model:
+            payload["input"]["model"] = model
+        if self._secret:
+            payload["input"]["secret"] = self._secret
+
+        try:
+            data = self._post(
+                payload,
+                timeout=httpx.Timeout(connect=5.0, read=60.0, write=10.0, pool=5.0),
+            )
+            err = extract_worker_error(data)
+            if err:
+                return text, err
+            out = data.get("output", {}) if isinstance(data, dict) else {}
+            if not isinstance(out, dict):
+                return text, "unexpected worker output"
+            return out.get("prompt", text), out.get("error")
+        except Exception as exc:  # noqa: BLE001
+            return text, str(exc)
+
+    def imagine(
+        self,
+        prompt: str,
+        *,
+        image_backend: str = "",
+        aspect_ratio: str = "3:2",
+        steps: int | None = None,
+    ) -> tuple[str | None, str | None, str | None, str | None]:
+        payload: dict = {"input": {"op": "imagine", "prompt": prompt, "aspect_ratio": aspect_ratio}}
+        if image_backend:
+            payload["input"]["image_backend"] = image_backend
+        if steps is not None:
+            payload["input"]["steps"] = steps
+        if self._secret:
+            payload["input"]["secret"] = self._secret
+
+        try:
+            data = self._post(
+                payload,
+                timeout=httpx.Timeout(connect=5.0, read=300.0, write=10.0, pool=5.0),
+            )
+            err = extract_worker_error(data)
+            if err:
+                return None, None, None, err
+
+            out = data.get("output", {}) if isinstance(data, dict) else {}
+            if not isinstance(out, dict):
+                return None, None, None, "unexpected worker output"
+            if "error" in out:
+                return None, None, None, str(out["error"])
+            return out.get("image_b64"), out.get("image_model"), out.get("image_backend"), None
+        except Exception as exc:  # noqa: BLE001
+            return None, None, None, str(exc)
+
+    def query(
+        self,
+        query: str,
+        *,
+        corpus: str = "all",
+        k: int = 8,
+        min_score: float = 0.0,
+        semantic_floor: float = 0.0,
+        synthesize: bool = False,
+        model: str = "",
+        backend: str = "",
+    ) -> dict:
+        payload: dict = {
+            "input": {
+                "query": query,
+                "corpus": corpus,
+                "k": k,
+                "min_score": min_score,
+                "semantic_floor": semantic_floor,
+                "synthesize": synthesize,
+            }
+        }
+        if model:
+            payload["input"]["model"] = model
+        if backend:
+            payload["input"]["backend"] = backend
+        if self._secret:
+            payload["input"]["secret"] = self._secret
+
+        data = self._post(
+            payload,
+            timeout=httpx.Timeout(connect=5.0, read=600.0, write=30.0, pool=5.0),
+        )
+        return decode_worker_response(data)

kgmodule_utils-0.4.2/src/kg_utils/worker/ops.py

@@ -0,0 +1,72 @@
+# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
+"""Shared handler operation dispatch for models, rewrite, and imagine."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from kg_utils.synthesis._image import ImageSynthesizer
+from kg_utils.synthesis._text import TextSynthesizer
+
+__all__ = ["handle_aux_ops"]
+
+
+def handle_aux_ops(
+    inp: dict,
+    text_synth_factory: Callable[[str], TextSynthesizer],
+    image_synth_factory: Callable[[str], ImageSynthesizer],
+) -> dict | None:
+    """Handle shared non-query worker operations.
+
+    Returns:
+    - operation payload dict when op is recognized
+    - ``None`` when input has no recognized operation
+    """
+    op = inp.get("op")
+
+    if op == "models":
+        synth = text_synth_factory(inp.get("backend", ""))
+        # Existing handlers expose the active model via synthesizer config internals.
+        return {
+            "models": synth.list_models(),
+            "default": synth._cfg.resolved_model(),  # pylint: disable=protected-access
+        }
+
+    if op == "rewrite":
+        text = (inp.get("text") or "").strip()
+        if not text:
+            return {"error": "rewrite requires a non-empty 'text'"}
+
+        synth = text_synth_factory(inp.get("backend", ""))
+        model_override = (inp.get("model") or "").strip() or None
+        prompt, error = synth.rewrite_for_image(text, model=model_override)
+        return {"prompt": prompt, "error": error}
+
+    if op == "imagine":
+        prompt = (inp.get("prompt") or "").strip()
+        if not prompt:
+            return {"error": "imagine requires a non-empty 'prompt'"}
+
+        aspect = inp.get("aspect_ratio", "3:2")
+        seed = inp.get("seed")
+        steps = inp.get("steps")
+        img_synth = image_synth_factory(inp.get("image_backend", ""))
+
+        try:
+            b64 = img_synth.generate_b64(
+                prompt,
+                aspect_ratio=aspect,
+                seed=int(seed) if seed is not None else None,
+                steps=int(steps) if steps is not None else None,
+            )
+            return {
+                "image_b64": b64,
+                "prompt": prompt,
+                "aspect_ratio": aspect,
+                "image_model": img_synth._cfg.resolved_model(),  # pylint: disable=protected-access
+                "image_backend": img_synth._cfg.backend.value,  # pylint: disable=protected-access
+            }
+        except Exception as exc:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+            return {"error": f"image generation failed: {exc}"}
+
+    return None