MetacouplingLLM 0.1.0__py3-none-any.whl
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.
- metacouplingllm/__init__.py +208 -0
- metacouplingllm/core.py +4542 -0
- metacouplingllm/data/Papers.zip +0 -0
- metacouplingllm/data/PeriTelecoupling_clean.csv +49953 -0
- metacouplingllm/data/PeriTelecoupling_subset.csv +11 -0
- metacouplingllm/data/chunk_embeddings.manifest.json +11 -0
- metacouplingllm/data/chunk_embeddings.npy +0 -0
- metacouplingllm/data/pericoupled_adm1_edge_list.csv +8291 -0
- metacouplingllm/data/telecoupling_literature.bib +3498 -0
- metacouplingllm/knowledge/__init__.py +1 -0
- metacouplingllm/knowledge/adm1_pericoupling.py +591 -0
- metacouplingllm/knowledge/citations.py +109 -0
- metacouplingllm/knowledge/countries.py +557 -0
- metacouplingllm/knowledge/examples.py +713 -0
- metacouplingllm/knowledge/framework.py +717 -0
- metacouplingllm/knowledge/literature.py +518 -0
- metacouplingllm/knowledge/pericoupling.py +241 -0
- metacouplingllm/knowledge/rag.py +1791 -0
- metacouplingllm/knowledge/references.py +112 -0
- metacouplingllm/knowledge/websearch.py +1842 -0
- metacouplingllm/llm/__init__.py +1 -0
- metacouplingllm/llm/client.py +636 -0
- metacouplingllm/llm/parser.py +868 -0
- metacouplingllm/output/__init__.py +1 -0
- metacouplingllm/output/formatter.py +276 -0
- metacouplingllm/prompts/__init__.py +1 -0
- metacouplingllm/prompts/builder.py +477 -0
- metacouplingllm/prompts/templates.py +556 -0
- metacouplingllm/visualization/__init__.py +114 -0
- metacouplingllm/visualization/adm1_map.py +884 -0
- metacouplingllm/visualization/worldmap.py +1372 -0
- metacouplingllm-0.1.0.dist-info/METADATA +440 -0
- metacouplingllm-0.1.0.dist-info/RECORD +35 -0
- metacouplingllm-0.1.0.dist-info/WHEEL +4 -0
- metacouplingllm-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""LLM client abstraction and response parsing."""
|
|
@@ -0,0 +1,636 @@
|
|
|
1
|
+
"""
|
|
2
|
+
LLM client abstraction using Protocol-based structural subtyping.
|
|
3
|
+
|
|
4
|
+
Provides a ``LLMClient`` protocol that any compatible client can satisfy,
|
|
5
|
+
plus ready-made adapters for OpenAI and Anthropic APIs.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import time
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from typing import Any, Protocol, runtime_checkable
|
|
13
|
+
|
|
14
|
+
# Maximum number of retries for transient API errors (rate limits, etc.)
|
|
15
|
+
_MAX_RETRIES = 3
|
|
16
|
+
_RETRY_BACKOFF_BASE = 1.0 # seconds
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
# ---------------------------------------------------------------------------
|
|
20
|
+
# Data classes
|
|
21
|
+
# ---------------------------------------------------------------------------
|
|
22
|
+
|
|
23
|
+
@dataclass
|
|
24
|
+
class Message:
|
|
25
|
+
"""A single message in a conversation."""
|
|
26
|
+
|
|
27
|
+
role: str # "system" | "user" | "assistant"
|
|
28
|
+
content: str
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass
|
|
32
|
+
class LLMResponse:
|
|
33
|
+
"""Response from an LLM provider."""
|
|
34
|
+
|
|
35
|
+
content: str
|
|
36
|
+
usage: dict[str, int] = field(default_factory=dict)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
# ---------------------------------------------------------------------------
|
|
40
|
+
# Protocol
|
|
41
|
+
# ---------------------------------------------------------------------------
|
|
42
|
+
|
|
43
|
+
@runtime_checkable
|
|
44
|
+
class LLMClient(Protocol):
|
|
45
|
+
"""Protocol that any LLM client must satisfy.
|
|
46
|
+
|
|
47
|
+
This uses structural subtyping — any object with a compatible ``chat``
|
|
48
|
+
method will work, no explicit inheritance required.
|
|
49
|
+
|
|
50
|
+
Example
|
|
51
|
+
-------
|
|
52
|
+
>>> class MyClient:
|
|
53
|
+
... def chat(self, messages, temperature=0.7, max_tokens=None):
|
|
54
|
+
... return LLMResponse(content="Hello!")
|
|
55
|
+
>>> isinstance(MyClient(), LLMClient)
|
|
56
|
+
True
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
def chat(
|
|
60
|
+
self,
|
|
61
|
+
messages: list[Message],
|
|
62
|
+
temperature: float = 0.7,
|
|
63
|
+
max_tokens: int | None = None,
|
|
64
|
+
) -> LLMResponse:
|
|
65
|
+
"""Send a conversation to the LLM and get a response.
|
|
66
|
+
|
|
67
|
+
Parameters
|
|
68
|
+
----------
|
|
69
|
+
messages:
|
|
70
|
+
Ordered list of messages (system, user, assistant).
|
|
71
|
+
temperature:
|
|
72
|
+
Sampling temperature (0.0 = deterministic, 1.0 = creative).
|
|
73
|
+
max_tokens:
|
|
74
|
+
Maximum tokens in the response. ``None`` uses the model default.
|
|
75
|
+
|
|
76
|
+
Returns
|
|
77
|
+
-------
|
|
78
|
+
An ``LLMResponse`` with the assistant's reply and optional usage data.
|
|
79
|
+
"""
|
|
80
|
+
...
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
# ---------------------------------------------------------------------------
|
|
84
|
+
# OpenAI Adapter
|
|
85
|
+
# ---------------------------------------------------------------------------
|
|
86
|
+
|
|
87
|
+
class OpenAIAdapter:
|
|
88
|
+
"""Adapter wrapping an OpenAI client to satisfy ``LLMClient``.
|
|
89
|
+
|
|
90
|
+
Parameters
|
|
91
|
+
----------
|
|
92
|
+
client:
|
|
93
|
+
An ``openai.OpenAI`` instance (or compatible).
|
|
94
|
+
model:
|
|
95
|
+
Model identifier (e.g., ``"gpt-4o"``, ``"gpt-4o-mini"``).
|
|
96
|
+
"""
|
|
97
|
+
|
|
98
|
+
def __init__(self, client: Any, model: str = "gpt-4o") -> None:
|
|
99
|
+
self._client = client
|
|
100
|
+
self._model = model
|
|
101
|
+
|
|
102
|
+
@property
|
|
103
|
+
def raw_client(self) -> Any:
|
|
104
|
+
"""Expose the wrapped OpenAI client for advanced integrations."""
|
|
105
|
+
return self._client
|
|
106
|
+
|
|
107
|
+
@property
|
|
108
|
+
def model(self) -> str:
|
|
109
|
+
"""Return the configured model identifier."""
|
|
110
|
+
return self._model
|
|
111
|
+
|
|
112
|
+
def chat(
|
|
113
|
+
self,
|
|
114
|
+
messages: list[Message],
|
|
115
|
+
temperature: float = 0.7,
|
|
116
|
+
max_tokens: int | None = None,
|
|
117
|
+
) -> LLMResponse:
|
|
118
|
+
"""Send messages via the OpenAI Chat Completions API."""
|
|
119
|
+
api_messages = [
|
|
120
|
+
{"role": msg.role, "content": msg.content} for msg in messages
|
|
121
|
+
]
|
|
122
|
+
|
|
123
|
+
kwargs: dict[str, Any] = {
|
|
124
|
+
"model": self._model,
|
|
125
|
+
"messages": api_messages,
|
|
126
|
+
"temperature": temperature,
|
|
127
|
+
}
|
|
128
|
+
if max_tokens is not None:
|
|
129
|
+
kwargs["max_tokens"] = max_tokens
|
|
130
|
+
|
|
131
|
+
try:
|
|
132
|
+
response = self._client.chat.completions.create(**kwargs)
|
|
133
|
+
except Exception as exc:
|
|
134
|
+
retry_kwargs = dict(kwargs)
|
|
135
|
+
retried = False
|
|
136
|
+
|
|
137
|
+
# GPT-5-family: temperature may only accept the default (1).
|
|
138
|
+
if self._should_retry_without_temperature(exc, temperature):
|
|
139
|
+
retry_kwargs.pop("temperature", None)
|
|
140
|
+
retried = True
|
|
141
|
+
|
|
142
|
+
# GPT-5-family: max_tokens → max_completion_tokens.
|
|
143
|
+
if self._should_retry_with_max_completion_tokens(exc):
|
|
144
|
+
val = retry_kwargs.pop("max_tokens", None)
|
|
145
|
+
if val is not None:
|
|
146
|
+
retry_kwargs["max_completion_tokens"] = val
|
|
147
|
+
retried = True
|
|
148
|
+
|
|
149
|
+
# Model-specific max_tokens cap exceeded: parse the error
|
|
150
|
+
# message and retry with the model's supported limit.
|
|
151
|
+
capped_value = self._parse_max_tokens_cap(exc)
|
|
152
|
+
if capped_value is not None:
|
|
153
|
+
if "max_tokens" in retry_kwargs:
|
|
154
|
+
retry_kwargs["max_tokens"] = capped_value
|
|
155
|
+
elif "max_completion_tokens" in retry_kwargs:
|
|
156
|
+
retry_kwargs["max_completion_tokens"] = capped_value
|
|
157
|
+
retried = True
|
|
158
|
+
|
|
159
|
+
# Rate limit: retry with exponential backoff.
|
|
160
|
+
if not retried and self._is_rate_limit_error(exc):
|
|
161
|
+
return self._retry_with_backoff(kwargs)
|
|
162
|
+
|
|
163
|
+
if not retried:
|
|
164
|
+
raise
|
|
165
|
+
|
|
166
|
+
response = self._client.chat.completions.create(**retry_kwargs)
|
|
167
|
+
|
|
168
|
+
# Safety: handle empty choices array
|
|
169
|
+
if not response.choices:
|
|
170
|
+
return LLMResponse(content="", usage={})
|
|
171
|
+
|
|
172
|
+
choice = response.choices[0]
|
|
173
|
+
usage_data: dict[str, int] = {}
|
|
174
|
+
if response.usage:
|
|
175
|
+
usage_data = {
|
|
176
|
+
"prompt_tokens": response.usage.prompt_tokens,
|
|
177
|
+
"completion_tokens": response.usage.completion_tokens,
|
|
178
|
+
"total_tokens": response.usage.total_tokens,
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
return LLMResponse(
|
|
182
|
+
content=choice.message.content or "",
|
|
183
|
+
usage=usage_data,
|
|
184
|
+
)
|
|
185
|
+
|
|
186
|
+
def _retry_with_backoff(
|
|
187
|
+
self,
|
|
188
|
+
kwargs: dict[str, Any],
|
|
189
|
+
) -> LLMResponse:
|
|
190
|
+
"""Retry the API call with exponential backoff for rate limits."""
|
|
191
|
+
last_exc: Exception | None = None
|
|
192
|
+
for attempt in range(_MAX_RETRIES):
|
|
193
|
+
delay = _RETRY_BACKOFF_BASE * (2 ** attempt)
|
|
194
|
+
time.sleep(delay)
|
|
195
|
+
try:
|
|
196
|
+
response = self._client.chat.completions.create(**kwargs)
|
|
197
|
+
if not response.choices:
|
|
198
|
+
return LLMResponse(content="", usage={})
|
|
199
|
+
choice = response.choices[0]
|
|
200
|
+
usage_data: dict[str, int] = {}
|
|
201
|
+
if response.usage:
|
|
202
|
+
usage_data = {
|
|
203
|
+
"prompt_tokens": response.usage.prompt_tokens,
|
|
204
|
+
"completion_tokens": response.usage.completion_tokens,
|
|
205
|
+
"total_tokens": response.usage.total_tokens,
|
|
206
|
+
}
|
|
207
|
+
return LLMResponse(
|
|
208
|
+
content=choice.message.content or "",
|
|
209
|
+
usage=usage_data,
|
|
210
|
+
)
|
|
211
|
+
except Exception as exc:
|
|
212
|
+
last_exc = exc
|
|
213
|
+
if not self._is_rate_limit_error(exc):
|
|
214
|
+
raise
|
|
215
|
+
raise last_exc # type: ignore[misc]
|
|
216
|
+
|
|
217
|
+
@staticmethod
|
|
218
|
+
def _parse_max_tokens_cap(exc: Exception) -> int | None:
|
|
219
|
+
"""Detect a "max_tokens too large" error and return the model's cap.
|
|
220
|
+
|
|
221
|
+
OpenAI returns messages like::
|
|
222
|
+
|
|
223
|
+
"max_tokens is too large: 65000. This model supports at most
|
|
224
|
+
16384 completion tokens, whereas you provided 65000."
|
|
225
|
+
|
|
226
|
+
This parses the number after "supports at most" and returns it
|
|
227
|
+
so the call can be retried with a compliant value. Returns
|
|
228
|
+
``None`` if the error doesn't match this pattern.
|
|
229
|
+
"""
|
|
230
|
+
import re
|
|
231
|
+
|
|
232
|
+
text = str(exc)
|
|
233
|
+
lowered = text.lower()
|
|
234
|
+
if "max_tokens" not in lowered and "max_completion_tokens" not in lowered:
|
|
235
|
+
return None
|
|
236
|
+
if "too large" not in lowered and "supports at most" not in lowered:
|
|
237
|
+
return None
|
|
238
|
+
match = re.search(r"supports at most\s+(\d+)", text, re.IGNORECASE)
|
|
239
|
+
if match:
|
|
240
|
+
try:
|
|
241
|
+
return int(match.group(1))
|
|
242
|
+
except ValueError:
|
|
243
|
+
return None
|
|
244
|
+
return None
|
|
245
|
+
|
|
246
|
+
@staticmethod
|
|
247
|
+
def _should_retry_without_temperature(
|
|
248
|
+
exc: Exception,
|
|
249
|
+
temperature: float,
|
|
250
|
+
) -> bool:
|
|
251
|
+
"""Return True when the API rejected a non-default temperature.
|
|
252
|
+
|
|
253
|
+
Some models accept only their default temperature setting. In that
|
|
254
|
+
case, retrying without the parameter is equivalent to using the
|
|
255
|
+
provider default and keeps the adapter compatible.
|
|
256
|
+
"""
|
|
257
|
+
if temperature == 1:
|
|
258
|
+
return False
|
|
259
|
+
|
|
260
|
+
text = str(exc).lower()
|
|
261
|
+
return "temperature" in text and "default (1)" in text
|
|
262
|
+
|
|
263
|
+
@staticmethod
|
|
264
|
+
def _should_retry_with_max_completion_tokens(exc: Exception) -> bool:
|
|
265
|
+
"""Return True when the API rejected ``max_tokens``.
|
|
266
|
+
|
|
267
|
+
OpenAI's GPT-5-family models require ``max_completion_tokens``
|
|
268
|
+
instead of ``max_tokens``. Detecting this from the error message
|
|
269
|
+
lets the adapter transparently support both old and new models.
|
|
270
|
+
"""
|
|
271
|
+
text = str(exc).lower()
|
|
272
|
+
return "max_tokens" in text and "max_completion_tokens" in text
|
|
273
|
+
|
|
274
|
+
@staticmethod
|
|
275
|
+
def _is_rate_limit_error(exc: Exception) -> bool:
|
|
276
|
+
"""Return True for rate-limit (429) or server (5xx) errors."""
|
|
277
|
+
text = str(exc).lower()
|
|
278
|
+
if "rate" in text and "limit" in text:
|
|
279
|
+
return True
|
|
280
|
+
if "429" in text:
|
|
281
|
+
return True
|
|
282
|
+
# Transient server errors worth retrying
|
|
283
|
+
if any(code in text for code in ("500", "502", "503", "529")):
|
|
284
|
+
return True
|
|
285
|
+
return False
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
# ---------------------------------------------------------------------------
|
|
289
|
+
# Anthropic Adapter
|
|
290
|
+
# ---------------------------------------------------------------------------
|
|
291
|
+
|
|
292
|
+
class AnthropicAdapter:
|
|
293
|
+
"""Adapter wrapping an Anthropic client to satisfy ``LLMClient``.
|
|
294
|
+
|
|
295
|
+
The Anthropic API handles system prompts differently (as a separate
|
|
296
|
+
parameter rather than a message), so this adapter extracts the system
|
|
297
|
+
message automatically.
|
|
298
|
+
|
|
299
|
+
Parameters
|
|
300
|
+
----------
|
|
301
|
+
client:
|
|
302
|
+
An ``anthropic.Anthropic`` instance (or compatible).
|
|
303
|
+
model:
|
|
304
|
+
Model identifier (e.g., ``"claude-sonnet-4-20250514"``).
|
|
305
|
+
"""
|
|
306
|
+
|
|
307
|
+
# Models that reject the ``temperature`` parameter (Opus 4.7 removed
|
|
308
|
+
# it along with top_p / top_k). When the configured model is in this
|
|
309
|
+
# set, we omit ``temperature`` from the request upfront. As a safety
|
|
310
|
+
# net for unknown future models, we also catch the
|
|
311
|
+
# "temperature is deprecated" error and retry once without it.
|
|
312
|
+
_MODELS_WITHOUT_TEMPERATURE: frozenset[str] = frozenset({
|
|
313
|
+
"claude-opus-4-7",
|
|
314
|
+
})
|
|
315
|
+
|
|
316
|
+
# When ``max_tokens`` exceeds this threshold, switch to streaming via
|
|
317
|
+
# ``client.messages.stream`` + ``.get_final_message``. The Anthropic
|
|
318
|
+
# SDK refuses non-streaming requests whose estimated generation time
|
|
319
|
+
# would exceed the 10-minute non-streaming budget. For Opus 4.7 the
|
|
320
|
+
# practical cutoff is around 21K output tokens; we use 16384 as a
|
|
321
|
+
# safe margin.
|
|
322
|
+
_STREAMING_MAX_TOKENS_THRESHOLD: int = 16384
|
|
323
|
+
|
|
324
|
+
def __init__(self, client: Any, model: str = "claude-sonnet-4-20250514") -> None:
|
|
325
|
+
self._client = client
|
|
326
|
+
self._model = model
|
|
327
|
+
|
|
328
|
+
@property
|
|
329
|
+
def raw_client(self) -> Any:
|
|
330
|
+
"""Expose the wrapped Anthropic client for advanced integrations."""
|
|
331
|
+
return self._client
|
|
332
|
+
|
|
333
|
+
@property
|
|
334
|
+
def model(self) -> str:
|
|
335
|
+
"""Return the configured model identifier."""
|
|
336
|
+
return self._model
|
|
337
|
+
|
|
338
|
+
def chat(
|
|
339
|
+
self,
|
|
340
|
+
messages: list[Message],
|
|
341
|
+
temperature: float = 0.7,
|
|
342
|
+
max_tokens: int | None = None,
|
|
343
|
+
) -> LLMResponse:
|
|
344
|
+
"""Send messages via the Anthropic Messages API."""
|
|
345
|
+
# Extract system messages (combine if multiple are present)
|
|
346
|
+
system_parts: list[str] = []
|
|
347
|
+
conversation: list[dict[str, str]] = []
|
|
348
|
+
|
|
349
|
+
for msg in messages:
|
|
350
|
+
if msg.role == "system":
|
|
351
|
+
system_parts.append(msg.content)
|
|
352
|
+
else:
|
|
353
|
+
conversation.append({"role": msg.role, "content": msg.content})
|
|
354
|
+
|
|
355
|
+
system_text = "\n\n".join(system_parts) if system_parts else ""
|
|
356
|
+
|
|
357
|
+
# Anthropic requires a positive max_tokens value
|
|
358
|
+
effective_max = max_tokens if max_tokens and max_tokens > 0 else 4096
|
|
359
|
+
|
|
360
|
+
kwargs: dict[str, Any] = {
|
|
361
|
+
"model": self._model,
|
|
362
|
+
"messages": conversation,
|
|
363
|
+
"max_tokens": effective_max,
|
|
364
|
+
}
|
|
365
|
+
# Skip temperature for models that have removed it (Opus 4.7+).
|
|
366
|
+
if self._model not in self._MODELS_WITHOUT_TEMPERATURE:
|
|
367
|
+
kwargs["temperature"] = temperature
|
|
368
|
+
if system_text:
|
|
369
|
+
kwargs["system"] = system_text
|
|
370
|
+
|
|
371
|
+
# Retry with exponential backoff for rate-limit / transient errors,
|
|
372
|
+
# with a one-shot retry-without-temperature fallback for unknown
|
|
373
|
+
# models that reject temperature at runtime.
|
|
374
|
+
last_exc: Exception | None = None
|
|
375
|
+
for attempt in range(_MAX_RETRIES + 1):
|
|
376
|
+
try:
|
|
377
|
+
response = self._issue_request(kwargs)
|
|
378
|
+
break
|
|
379
|
+
except Exception as exc:
|
|
380
|
+
last_exc = exc
|
|
381
|
+
# One-shot fallback: API rejected temperature on a model
|
|
382
|
+
# not in our compile-time deny list. Strip it and retry
|
|
383
|
+
# the same call; only do this once.
|
|
384
|
+
if (
|
|
385
|
+
"temperature" in kwargs
|
|
386
|
+
and self._is_temperature_deprecated_error(exc)
|
|
387
|
+
):
|
|
388
|
+
kwargs.pop("temperature", None)
|
|
389
|
+
response = self._issue_request(kwargs)
|
|
390
|
+
break
|
|
391
|
+
text = str(exc).lower()
|
|
392
|
+
is_transient = (
|
|
393
|
+
("rate" in text and "limit" in text)
|
|
394
|
+
or any(c in text for c in ("429", "500", "502", "503", "529"))
|
|
395
|
+
or "overloaded" in text
|
|
396
|
+
)
|
|
397
|
+
if not is_transient or attempt >= _MAX_RETRIES:
|
|
398
|
+
raise
|
|
399
|
+
time.sleep(_RETRY_BACKOFF_BASE * (2 ** attempt))
|
|
400
|
+
else:
|
|
401
|
+
raise last_exc # type: ignore[misc]
|
|
402
|
+
|
|
403
|
+
# Extract text content from response blocks
|
|
404
|
+
content_text = ""
|
|
405
|
+
for block in response.content:
|
|
406
|
+
if hasattr(block, "text"):
|
|
407
|
+
content_text += block.text
|
|
408
|
+
|
|
409
|
+
usage_data: dict[str, int] = {}
|
|
410
|
+
if response.usage:
|
|
411
|
+
usage_data = {
|
|
412
|
+
"input_tokens": response.usage.input_tokens,
|
|
413
|
+
"output_tokens": response.usage.output_tokens,
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
return LLMResponse(content=content_text, usage=usage_data)
|
|
417
|
+
|
|
418
|
+
@staticmethod
|
|
419
|
+
def _is_temperature_deprecated_error(exc: Exception) -> bool:
|
|
420
|
+
"""Detect Anthropic's "temperature is deprecated for this model" 400.
|
|
421
|
+
|
|
422
|
+
Opus 4.7 (and any future model that drops sampling parameters)
|
|
423
|
+
returns this exact 400 when ``temperature`` is sent. Returns
|
|
424
|
+
``True`` so the adapter can pop the parameter and retry once.
|
|
425
|
+
"""
|
|
426
|
+
text = str(exc).lower()
|
|
427
|
+
return "temperature" in text and "deprecated" in text
|
|
428
|
+
|
|
429
|
+
def _issue_request(self, kwargs: dict[str, Any]) -> Any:
|
|
430
|
+
"""Issue a single API request, switching to streaming for large
|
|
431
|
+
``max_tokens`` so the SDK doesn't reject the call as exceeding
|
|
432
|
+
the 10-minute non-streaming budget.
|
|
433
|
+
|
|
434
|
+
Returns the same ``Message`` object regardless of which path is
|
|
435
|
+
taken — :meth:`anthropic.MessageStreamManager.get_final_message`
|
|
436
|
+
produces a ``Message`` with the same shape as
|
|
437
|
+
:meth:`anthropic.Anthropic.messages.create`.
|
|
438
|
+
"""
|
|
439
|
+
max_tokens = kwargs.get("max_tokens", 4096)
|
|
440
|
+
if max_tokens > self._STREAMING_MAX_TOKENS_THRESHOLD:
|
|
441
|
+
with self._client.messages.stream(**kwargs) as stream:
|
|
442
|
+
return stream.get_final_message()
|
|
443
|
+
return self._client.messages.create(**kwargs)
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
# ---------------------------------------------------------------------------
|
|
447
|
+
# Gemini Adapter
|
|
448
|
+
# ---------------------------------------------------------------------------
|
|
449
|
+
|
|
450
|
+
class GeminiAdapter:
|
|
451
|
+
"""Adapter wrapping a Google Gemini client to satisfy ``LLMClient``.
|
|
452
|
+
|
|
453
|
+
Built against the new **``google.genai`` SDK** (the unified Google
|
|
454
|
+
GenAI SDK that replaced the deprecated ``google.generativeai``
|
|
455
|
+
package in 2025). Pass a ``google.genai.Client`` instance.
|
|
456
|
+
|
|
457
|
+
Gemini's API has a different message shape than OpenAI/Anthropic:
|
|
458
|
+
* messages use a ``parts`` array, not flat strings;
|
|
459
|
+
* the ``"assistant"`` role is called ``"model"``;
|
|
460
|
+
* the system instruction is a separate ``system_instruction``
|
|
461
|
+
field on the request config, not a conversation message.
|
|
462
|
+
|
|
463
|
+
This adapter normalizes those differences so callers can pass a
|
|
464
|
+
standard ``list[Message]`` exactly like they would for OpenAI or
|
|
465
|
+
Anthropic.
|
|
466
|
+
|
|
467
|
+
Parameters
|
|
468
|
+
----------
|
|
469
|
+
client:
|
|
470
|
+
A ``google.genai.Client`` instance configured with your API key
|
|
471
|
+
(``Client(api_key=...)``).
|
|
472
|
+
model:
|
|
473
|
+
Model identifier (e.g., ``"gemini-2.5-flash"``,
|
|
474
|
+
``"gemini-2.5-pro"``).
|
|
475
|
+
|
|
476
|
+
Examples
|
|
477
|
+
--------
|
|
478
|
+
>>> from google import genai
|
|
479
|
+
>>> from metacouplingllm import GeminiAdapter, MetacouplingAssistant
|
|
480
|
+
>>> client = genai.Client(api_key="...")
|
|
481
|
+
>>> advisor = MetacouplingAssistant(
|
|
482
|
+
... GeminiAdapter(client, model="gemini-2.5-flash")
|
|
483
|
+
... )
|
|
484
|
+
"""
|
|
485
|
+
|
|
486
|
+
def __init__(self, client: Any, model: str = "gemini-2.5-flash") -> None:
|
|
487
|
+
self._client = client
|
|
488
|
+
self._model = model
|
|
489
|
+
|
|
490
|
+
@property
|
|
491
|
+
def raw_client(self) -> Any:
|
|
492
|
+
"""Expose the wrapped ``google.genai.Client`` instance."""
|
|
493
|
+
return self._client
|
|
494
|
+
|
|
495
|
+
@property
|
|
496
|
+
def model(self) -> str:
|
|
497
|
+
"""Return the configured model identifier."""
|
|
498
|
+
return self._model
|
|
499
|
+
|
|
500
|
+
def chat(
|
|
501
|
+
self,
|
|
502
|
+
messages: list[Message],
|
|
503
|
+
temperature: float = 0.7,
|
|
504
|
+
max_tokens: int | None = None,
|
|
505
|
+
) -> LLMResponse:
|
|
506
|
+
"""Send messages via the Gemini ``models.generate_content`` API."""
|
|
507
|
+
# Gemini handles system separately (like Anthropic).
|
|
508
|
+
system_parts: list[str] = []
|
|
509
|
+
contents: list[dict[str, Any]] = []
|
|
510
|
+
for msg in messages:
|
|
511
|
+
if msg.role == "system":
|
|
512
|
+
system_parts.append(msg.content)
|
|
513
|
+
continue
|
|
514
|
+
# Gemini calls the assistant role "model".
|
|
515
|
+
role = "model" if msg.role == "assistant" else "user"
|
|
516
|
+
contents.append(
|
|
517
|
+
{"role": role, "parts": [{"text": msg.content}]}
|
|
518
|
+
)
|
|
519
|
+
|
|
520
|
+
system_instruction = (
|
|
521
|
+
"\n\n".join(system_parts) if system_parts else None
|
|
522
|
+
)
|
|
523
|
+
|
|
524
|
+
# Build the GenerateContentConfig dict-style for cross-version
|
|
525
|
+
# compatibility (the new SDK accepts both dicts and typed
|
|
526
|
+
# GenerateContentConfig objects on `models.generate_content(config=...)`).
|
|
527
|
+
config: dict[str, Any] = {"temperature": temperature}
|
|
528
|
+
if max_tokens is not None:
|
|
529
|
+
config["max_output_tokens"] = max_tokens
|
|
530
|
+
if system_instruction is not None:
|
|
531
|
+
config["system_instruction"] = system_instruction
|
|
532
|
+
|
|
533
|
+
response = self._client.models.generate_content(
|
|
534
|
+
model=self._model,
|
|
535
|
+
contents=contents,
|
|
536
|
+
config=config,
|
|
537
|
+
)
|
|
538
|
+
|
|
539
|
+
# Extract text. Gemini's `.text` raises if the response was
|
|
540
|
+
# blocked or empty; guard against that.
|
|
541
|
+
try:
|
|
542
|
+
content_text = response.text or ""
|
|
543
|
+
except Exception:
|
|
544
|
+
content_text = ""
|
|
545
|
+
|
|
546
|
+
usage_data: dict[str, int] = {}
|
|
547
|
+
usage_meta = getattr(response, "usage_metadata", None)
|
|
548
|
+
if usage_meta is not None:
|
|
549
|
+
usage_data = {
|
|
550
|
+
"input_tokens": int(getattr(usage_meta, "prompt_token_count", 0)),
|
|
551
|
+
"output_tokens": int(getattr(usage_meta, "candidates_token_count", 0)),
|
|
552
|
+
"total_tokens": int(getattr(usage_meta, "total_token_count", 0)),
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
return LLMResponse(content=content_text, usage=usage_data)
|
|
556
|
+
|
|
557
|
+
|
|
558
|
+
# ---------------------------------------------------------------------------
|
|
559
|
+
# Grok (xAI) Adapter
|
|
560
|
+
# ---------------------------------------------------------------------------
|
|
561
|
+
|
|
562
|
+
class GrokAdapter:
|
|
563
|
+
"""Adapter wrapping an xAI Grok client to satisfy ``LLMClient``.
|
|
564
|
+
|
|
565
|
+
Grok's API is OpenAI-protocol-compatible. Pass an ``openai.OpenAI``
|
|
566
|
+
instance configured with ``base_url="https://api.x.ai/v1"``.
|
|
567
|
+
|
|
568
|
+
A separate class (rather than reusing ``OpenAIAdapter``) is needed
|
|
569
|
+
so the auto-wiring in ``MetacouplingAssistant`` can route web search
|
|
570
|
+
to ``GrokWebSearchBackend`` (xAI Live Search) instead of
|
|
571
|
+
``OpenAIWebSearchBackend`` (OpenAI's ``web_search`` tool).
|
|
572
|
+
|
|
573
|
+
Parameters
|
|
574
|
+
----------
|
|
575
|
+
client:
|
|
576
|
+
An ``openai.OpenAI`` instance configured with the xAI base URL.
|
|
577
|
+
model:
|
|
578
|
+
Model identifier (e.g., ``"grok-3"``, ``"grok-2"``).
|
|
579
|
+
|
|
580
|
+
Examples
|
|
581
|
+
--------
|
|
582
|
+
>>> from openai import OpenAI
|
|
583
|
+
>>> from metacouplingllm import GrokAdapter, MetacouplingAssistant
|
|
584
|
+
>>> client = OpenAI(api_key="...", base_url="https://api.x.ai/v1")
|
|
585
|
+
>>> advisor = MetacouplingAssistant(GrokAdapter(client, model="grok-3"))
|
|
586
|
+
"""
|
|
587
|
+
|
|
588
|
+
def __init__(self, client: Any, model: str = "grok-3") -> None:
|
|
589
|
+
self._client = client
|
|
590
|
+
self._model = model
|
|
591
|
+
|
|
592
|
+
@property
|
|
593
|
+
def raw_client(self) -> Any:
|
|
594
|
+
"""Expose the wrapped xAI client (an ``openai.OpenAI`` instance)."""
|
|
595
|
+
return self._client
|
|
596
|
+
|
|
597
|
+
@property
|
|
598
|
+
def model(self) -> str:
|
|
599
|
+
"""Return the configured model identifier."""
|
|
600
|
+
return self._model
|
|
601
|
+
|
|
602
|
+
def chat(
|
|
603
|
+
self,
|
|
604
|
+
messages: list[Message],
|
|
605
|
+
temperature: float = 0.7,
|
|
606
|
+
max_tokens: int | None = None,
|
|
607
|
+
) -> LLMResponse:
|
|
608
|
+
"""Send messages via xAI's chat-completions API (OpenAI-shaped)."""
|
|
609
|
+
api_messages = [
|
|
610
|
+
{"role": msg.role, "content": msg.content} for msg in messages
|
|
611
|
+
]
|
|
612
|
+
kwargs: dict[str, Any] = {
|
|
613
|
+
"model": self._model,
|
|
614
|
+
"messages": api_messages,
|
|
615
|
+
"temperature": temperature,
|
|
616
|
+
}
|
|
617
|
+
if max_tokens is not None:
|
|
618
|
+
kwargs["max_tokens"] = max_tokens
|
|
619
|
+
|
|
620
|
+
response = self._client.chat.completions.create(**kwargs)
|
|
621
|
+
|
|
622
|
+
if not response.choices:
|
|
623
|
+
return LLMResponse(content="", usage={})
|
|
624
|
+
|
|
625
|
+
choice = response.choices[0]
|
|
626
|
+
usage_data: dict[str, int] = {}
|
|
627
|
+
if response.usage:
|
|
628
|
+
usage_data = {
|
|
629
|
+
"prompt_tokens": int(response.usage.prompt_tokens),
|
|
630
|
+
"completion_tokens": int(response.usage.completion_tokens),
|
|
631
|
+
"total_tokens": int(response.usage.total_tokens),
|
|
632
|
+
}
|
|
633
|
+
return LLMResponse(
|
|
634
|
+
content=choice.message.content or "",
|
|
635
|
+
usage=usage_data,
|
|
636
|
+
)
|