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.
Files changed (54) hide show
  1. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/PKG-INFO +18 -6
  2. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/README.md +15 -5
  3. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/pyproject.toml +3 -1
  4. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/__init__.py +1 -1
  5. kgmodule_utils-0.30.1/src/kg_utils/synthesis/_anthropic.py +101 -0
  6. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/_config.py +9 -0
  7. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/_text.py +86 -12
  8. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/factory.py +4 -0
  9. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/LICENSE +0 -0
  10. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/analysis/__init__.py +0 -0
  11. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/analysis/scores.py +0 -0
  12. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/corpus_embedder.py +0 -0
  13. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/devicepack.py +0 -0
  14. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/embed.py +0 -0
  15. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/embedder.py +0 -0
  16. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/extractor.py +0 -0
  17. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/__init__.py +0 -0
  18. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/converters.py +0 -0
  19. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/derived.py +0 -0
  20. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/manifest.py +0 -0
  21. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/ingest/pipeline.py +0 -0
  22. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/__init__.py +0 -0
  23. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/_names.py +0 -0
  24. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/cli.py +0 -0
  25. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/mcp/server.py +0 -0
  26. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/module.py +0 -0
  27. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/pipeline.py +0 -0
  28. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/py.typed +0 -0
  29. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/retrieval/__init__.py +0 -0
  30. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/retrieval/hits.py +0 -0
  31. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/semantic.py +0 -0
  32. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/snapshots/__init__.py +0 -0
  33. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/snapshots/manager.py +0 -0
  34. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/snapshots/models.py +0 -0
  35. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/specs.py +0 -0
  36. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/stats.py +0 -0
  37. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/store.py +0 -0
  38. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/__init__.py +0 -0
  39. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/synthesis/_image.py +0 -0
  40. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/temporal.py +0 -0
  41. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/validation.py +0 -0
  42. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/vector_backend.py +0 -0
  43. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/__init__.py +0 -0
  44. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/graph_html.py +0 -0
  45. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/theme.py +0 -0
  46. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz/tooltip.py +0 -0
  47. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/__init__.py +0 -0
  48. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/layout.py +0 -0
  49. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/organic.py +0 -0
  50. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/qt.py +0 -0
  51. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/viz3d/species.py +0 -0
  52. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/worker/__init__.py +0 -0
  53. {kgmodule_utils-0.29.2 → kgmodule_utils-0.30.1}/src/kg_utils/worker/client.py +0 -0
  54. {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.29.2
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
  [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
59
61
  [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
60
- [![Version](https://img.shields.io/badge/version-0.29.2-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
62
+ [![Version](https://img.shields.io/badge/version-0.30.1-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
61
63
  [![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)
62
64
  [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
63
65
  [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21284866-blue.svg)](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.29.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21284866
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.29.2},
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
  [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
3
3
  [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
4
- [![Version](https://img.shields.io/badge/version-0.29.2-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
4
+ [![Version](https://img.shields.io/badge/version-0.30.1-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
5
5
  [![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)
6
6
  [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
7
7
  [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21284866-blue.svg)](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.29.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21284866
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.29.2},
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.29.2"
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",
@@ -72,4 +72,4 @@ The core install is stdlib-only; everything heavier is opt-in.
72
72
  pip install 'kgmodule-utils[synthesis-mflux]' # + mflux (Apple Silicon local gen)
73
73
  """
74
74
 
75
- __version__ = "0.29.2"
75
+ __version__ = "0.30.1"
@@ -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 OpenAI backends."""
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 concise "
26
- "image generation prompt (one paragraph, no bullet points, no quotation marks) that vividly "
27
- "describes the scene for a text-to-image model. Focus on visual elements: setting, lighting, "
28
- "figures, mood, and artistic style. Do NOT include any text, labels, captions, or words in "
29
- "the scene description. Output ONLY the prompt, nothing else."
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
- "max_tokens": max_tokens or self._cfg.max_tokens,
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
- resp = client.chat.completions.create(**kwargs)
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
- return [m.id for m in self._client().models.list().data if m.id]
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