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.
Files changed (35) hide show
  1. metacouplingllm/__init__.py +208 -0
  2. metacouplingllm/core.py +4542 -0
  3. metacouplingllm/data/Papers.zip +0 -0
  4. metacouplingllm/data/PeriTelecoupling_clean.csv +49953 -0
  5. metacouplingllm/data/PeriTelecoupling_subset.csv +11 -0
  6. metacouplingllm/data/chunk_embeddings.manifest.json +11 -0
  7. metacouplingllm/data/chunk_embeddings.npy +0 -0
  8. metacouplingllm/data/pericoupled_adm1_edge_list.csv +8291 -0
  9. metacouplingllm/data/telecoupling_literature.bib +3498 -0
  10. metacouplingllm/knowledge/__init__.py +1 -0
  11. metacouplingllm/knowledge/adm1_pericoupling.py +591 -0
  12. metacouplingllm/knowledge/citations.py +109 -0
  13. metacouplingllm/knowledge/countries.py +557 -0
  14. metacouplingllm/knowledge/examples.py +713 -0
  15. metacouplingllm/knowledge/framework.py +717 -0
  16. metacouplingllm/knowledge/literature.py +518 -0
  17. metacouplingllm/knowledge/pericoupling.py +241 -0
  18. metacouplingllm/knowledge/rag.py +1791 -0
  19. metacouplingllm/knowledge/references.py +112 -0
  20. metacouplingllm/knowledge/websearch.py +1842 -0
  21. metacouplingllm/llm/__init__.py +1 -0
  22. metacouplingllm/llm/client.py +636 -0
  23. metacouplingllm/llm/parser.py +868 -0
  24. metacouplingllm/output/__init__.py +1 -0
  25. metacouplingllm/output/formatter.py +276 -0
  26. metacouplingllm/prompts/__init__.py +1 -0
  27. metacouplingllm/prompts/builder.py +477 -0
  28. metacouplingllm/prompts/templates.py +556 -0
  29. metacouplingllm/visualization/__init__.py +114 -0
  30. metacouplingllm/visualization/adm1_map.py +884 -0
  31. metacouplingllm/visualization/worldmap.py +1372 -0
  32. metacouplingllm-0.1.0.dist-info/METADATA +440 -0
  33. metacouplingllm-0.1.0.dist-info/RECORD +35 -0
  34. metacouplingllm-0.1.0.dist-info/WHEEL +4 -0
  35. 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
+ )