Repository navigation
Expand file tree
/
Copy pathllm_utils.py
More file actions
278 lines (224 loc) · 10.7 KB
/
Copy pathllm_utils.py
File metadata and controls
278 lines (224 loc) · 10.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Shared LLM utilities (OpenAI-compatible chat models + agent CLI transports).
Credentials are resolved in this order:
1. The active provider (see :mod:`skillspector.providers`):
- CLI providers (``claude_cli``, ``codex_cli``, ``gemini_cli``): use
``is_available()`` and ``complete()`` — no API key needed.
- HTTP providers (``anthropic``, ``openai``, ``nv_build``): read their
respective credential env vars and supply a base URL.
2. ``OPENAI_API_KEY`` / ``OPENAI_BASE_URL`` (the langchain-openai
defaults) — only consulted for HTTP providers when the provider's
own credential env var is unset.
There is no SkillSpector-specific credential env var: setting
``NVIDIA_INFERENCE_KEY`` configures whichever NVIDIA endpoint the
deployment ships with, Anthropic reads ``ANTHROPIC_API_KEY``, and any
other OpenAI-compatible endpoint is configured via the standard
``OPENAI_*`` envs.
"""
from __future__ import annotations
import asyncio
import json
from typing import NoReturn
from langchain_core.language_models.chat_models import BaseChatModel
from skillspector.model_info import get_max_input_tokens, get_max_output_tokens
from skillspector.providers import (
create_chat_model,
get_active_provider,
get_metadata_provider,
has_cli_capability,
raise_no_llm_api_key_configured,
resolve_chat_model_credentials,
resolve_provider_credentials,
)
from skillspector.providers.openai import OpenAIProvider
def _resolve_llm_credentials() -> tuple[str, str | None]:
"""Return ``(api_key, base_url)`` resolved from the environment.
Tries the active SkillSpector provider first; falls back to
``OPENAI_API_KEY`` / ``OPENAI_BASE_URL`` when the provider is not
configured.
Raises:
ValueError: when no API key can be resolved from any source.
"""
creds = resolve_chat_model_credentials()
if creds is None:
raise_no_llm_api_key_configured()
return creds
def _resolve_default_chat_model() -> str:
"""Return the default chat model for the endpoint that will be used."""
if resolve_provider_credentials() is not None:
return get_metadata_provider().resolve_model()
openai_provider = OpenAIProvider()
if openai_provider.resolve_credentials() is not None:
return openai_provider.resolve_model()
raise_no_llm_api_key_configured()
def is_llm_available() -> tuple[bool, str | None]:
"""Return ``(available, error_message)`` describing LLM availability.
For CLI providers (``claude_cli``, ``codex_cli``, ``gemini_cli``) the check
delegates to the provider's ``is_available()`` method (binary on PATH +
auth). For HTTP providers, it falls back to credential resolution.
"""
provider = get_active_provider()
if has_cli_capability(provider):
return provider.is_available() # type: ignore[attr-defined]
try:
_resolve_llm_credentials()
except ValueError as exc:
return False, str(exc)
return True, None
def fetch_model_token_limits(model_label: str) -> tuple[int, int]:
"""Return ``(max_input_tokens, max_output_tokens)`` for *model_label*."""
return get_max_input_tokens(model_label), get_max_output_tokens(model_label)
# ---------------------------------------------------------------------------
# Agent CLI chat-model adapter
# ---------------------------------------------------------------------------
#
# The LLM analyzers (meta_analyzer, semantic_*) obtain a model from
# ``get_chat_model()`` and call ``.invoke()`` / ``.with_structured_output(
# schema).invoke()`` on it (see ``llm_analyzer_base``) — they never go through
# ``chat_completion``. To support CLI providers there, ``get_chat_model``
# returns this minimal adapter, which mimics the slice of the ``ChatOpenAI``
# interface the analyzers rely on, backed by the provider's ``complete()``
# subprocess transport.
class _AgentCLIMessage:
"""Minimal stand-in for a LangChain message: exposes ``.content``."""
def __init__(self, content: str) -> None:
self.content = content
def _extract_json_object(raw: str) -> dict:
"""Extract a single JSON object from a CLI model's text response.
Tolerates markdown code fences and surrounding prose. Raises ``ValueError``
(fail-closed) when no JSON object can be parsed.
"""
text = raw.strip()
if text.startswith("```"):
# Drop the opening fence line (``` or ```json) and any closing fence.
text = text.split("\n", 1)[1] if "\n" in text else ""
fence = text.rfind("```")
if fence != -1:
text = text[:fence]
text = text.strip()
try:
obj = json.loads(text)
if isinstance(obj, dict):
return obj
except json.JSONDecodeError:
pass
start, end = text.find("{"), text.rfind("}")
if start != -1 and end > start:
try:
obj = json.loads(text[start : end + 1])
if isinstance(obj, dict):
return obj
except json.JSONDecodeError:
pass
raise ValueError(f"could not extract a JSON object from CLI response: {raw[:200]!r}")
class _StructuredAgentCLIModel:
"""Mimics ``ChatOpenAI.with_structured_output(schema)`` for a CLI provider.
``invoke`` augments the prompt with the schema, calls the provider's
``complete()``, then parses and validates the response into *schema*.
"""
def __init__(self, provider: object, model: str, max_output_tokens: int, schema: type) -> None:
self._provider = provider
self._model = model
self._max_output_tokens = max_output_tokens
self._schema = schema
def _augment(self, prompt: str) -> str:
schema_json = json.dumps(self._schema.model_json_schema(), indent=2)
return (
f"{prompt}\n\n"
"Respond with ONLY a single JSON object conforming to the JSON Schema "
"below. Do not wrap it in markdown code fences and do not add any prose "
f"before or after the JSON.\n\nJSON Schema:\n{schema_json}"
)
def invoke(self, prompt: str) -> object:
raw = self._provider.complete( # type: ignore[attr-defined]
self._augment(prompt),
model=self._model,
max_output_tokens=self._max_output_tokens,
)
return self._schema.model_validate(_extract_json_object(raw))
async def ainvoke(self, prompt: str) -> object:
return await asyncio.to_thread(self.invoke, prompt)
class AgentCLIChatModel:
"""Minimal ``ChatOpenAI``-compatible adapter backed by a CLI provider.
Implements only the surface the analyzers use: ``invoke`` (returns an
object with ``.content``), ``ainvoke``, and ``with_structured_output``.
The rest of the ``BaseChatModel`` surface (``batch``, ``stream``,
callbacks) is intentionally unsupported; the stubs below make that boundary
explicit so a future analyzer reaching for it fails loudly with a clear
message rather than a confusing ``AttributeError``.
"""
def __init__(self, provider: object, model: str, max_output_tokens: int) -> None:
self._provider = provider
self._model = model
self._max_output_tokens = max_output_tokens
def batch(self, *args: object, **kwargs: object) -> NoReturn:
raise NotImplementedError(
"AgentCLIChatModel supports only invoke/ainvoke/with_structured_output; "
"batch() is not available for CLI providers."
)
def stream(self, *args: object, **kwargs: object) -> NoReturn:
raise NotImplementedError(
"AgentCLIChatModel supports only invoke/ainvoke/with_structured_output; "
"stream() is not available for CLI providers."
)
def invoke(self, prompt: str) -> _AgentCLIMessage:
text = self._provider.complete( # type: ignore[attr-defined]
prompt,
model=self._model,
max_output_tokens=self._max_output_tokens,
)
return _AgentCLIMessage(text)
async def ainvoke(self, prompt: str) -> _AgentCLIMessage:
return await asyncio.to_thread(self.invoke, prompt)
def with_structured_output(self, schema: type) -> _StructuredAgentCLIModel:
return _StructuredAgentCLIModel(
self._provider, self._model, self._max_output_tokens, schema
)
def get_chat_model(model: str | None = None) -> BaseChatModel | AgentCLIChatModel:
"""Return a chat model for the active provider.
For CLI providers (``claude_cli``, ``codex_cli``, ``gemini_cli``) this
returns an :class:`AgentCLIChatModel` adapter backed by the provider's
``complete()`` subprocess transport — so the LLM analyzers (which use
``.invoke()`` and ``.with_structured_output()``) work with no API key.
For HTTP providers it delegates to
:func:`skillspector.providers.create_chat_model`, which uses the
provider's own native client (e.g. ``ChatAnthropic`` for Anthropic) with
an ``OPENAI_API_KEY`` / ``ChatOpenAI`` fallback.
Raises:
ValueError: when an HTTP provider has no API key configured.
"""
provider = get_active_provider()
if has_cli_capability(provider):
resolved_model = model or provider.resolve_model()
return AgentCLIChatModel(provider, resolved_model, get_max_output_tokens(resolved_model))
model = model or _resolve_default_chat_model()
return create_chat_model(
model=model,
max_tokens=get_max_output_tokens(model),
timeout=120,
)
def chat_completion(prompt: str, *, model: str | None = None) -> str:
"""Request a single chat completion and return the assistant content.
Routes through :func:`get_chat_model`, which dispatches to the CLI adapter
for CLI providers and to the provider's native chat model for HTTP providers.
Uses ``.text`` when available (real LangChain ``BaseMessage`` objects,
which normalise content blocks to a single string) and falls back to
``.content`` for the CLI adapter's ``_AgentCLIMessage``.
"""
response = get_chat_model(model=model).invoke(prompt)
if hasattr(response, "text"):
return response.text # type: ignore[union-attr]
return response.content or "" # type: ignore[union-attr]