kgmodule-utils 0.29.2__tar.gz → 0.30.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/PKG-INFO +18 -6
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/README.md +15 -5
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/pyproject.toml +3 -1
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/__init__.py +1 -1
- kgmodule_utils-0.30.1/src/kg_utils/synthesis/_anthropic.py +101 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/_config.py +9 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/_text.py +86 -12
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/factory.py +4 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/LICENSE +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/analysis/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/analysis/scores.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/corpus_embedder.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/devicepack.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/embed.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/embedder.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/extractor.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/converters.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/derived.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/manifest.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/pipeline.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/_names.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/cli.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/server.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/module.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/pipeline.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/py.typed +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/retrieval/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/retrieval/hits.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/semantic.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/snapshots/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/snapshots/manager.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/snapshots/models.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/specs.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/stats.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/store.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/_image.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/temporal.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/validation.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/vector_backend.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/graph_html.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/theme.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/tooltip.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/layout.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/organic.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/qt.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/species.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/worker/__init__.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/worker/client.py +0 -0
- {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/worker/ops.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: kgmodule-utils
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.30.1
|
|
4
4
|
Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
|
|
5
5
|
License-Expression: Elastic-2.0
|
|
6
6
|
License-File: LICENSE
|
|
@@ -25,6 +25,8 @@ Provides-Extra: viz3d
|
|
|
25
25
|
Provides-Extra: viz3d-qt
|
|
26
26
|
Provides-Extra: viz3d-render
|
|
27
27
|
Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d-qt"
|
|
28
|
+
Requires-Dist: anthropic (>=2.0.0) ; extra == "synthesis"
|
|
29
|
+
Requires-Dist: anthropic (>=2.0.0) ; extra == "synthesis-mflux"
|
|
28
30
|
Requires-Dist: click (>=8.1.0) ; extra == "mcp"
|
|
29
31
|
Requires-Dist: firecrawl-anydoc (>=0.1.9) ; extra == "ingest"
|
|
30
32
|
Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis"
|
|
@@ -57,7 +59,7 @@ Description-Content-Type: text/markdown
|
|
|
57
59
|
|
|
58
60
|
[](https://www.python.org/)
|
|
59
61
|
[](https://www.elastic.co/licensing/elastic-license)
|
|
60
|
-
[](https://github.com/Flux-Frontiers/KG_utils/releases)
|
|
61
63
|
[](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
|
|
62
64
|
[](https://python-poetry.org/)
|
|
63
65
|
[](https://doi.org/10.5281/zenodo.21284866)
|
|
@@ -82,6 +84,16 @@ Fleet modules use it in two ways. [PyCodeKG](https://github.com/Flux-Frontiers/p
|
|
|
82
84
|
|
|
83
85
|
## Latest News
|
|
84
86
|
|
|
87
|
+
- **0.30.1 (2026-11-17)** -- The image rewrite prompt asks for an accurate
|
|
88
|
+
scene: the end of the moment, a person turned into something shown only as
|
|
89
|
+
what they became, the narrator in the scene, everyone clothed, and no
|
|
90
|
+
lettering. A rewrite model of Qwen3.6-35B-A3B or Qwen3.8-27B follows the
|
|
91
|
+
rules; a 4B model mostly ignores them.
|
|
92
|
+
- **0.30.0 (2026-11-05)** -- An Anthropic text backend: `SYNTH_BACKEND=anthropic`
|
|
93
|
+
(or `backend="anthropic"`) answers through Claude via the `anthropic` SDK,
|
|
94
|
+
now part of the `synthesis` extras. And OpenAI's gpt-5 and later answer
|
|
95
|
+
again: the OpenAI backend sends `max_completion_tokens`, drops a
|
|
96
|
+
temperature the model refuses, logs failures, and lists only chat models.
|
|
85
97
|
- **0.29.2 (2026-11-02)** -- A security release. The `synthesis` extras
|
|
86
98
|
floor Pillow at 13.0.0 and `viz3d-qt` floors quiltwright at 0.17.0, so a
|
|
87
99
|
fresh install can no longer resolve Pillow 12.3.0 and its 41 advisories.
|
|
@@ -291,7 +303,7 @@ and the standard `<tool> mcp` command (`kg_utils.mcp`).
|
|
|
291
303
|
pip install 'kgmodule-utils[mcp]'
|
|
292
304
|
```
|
|
293
305
|
|
|
294
|
-
### With text + image synthesis (oMLX / Ollama / OpenAI / mflux-serve)
|
|
306
|
+
### With text + image synthesis (oMLX / Ollama / OpenAI / Anthropic / mflux-serve)
|
|
295
307
|
|
|
296
308
|
```bash
|
|
297
309
|
pip install 'kgmodule-utils[synthesis]'
|
|
@@ -470,7 +482,7 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
|
|
|
470
482
|
|
|
471
483
|
| Class / function | Description |
|
|
472
484
|
|---|---|
|
|
473
|
-
| `TextBackend` | Enum: `omlx` \| `ollama` \| `openai` |
|
|
485
|
+
| `TextBackend` | Enum: `omlx` \| `ollama` \| `openai` \| `anthropic` |
|
|
474
486
|
| `ImageBackend` | Enum: `mflux-local` \| `mflux-serve` \| `openai` |
|
|
475
487
|
| `TextConfig` | Backend config dataclass with `resolved_endpoint()` / `resolved_model()` |
|
|
476
488
|
| `ImageConfig` | Backend config dataclass with `resolved_server_url()` / `resolved_model()` |
|
|
@@ -876,7 +888,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
876
888
|
|
|
877
889
|
**APA**
|
|
878
890
|
|
|
879
|
-
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.
|
|
891
|
+
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.30.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21284866
|
|
880
892
|
|
|
881
893
|
**BibTeX**
|
|
882
894
|
|
|
@@ -884,7 +896,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
884
896
|
@software{suchanek_kgmodule_utils,
|
|
885
897
|
author = {Suchanek, Eric G.},
|
|
886
898
|
title = {{kgmodule-utils}: Shared SDK for the KGModule Knowledge-Graph Ecosystem},
|
|
887
|
-
version = {0.
|
|
899
|
+
version = {0.30.1},
|
|
888
900
|
year = {2026},
|
|
889
901
|
publisher = {Flux-Frontiers},
|
|
890
902
|
url = {https://github.com/Flux-Frontiers/KG_utils},
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
|
|
2
2
|
[](https://www.python.org/)
|
|
3
3
|
[](https://www.elastic.co/licensing/elastic-license)
|
|
4
|
-
[](https://github.com/Flux-Frontiers/KG_utils/releases)
|
|
5
5
|
[](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
|
|
6
6
|
[](https://python-poetry.org/)
|
|
7
7
|
[](https://doi.org/10.5281/zenodo.21284866)
|
|
@@ -26,6 +26,16 @@ Fleet modules use it in two ways. [PyCodeKG](https://github.com/Flux-Frontiers/p
|
|
|
26
26
|
|
|
27
27
|
## Latest News
|
|
28
28
|
|
|
29
|
+
- **0.30.1 (2026-11-17)** -- The image rewrite prompt asks for an accurate
|
|
30
|
+
scene: the end of the moment, a person turned into something shown only as
|
|
31
|
+
what they became, the narrator in the scene, everyone clothed, and no
|
|
32
|
+
lettering. A rewrite model of Qwen3.6-35B-A3B or Qwen3.8-27B follows the
|
|
33
|
+
rules; a 4B model mostly ignores them.
|
|
34
|
+
- **0.30.0 (2026-11-05)** -- An Anthropic text backend: `SYNTH_BACKEND=anthropic`
|
|
35
|
+
(or `backend="anthropic"`) answers through Claude via the `anthropic` SDK,
|
|
36
|
+
now part of the `synthesis` extras. And OpenAI's gpt-5 and later answer
|
|
37
|
+
again: the OpenAI backend sends `max_completion_tokens`, drops a
|
|
38
|
+
temperature the model refuses, logs failures, and lists only chat models.
|
|
29
39
|
- **0.29.2 (2026-11-02)** -- A security release. The `synthesis` extras
|
|
30
40
|
floor Pillow at 13.0.0 and `viz3d-qt` floors quiltwright at 0.17.0, so a
|
|
31
41
|
fresh install can no longer resolve Pillow 12.3.0 and its 41 advisories.
|
|
@@ -235,7 +245,7 @@ and the standard `<tool> mcp` command (`kg_utils.mcp`).
|
|
|
235
245
|
pip install 'kgmodule-utils[mcp]'
|
|
236
246
|
```
|
|
237
247
|
|
|
238
|
-
### With text + image synthesis (oMLX / Ollama / OpenAI / mflux-serve)
|
|
248
|
+
### With text + image synthesis (oMLX / Ollama / OpenAI / Anthropic / mflux-serve)
|
|
239
249
|
|
|
240
250
|
```bash
|
|
241
251
|
pip install 'kgmodule-utils[synthesis]'
|
|
@@ -414,7 +424,7 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
|
|
|
414
424
|
|
|
415
425
|
| Class / function | Description |
|
|
416
426
|
|---|---|
|
|
417
|
-
| `TextBackend` | Enum: `omlx` \| `ollama` \| `openai` |
|
|
427
|
+
| `TextBackend` | Enum: `omlx` \| `ollama` \| `openai` \| `anthropic` |
|
|
418
428
|
| `ImageBackend` | Enum: `mflux-local` \| `mflux-serve` \| `openai` |
|
|
419
429
|
| `TextConfig` | Backend config dataclass with `resolved_endpoint()` / `resolved_model()` |
|
|
420
430
|
| `ImageConfig` | Backend config dataclass with `resolved_server_url()` / `resolved_model()` |
|
|
@@ -820,7 +830,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
820
830
|
|
|
821
831
|
**APA**
|
|
822
832
|
|
|
823
|
-
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.
|
|
833
|
+
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.30.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21284866
|
|
824
834
|
|
|
825
835
|
**BibTeX**
|
|
826
836
|
|
|
@@ -828,7 +838,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
828
838
|
@software{suchanek_kgmodule_utils,
|
|
829
839
|
author = {Suchanek, Eric G.},
|
|
830
840
|
title = {{kgmodule-utils}: Shared SDK for the KGModule Knowledge-Graph Ecosystem},
|
|
831
|
-
version = {0.
|
|
841
|
+
version = {0.30.1},
|
|
832
842
|
year = {2026},
|
|
833
843
|
publisher = {Flux-Frontiers},
|
|
834
844
|
url = {https://github.com/Flux-Frontiers/KG_utils},
|
|
@@ -9,7 +9,7 @@ build-backend = "poetry.core.masonry.api"
|
|
|
9
9
|
|
|
10
10
|
[project]
|
|
11
11
|
name = "kgmodule-utils"
|
|
12
|
-
version = "0.
|
|
12
|
+
version = "0.30.1"
|
|
13
13
|
description = "Shared types, graph store, semantic index, and pipeline base for the KGModule SDK"
|
|
14
14
|
readme = "README.md"
|
|
15
15
|
license = "Elastic-2.0"
|
|
@@ -94,11 +94,13 @@ pdf = [
|
|
|
94
94
|
"pymupdf>=2.0",
|
|
95
95
|
]
|
|
96
96
|
synthesis = [
|
|
97
|
+
"anthropic>=2.0.0",
|
|
97
98
|
"httpx>=0.27.0",
|
|
98
99
|
"openai>=1.30.0",
|
|
99
100
|
"pillow>=13.0.0",
|
|
100
101
|
]
|
|
101
102
|
synthesis-mflux = [
|
|
103
|
+
"anthropic>=2.0.0",
|
|
102
104
|
"httpx>=0.27.0",
|
|
103
105
|
"openai>=1.30.0",
|
|
104
106
|
"pillow>=13.0.0",
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
|
|
2
|
+
"""Anthropic Messages API calls for :class:`~kg_utils.synthesis._text.TextSynthesizer`.
|
|
3
|
+
|
|
4
|
+
The other backends speak the OpenAI wire protocol; Claude is called through
|
|
5
|
+
the official ``anthropic`` SDK, so it lives in its own module and
|
|
6
|
+
``TextSynthesizer`` hands it OpenAI-style messages.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import logging
|
|
12
|
+
|
|
13
|
+
from kg_utils.synthesis._config import TextConfig
|
|
14
|
+
|
|
15
|
+
_log = logging.getLogger(__name__)
|
|
16
|
+
|
|
17
|
+
# Claude thinks before it answers, and the thinking counts against max_tokens,
|
|
18
|
+
# so a budget sized for the answer alone can end before the answer starts.
|
|
19
|
+
_MIN_MAX_TOKENS = 4096
|
|
20
|
+
|
|
21
|
+
# A grounded answer from given passages is chat-shaped work: low effort keeps
|
|
22
|
+
# the thinking short. Older models reject the parameter; see complete().
|
|
23
|
+
_EFFORT = "low"
|
|
24
|
+
|
|
25
|
+
# Models that take the server-side fallback: on a policy decline the API
|
|
26
|
+
# re-runs the request on a fallback model inside the same call.
|
|
27
|
+
_FALLBACK_MODELS = {"claude-fable-5-1", "claude-opus-5-5", "claude-opus-5", "claude-sonnet-5-5"}
|
|
28
|
+
_FALLBACK_BETA = "server-side-fallback-2026-07-01"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _client(cfg: TextConfig): # type: ignore[no-untyped-def]
|
|
32
|
+
import anthropic # type: ignore[import-unresolved]
|
|
33
|
+
|
|
34
|
+
# No key in the config means the SDK's own resolution: ANTHROPIC_API_KEY,
|
|
35
|
+
# ANTHROPIC_AUTH_TOKEN, then an `ant auth login` profile.
|
|
36
|
+
return anthropic.Anthropic(api_key=cfg.api_key or None, base_url=cfg.endpoint or None)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _split_system(messages: list[dict]) -> tuple[str, list[dict]]:
|
|
40
|
+
"""Move OpenAI-style system messages into the Messages API's ``system``."""
|
|
41
|
+
system = "\n\n".join(m["content"] for m in messages if m.get("role") == "system")
|
|
42
|
+
rest = [
|
|
43
|
+
{"role": m["role"], "content": m["content"]} for m in messages if m.get("role") != "system"
|
|
44
|
+
]
|
|
45
|
+
return system, rest
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def complete(cfg: TextConfig, messages: list[dict], *, model: str, max_tokens: int) -> str | None:
|
|
49
|
+
"""One Messages API call; the answer's text, or ``None`` on failure.
|
|
50
|
+
|
|
51
|
+
No sampling parameters are sent: current Claude models reject a
|
|
52
|
+
non-default temperature. Effort is sent when the model takes it, and a
|
|
53
|
+
model that refuses it is asked again without.
|
|
54
|
+
|
|
55
|
+
:param cfg: The synthesizer's configuration (key and endpoint).
|
|
56
|
+
:param messages: OpenAI-style chat messages; system messages become ``system``.
|
|
57
|
+
:param model: The Claude model id.
|
|
58
|
+
:param max_tokens: The caller's budget; raised to leave room for thinking.
|
|
59
|
+
:returns: The text blocks joined, or ``None`` on an error, a refusal or no text.
|
|
60
|
+
"""
|
|
61
|
+
import anthropic # type: ignore[import-unresolved]
|
|
62
|
+
|
|
63
|
+
system, rest = _split_system(messages)
|
|
64
|
+
kwargs: dict = {
|
|
65
|
+
"model": model,
|
|
66
|
+
"max_tokens": max(max_tokens, _MIN_MAX_TOKENS),
|
|
67
|
+
"messages": rest,
|
|
68
|
+
"output_config": {"effort": _EFFORT},
|
|
69
|
+
}
|
|
70
|
+
if system:
|
|
71
|
+
kwargs["system"] = system
|
|
72
|
+
if model in _FALLBACK_MODELS:
|
|
73
|
+
kwargs["betas"] = [_FALLBACK_BETA]
|
|
74
|
+
kwargs["fallbacks"] = "default"
|
|
75
|
+
try:
|
|
76
|
+
client = _client(cfg)
|
|
77
|
+
try:
|
|
78
|
+
response = client.beta.messages.create(**kwargs)
|
|
79
|
+
except anthropic.BadRequestError as exc:
|
|
80
|
+
if "effort" not in str(exc):
|
|
81
|
+
raise
|
|
82
|
+
del kwargs["output_config"]
|
|
83
|
+
response = client.beta.messages.create(**kwargs)
|
|
84
|
+
except Exception as exc: # noqa: BLE001 -- an API error, or no credentials (TypeError)
|
|
85
|
+
_log.warning("text synthesis failed (anthropic, model %s): %s", model, exc)
|
|
86
|
+
return None
|
|
87
|
+
if response.stop_reason == "refusal":
|
|
88
|
+
_log.warning(
|
|
89
|
+
"text synthesis declined (anthropic, model %s): %s", model, response.stop_details
|
|
90
|
+
)
|
|
91
|
+
return None
|
|
92
|
+
text = "".join(block.text for block in response.content if block.type == "text").strip()
|
|
93
|
+
return text or None
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def list_models(cfg: TextConfig) -> list[str]:
|
|
97
|
+
"""The Claude model ids the key can use, newest first; empty on failure."""
|
|
98
|
+
try:
|
|
99
|
+
return [m.id for m in _client(cfg).models.list() if m.id]
|
|
100
|
+
except Exception: # noqa: BLE001
|
|
101
|
+
return []
|
|
@@ -14,6 +14,7 @@ class TextBackend(str, Enum):
|
|
|
14
14
|
OMLX = "omlx" # local oMLX / vLLM — OpenAI wire protocol with MLX thinking suppression
|
|
15
15
|
OLLAMA = "ollama" # local Ollama — OpenAI wire protocol, no api_key required
|
|
16
16
|
OPENAI = "openai" # OpenAI cloud API — requires OPENAI_API_KEY / SYNTH_API_KEY
|
|
17
|
+
ANTHROPIC = "anthropic" # Claude API — anthropic SDK; ANTHROPIC_API_KEY or an `ant` profile
|
|
17
18
|
|
|
18
19
|
|
|
19
20
|
class ImageBackend(str, Enum):
|
|
@@ -38,6 +39,11 @@ _TEXT_DEFAULTS: dict[TextBackend, dict[str, str]] = {
|
|
|
38
39
|
"endpoint": "https://api.openai.com/v1",
|
|
39
40
|
"model": "gpt-4o-mini",
|
|
40
41
|
},
|
|
42
|
+
# The SDK's own endpoint is used when none is set.
|
|
43
|
+
TextBackend.ANTHROPIC: {
|
|
44
|
+
"endpoint": "",
|
|
45
|
+
"model": "claude-opus-5-5",
|
|
46
|
+
},
|
|
41
47
|
}
|
|
42
48
|
|
|
43
49
|
_IMAGE_DEFAULTS: dict[ImageBackend, dict[str, str]] = {
|
|
@@ -130,6 +136,9 @@ def text_config_from_env() -> TextConfig:
|
|
|
130
136
|
or os.environ.get("OPENAI_API_KEY")
|
|
131
137
|
or ""
|
|
132
138
|
)
|
|
139
|
+
if backend == TextBackend.ANTHROPIC:
|
|
140
|
+
# An OpenAI key is never a Claude key; empty lets the SDK resolve one.
|
|
141
|
+
api_key = os.environ.get("ANTHROPIC_API_KEY") or ""
|
|
133
142
|
model = os.environ.get("SYNTH_MODEL") or os.environ.get("VLLM_MODEL") or ""
|
|
134
143
|
return TextConfig(backend=backend, endpoint=endpoint, api_key=api_key, model=model)
|
|
135
144
|
|
|
@@ -1,12 +1,34 @@
|
|
|
1
1
|
# © 2026 Eric G. Suchanek, PhD — Flux-Frontiers · SPDX-License-Identifier: Elastic-2.0
|
|
2
|
-
"""TextSynthesizer — unified LLM completion across oMLX, Ollama, and
|
|
2
|
+
"""TextSynthesizer — unified LLM completion across oMLX, Ollama, OpenAI and Anthropic backends."""
|
|
3
3
|
|
|
4
4
|
from __future__ import annotations
|
|
5
5
|
|
|
6
|
+
import logging
|
|
6
7
|
import re
|
|
7
8
|
|
|
8
9
|
from kg_utils.synthesis._config import TextBackend, TextConfig
|
|
9
10
|
|
|
11
|
+
_log = logging.getLogger(__name__)
|
|
12
|
+
|
|
13
|
+
# OpenAI model ids that the chat-completions route cannot serve: audio, image,
|
|
14
|
+
# realtime and moderation models, embeddings, and the models served only by
|
|
15
|
+
# v1/responses (the -pro and codex ones). Search models answer from the web,
|
|
16
|
+
# not from the passages they are given.
|
|
17
|
+
_OPENAI_NON_CHAT = (
|
|
18
|
+
"audio",
|
|
19
|
+
"codex",
|
|
20
|
+
"embedding",
|
|
21
|
+
"image",
|
|
22
|
+
"live",
|
|
23
|
+
"moderation",
|
|
24
|
+
"-pro",
|
|
25
|
+
"realtime",
|
|
26
|
+
"search",
|
|
27
|
+
"transcribe",
|
|
28
|
+
"tts",
|
|
29
|
+
"whisper",
|
|
30
|
+
)
|
|
31
|
+
|
|
10
32
|
# ---------------------------------------------------------------------------
|
|
11
33
|
# System prompts
|
|
12
34
|
# ---------------------------------------------------------------------------
|
|
@@ -22,11 +44,19 @@ _RAG_SYSTEM = (
|
|
|
22
44
|
)
|
|
23
45
|
|
|
24
46
|
_IMAGE_REWRITE_SYSTEM = (
|
|
25
|
-
"You are an expert art director. Given a passage of historical text, write a single
|
|
26
|
-
"image generation prompt (one paragraph, no bullet points, no quotation marks)
|
|
27
|
-
"describes the scene for a text-to-image model. Focus on
|
|
28
|
-
"figures, mood, and artistic style.
|
|
29
|
-
"the scene
|
|
47
|
+
"You are an expert art director. Given a passage of historical text, write a single "
|
|
48
|
+
"concise image generation prompt (one paragraph, no bullet points, no quotation marks) "
|
|
49
|
+
"that vividly and ACCURATELY describes the scene for a text-to-image model. Focus on "
|
|
50
|
+
"visual elements: setting, lighting, figures, mood, and artistic style. Be faithful to "
|
|
51
|
+
"the passage: show the scene as it stands at the END of the moment described. Anyone the "
|
|
52
|
+
"passage says was turned into something no longer exists as a person; show only the thing"
|
|
53
|
+
" they became. Name every key subject concretely (the animal, the object, its material). "
|
|
54
|
+
"If the passage has a narrator or eyewitness, place them in the scene, watching. Describe"
|
|
55
|
+
" people by appearance and period clothing, since the image model does not know names. Do"
|
|
56
|
+
" NOT include any text, labels, captions, or words in the scene description. Anyone "
|
|
57
|
+
"shown, including a figure turned to stone or salt, is fully clothed in period dress. "
|
|
58
|
+
"Never ask for names, titles or lettering to appear on ships, signs or anything else. "
|
|
59
|
+
"Keep it under 120 words. Output ONLY the prompt, nothing else."
|
|
30
60
|
)
|
|
31
61
|
|
|
32
62
|
|
|
@@ -47,6 +77,8 @@ class TextSynthesizer:
|
|
|
47
77
|
|
|
48
78
|
def __init__(self, config: TextConfig) -> None:
|
|
49
79
|
self._cfg = config
|
|
80
|
+
# OpenAI models that refused a temperature; later calls leave it out.
|
|
81
|
+
self._fixed_temperature: set[str] = set()
|
|
50
82
|
|
|
51
83
|
# ------------------------------------------------------------------
|
|
52
84
|
# Internal helpers
|
|
@@ -76,22 +108,48 @@ class TextSynthesizer:
|
|
|
76
108
|
max_tokens: int | None = None,
|
|
77
109
|
temperature: float = 0.7,
|
|
78
110
|
) -> str | None:
|
|
111
|
+
mdl = model or self._cfg.resolved_model()
|
|
112
|
+
if self._cfg.backend == TextBackend.ANTHROPIC:
|
|
113
|
+
from kg_utils.synthesis import _anthropic
|
|
114
|
+
|
|
115
|
+
raw = _anthropic.complete(
|
|
116
|
+
self._cfg, messages, model=mdl, max_tokens=max_tokens or self._cfg.max_tokens
|
|
117
|
+
)
|
|
118
|
+
return self._strip_thinking(raw) if raw else None
|
|
79
119
|
try:
|
|
80
120
|
client = self._client()
|
|
81
|
-
mdl = model or self._cfg.resolved_model()
|
|
82
121
|
extra = self._extra_body()
|
|
122
|
+
openai = self._cfg.backend == TextBackend.OPENAI
|
|
123
|
+
# OpenAI's reasoning models (gpt-5 and later, o-series) reject
|
|
124
|
+
# max_tokens; max_completion_tokens is accepted by every OpenAI
|
|
125
|
+
# chat model. Local servers keep the older name.
|
|
126
|
+
budget = "max_completion_tokens" if openai else "max_tokens"
|
|
83
127
|
kwargs: dict = {
|
|
84
128
|
"model": mdl,
|
|
85
129
|
"messages": messages,
|
|
86
|
-
|
|
87
|
-
"temperature": temperature,
|
|
130
|
+
budget: max_tokens or self._cfg.max_tokens,
|
|
88
131
|
}
|
|
132
|
+
if not (openai and mdl in self._fixed_temperature):
|
|
133
|
+
kwargs["temperature"] = temperature
|
|
89
134
|
if extra:
|
|
90
135
|
kwargs["extra_body"] = extra
|
|
91
|
-
|
|
136
|
+
try:
|
|
137
|
+
resp = client.chat.completions.create(**kwargs)
|
|
138
|
+
except Exception as exc:
|
|
139
|
+
# Reasoning models allow only their default temperature, and
|
|
140
|
+
# which models those are changes with every release, so the
|
|
141
|
+
# refusal is the test rather than a list of names.
|
|
142
|
+
if not (openai and "temperature" in kwargs and "temperature" in str(exc)):
|
|
143
|
+
raise
|
|
144
|
+
self._fixed_temperature.add(mdl)
|
|
145
|
+
del kwargs["temperature"]
|
|
146
|
+
resp = client.chat.completions.create(**kwargs)
|
|
92
147
|
raw = (resp.choices[0].message.content or "").strip()
|
|
93
148
|
return self._strip_thinking(raw) or None
|
|
94
|
-
except Exception: # noqa: BLE001
|
|
149
|
+
except Exception as exc: # noqa: BLE001
|
|
150
|
+
_log.warning(
|
|
151
|
+
"text synthesis failed (%s, model %s): %s", self._cfg.backend.value, mdl, exc
|
|
152
|
+
)
|
|
95
153
|
return None
|
|
96
154
|
|
|
97
155
|
# ------------------------------------------------------------------
|
|
@@ -126,13 +184,29 @@ class TextSynthesizer:
|
|
|
126
184
|
def list_models(self) -> list[str]:
|
|
127
185
|
"""Return the model IDs available at the configured endpoint.
|
|
128
186
|
|
|
187
|
+
On OpenAI the account lists every model it can use, most of which are
|
|
188
|
+
not chat models; only the ones chat completions can answer with are
|
|
189
|
+
returned.
|
|
190
|
+
|
|
129
191
|
:returns: List of model ID strings; empty list on failure or if the
|
|
130
192
|
endpoint does not support the ``/v1/models`` route.
|
|
131
193
|
"""
|
|
194
|
+
if self._cfg.backend == TextBackend.ANTHROPIC:
|
|
195
|
+
from kg_utils.synthesis import _anthropic
|
|
196
|
+
|
|
197
|
+
return _anthropic.list_models(self._cfg)
|
|
132
198
|
try:
|
|
133
|
-
|
|
199
|
+
ids = [m.id for m in self._client().models.list().data if m.id]
|
|
134
200
|
except Exception: # noqa: BLE001
|
|
135
201
|
return []
|
|
202
|
+
if self._cfg.backend != TextBackend.OPENAI:
|
|
203
|
+
return ids
|
|
204
|
+
return [
|
|
205
|
+
i
|
|
206
|
+
for i in ids
|
|
207
|
+
if i.startswith(("gpt-", "o1", "o3", "o4", "chat"))
|
|
208
|
+
and not any(part in i for part in _OPENAI_NON_CHAT)
|
|
209
|
+
]
|
|
136
210
|
|
|
137
211
|
def synthesize_rag(
|
|
138
212
|
self,
|
|
@@ -65,6 +65,10 @@ def text_synth_for_backend(backend: str, fallback: TextSynthesizer) -> TextSynth
|
|
|
65
65
|
api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("SYNTH_API_KEY") or ""
|
|
66
66
|
return TextSynthesizer(TextConfig(backend=selected, api_key=api_key))
|
|
67
67
|
|
|
68
|
+
if selected == TextBackend.ANTHROPIC:
|
|
69
|
+
api_key = os.environ.get("ANTHROPIC_API_KEY") or ""
|
|
70
|
+
return TextSynthesizer(TextConfig(backend=selected, api_key=api_key))
|
|
71
|
+
|
|
68
72
|
return fallback
|
|
69
73
|
|
|
70
74
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|