Coverage for src/keel/providers.py: 100%

227 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 19:17 +0000

1"""The provider vocabulary keel can dispatch to — pure data model + registry (#1011). 

2 

3keel advertises agent CLIs, hosted APIs, OpenAI-compatible endpoints, generic CLI 

4profiles and local Ollama models as delegates, but nothing in core could tell an 

5operator *which* of those are usable on this machine. This module owns the pure half 

6of that answer: the :class:`Provider` record, the machine-level **provider registry** 

7(``~/.keel/providers.yaml``), the name-clash rules, and :func:`plan_probes`, which 

8lists what a probe should look at. The probing itself — subprocess, PATH, HTTP — is 

9thin I/O in :mod:`keel.providerprobe`. 

10 

11Three sources feed one list, in this precedence: 

12 

13``profile`` a project ``knobs.delegate_profiles`` entry (checked into the repo); 

14``registry`` a machine-level entry the operator owns and never commits; 

15``builtin`` a vendor keel understands with no configuration at all. 

16 

17Which providers are usable is a property of the **machine and the person**, not of 

18the project — one operator has ``claude``/``codex``/``agy`` logged in and no API key, 

19another has only ``XAI_API_KEY``. The registry is where those facts live so they do 

20not have to be committed to ``project.yaml``. 

21 

22Name resolution is fail-closed and mirrors the existing built-in shadowing rule 

23(:func:`keel.config._validate_delegate_profiles`): a registry entry may not take the 

24name of a built-in vendor or of a project profile. The project profile keeps working 

25and **wins**; the clash is reported as a validation error naming both sources. 

26 

27Pure and deterministic: no wall-clock, no randomness, no subprocess, no network. The 

28one file read is :func:`load_registry`, whose reader is injectable. 

29""" 

30 

31from __future__ import annotations 

32 

33import os 

34from collections.abc import Callable, Iterable, Mapping 

35from dataclasses import dataclass, field 

36from pathlib import Path 

37from typing import Any 

38 

39from . import agents 

40from . import config as cfg 

41from . import yaml_helper as yaml 

42from .api_delegate import OPENAI_COMPATIBLE, env_key_name 

43 

44#: Env var naming an alternative registry file; otherwise ``~/.keel/providers.yaml``. 

45REGISTRY_ENV = "KEEL_PROVIDERS" 

46 

47#: Path of the default registry, relative to the operator's home directory. 

48DEFAULT_REGISTRY_RELPATH = (".keel", "providers.yaml") 

49 

50#: Transports a provider can be reached over. ``cli`` is a local coding-agent binary, 

51#: ``api`` a hosted HTTP endpoint keyed by an env var, ``local`` a model served on the 

52#: operator's own hardware. 

53TRANSPORTS = ("cli", "api", "local") 

54 

55#: Documented read-only flag per built-in CLI vendor. Presence here is what 

56#: ``read_only_mode`` reports: keel cannot *enforce* read-only for an arbitrary CLI, 

57#: so the capability says "a documented flag exists", never "writes are impossible". 

58READ_ONLY_FLAGS: dict[str, str] = { 

59 "claude": "--disallowed-tools", 

60 "codex": "-s read-only", 

61 "agy": "--sandbox", 

62} 

63 

64#: The flag every built-in CLI vendor spells model selection with. 

65DEFAULT_MODEL_ARG = "--model" 

66 

67#: Ollama's local tag listing. A **hardcoded loopback constant**, like every other URL 

68#: keel dials: the probe never reaches an endpoint named by config or by the registry, 

69#: which is what keeps the SSRF story of this module trivial. 

70OLLAMA_TAGS_URL = "http://127.0.0.1:11434/api/tags" 

71 

72#: The command that serves the built-in ``ollama`` local vendor. 

73OLLAMA_COMMAND = "ollama" 

74 

75#: Distinct review vendors a cross-vendor review panel needs. Two vendors reviewing is 

76#: the property `review-vendors` reports; one vendor twice is one opinion twice. 

77REVIEW_VENDOR_MINIMUM = 2 

78 

79#: Characters an environment variable *name* may contain. 

80_ENV_NAME_OK = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_") 

81 

82#: Registry keys a provider entry may carry. Anything else is ignored (fail-soft) — 

83#: an unknown key is far more likely a typo in a hand-written file than an intent. 

84_ENTRY_KEYS = frozenset( 

85 { 

86 "transport", 

87 "command", 

88 "endpoint", 

89 "api_key_env", 

90 "model", 

91 "model_arg", 

92 "effort", 

93 "args", 

94 "review_args", 

95 "vendor_label", 

96 } 

97) 

98 

99 

100@dataclass(frozen=True) 

101class Provider: 

102 """One provider keel could dispatch to, from any of the three sources.""" 

103 

104 name: str 

105 #: The delegate vendor recorded in attribution: a built-in vendor name 

106 #: (``claude``/``anthropic-api``/…), or ``cli``/``openai-compatible``/``local`` 

107 #: for a profile or registry entry. 

108 vendor: str 

109 transport: str 

110 command: str | None = None 

111 endpoint: str | None = None 

112 #: The **name** of the env var holding the key — never the key. 

113 api_key_env: str | None = None 

114 model: str | None = None 

115 #: Vendor-specific reasoning-effort selector, carried through for dispatch (#1012). 

116 effort: str | None = None 

117 #: Flags that make this provider a reviewer rather than an implementer. Their 

118 #: presence is what ``read_only_mode`` reports for a profile/registry entry. 

119 review_args: tuple[str, ...] = () 

120 #: Flags the implementer (write) role runs with, e.g. ``--trust`` for a current 

121 #: ``cursor-agent``. Registry entries only (#1508). Reviewers use ``review_args`` 

122 #: instead; ``args`` is never a fallback for review, because these are the write flags. 

123 args: tuple[str, ...] = () 

124 #: ``builtin`` | ``profile`` | ``registry``. 

125 source: str = "builtin" 

126 #: How a model reaches a CLI (``<model_arg> <model>``); ``None`` when the provider 

127 #: exposes no model selection. 

128 model_arg: str | None = None 

129 #: What ``agent:<vendor>`` should say for a profile or registry entry whose 

130 #: :attr:`vendor` is the transport (``cli``) rather than the model's maker (#1129). 

131 #: ``None`` — the default and the state of every built-in — leaves the label alone. 

132 vendor_label: str | None = None 

133 

134 def label_vendor(self) -> str: 

135 """The vendor this provider's attribution names: ``vendor_label`` when set. 

136 

137 Built-ins never set it, so they keep naming themselves. A ``cli`` entry that 

138 does set it stops sharing one ``agent:cli`` with every other ``cli`` entry — 

139 which is what ``review-vendor-distinctness`` needs in order to tell two 

140 reviewers apart. 

141 """ 

142 return self.vendor_label or self.vendor 

143 

144 def capabilities(self) -> dict[str, bool]: 

145 """What this provider can do — the three facts a dispatcher needs. 

146 

147 ``tools``: can it run git/PR steps itself? Only a CLI can; an ``api`` or 

148 ``local`` provider generates text under keel's no-tools contract, where the 

149 orchestrator performs every mutation. 

150 

151 ``read_only_mode``: is there a documented way to run it without write tools? 

152 A built-in CLI has a flag (:data:`READ_ONLY_FLAGS`); a profile or registry 

153 entry has it when the operator set ``review_args``. A provider with no tools 

154 at all has no such flag, and reports ``False`` — read ``tools`` first. 

155 

156 ``model_selection``: can the caller choose the model? 

157 """ 

158 return { 

159 "tools": self.transport == "cli", 

160 "read_only_mode": self._read_only_mode(), 

161 "model_selection": self.transport in ("api", "local") 

162 or bool(self.model_arg or self.model), 

163 } 

164 

165 def _read_only_mode(self) -> bool: 

166 if self.source == "builtin": 

167 return self.name in READ_ONLY_FLAGS 

168 return bool(self.review_args) 

169 

170 def as_dict(self) -> dict[str, object]: 

171 """JSON-stable record (no secrets: ``api_key_env`` is a name, never a value).""" 

172 return { 

173 "name": self.name, 

174 "vendor": self.vendor, 

175 "transport": self.transport, 

176 "source": self.source, 

177 "command": self.command, 

178 "endpoint": self.endpoint, 

179 "api_key_env": self.api_key_env, 

180 "model": self.model, 

181 "effort": self.effort, 

182 "args": list(self.args), 

183 "review_args": list(self.review_args), 

184 "capabilities": self.capabilities(), 

185 } 

186 

187 

188@dataclass(frozen=True) 

189class Registry: 

190 """The machine-level provider registry, already parsed and fail-soft.""" 

191 

192 path: str 

193 present: bool = False 

194 providers: tuple[Provider, ...] = () 

195 #: Fail-soft parse complaints. A malformed registry never raises: keel degrades to 

196 #: the built-ins and says why. 

197 warnings: tuple[str, ...] = field(default_factory=tuple) 

198 

199 def names(self) -> tuple[str, ...]: 

200 return tuple(provider.name for provider in self.providers) 

201 

202 

203def registry_path(*, env: Mapping[str, str] | None = None, home: str | Path | None = None) -> Path: 

204 """Where the registry lives: ``$KEEL_PROVIDERS``, else ``~/.keel/providers.yaml``. 

205 

206 ``home`` is resolved from the **injected** environment before ``Path.home()`` so a 

207 test can place a registry without touching the real ``$HOME`` — and so an operator 

208 who moved ``HOME`` gets the registry their other tools see. 

209 """ 

210 env = os.environ if env is None else env 

211 override = (env.get(REGISTRY_ENV) or "").strip() 

212 if override: 

213 return Path(override).expanduser() 

214 if home is None: 

215 home = env.get("HOME") or None 

216 base = Path(home).expanduser() if home is not None else Path.home() 

217 return base.joinpath(*DEFAULT_REGISTRY_RELPATH) 

218 

219 

220def _read_text(path: Path) -> str: 

221 return path.read_text(encoding="utf-8") 

222 

223 

224def load_registry( 

225 path: str | Path | None = None, 

226 *, 

227 env: Mapping[str, str] | None = None, 

228 _read: Callable[[Path], str] = _read_text, 

229) -> Registry: 

230 """Load and parse the registry. **Never raises** — every failure is a warning. 

231 

232 A missing file is not a failure: no registry means no machine-level providers, 

233 which is the state of every machine that has not opted in. 

234 """ 

235 env = os.environ if env is None else env 

236 target = Path(path) if path is not None else registry_path(env=env) 

237 try: 

238 text = _read(target) 

239 except FileNotFoundError: 

240 return Registry(path=str(target), present=False) 

241 except OSError as exc: 

242 return Registry( 

243 path=str(target), 

244 present=True, 

245 warnings=(f"{target}: cannot be read ({exc})",), 

246 ) 

247 try: 

248 data = yaml.load(text) 

249 except yaml.YAMLError as exc: 

250 return Registry( 

251 path=str(target), 

252 present=True, 

253 warnings=(f"{target}: is not valid YAML ({exc})",), 

254 ) 

255 return parse_registry(data, path=str(target), env=env) 

256 

257 

258def parse_registry( 

259 data: Any, 

260 *, 

261 path: str, 

262 env: Mapping[str, str] | None = None, 

263) -> Registry: 

264 """Turn a loaded registry document into providers + fail-soft warnings (pure).""" 

265 env = os.environ if env is None else env 

266 if data is None: 

267 return Registry(path=path, present=True) 

268 if not isinstance(data, dict): 

269 return Registry( 

270 path=path, 

271 present=True, 

272 warnings=(f"{path}: expected a mapping with a 'providers:' key",), 

273 ) 

274 entries = data.get("providers") 

275 if entries is None: 

276 return Registry( 

277 path=path, 

278 present=True, 

279 warnings=(f"{path}: has no 'providers:' mapping — nothing to register",), 

280 ) 

281 if not isinstance(entries, dict): 

282 return Registry( 

283 path=path, 

284 present=True, 

285 warnings=(f"{path}: 'providers' must be a mapping of name -> entry",), 

286 ) 

287 providers: list[Provider] = [] 

288 warnings: list[str] = [] 

289 for name in sorted(entries, key=str): 

290 provider, entry_warnings = _parse_entry(name, entries[name], path=path, env=env) 

291 warnings.extend(entry_warnings) 

292 if provider is not None: 

293 providers.append(provider) 

294 return Registry( 

295 path=path, 

296 present=True, 

297 providers=tuple(providers), 

298 warnings=tuple(warnings), 

299 ) 

300 

301 

302def _parse_entry( 

303 name: Any, 

304 entry: Any, 

305 *, 

306 path: str, 

307 env: Mapping[str, str], 

308) -> tuple[Provider | None, list[str]]: 

309 """One registry entry -> a provider, or ``None`` plus the reasons it was skipped.""" 

310 where = f"{path}: provider {name!r}" 

311 if not isinstance(name, str) or not name.strip(): 

312 return None, [ 

313 f"{path}: provider name {name!r} is not a non-empty string — quote the key " 

314 "(YAML reads a bare on/off/yes/no as a boolean and a bare number as an int)" 

315 ] 

316 if ":" in name: 

317 return None, [ 

318 f"{where}: a name may not contain ':' — --delegate splits on the first colon " 

319 "to separate the provider from a per-run model, so this could never be selected" 

320 ] 

321 if not isinstance(entry, dict): 

322 return None, [f"{where}: entry must be a mapping of fields"] 

323 unknown = sorted(set(entry) - _ENTRY_KEYS) 

324 warnings = [f"{where}: ignoring unknown field(s) {', '.join(unknown)}"] if unknown else [] 

325 transport = entry.get("transport") 

326 if transport not in TRANSPORTS: 

327 warnings.append(f"{where}: unknown transport {transport!r}; valid: {', '.join(TRANSPORTS)}") 

328 return None, warnings 

329 review_args, arg_warnings = _string_tuple(entry.get("review_args"), where=where) 

330 warnings.extend(arg_warnings) 

331 impl_args, impl_warnings = _string_tuple(entry.get("args"), where=where, key="args") 

332 warnings.extend(impl_warnings) 

333 # Fail-soft like every other registry rule: a bad label is dropped with a warning 

334 # rather than skipping the whole entry. The provider still works; it just keeps the 

335 # generic label it had before, which is the state this field improves on. 

336 # The **raw** value, not `_text(...)`: `_text` returns None for a bool, an int or a 

337 # list, and `vendor_label_errors(None)` is silence — so exactly the YAML case the 

338 # project-profile validator reports (an unquoted `on:`/`2:` resolving to a bool/int) 

339 # was swallowed here without a warning. Both gate seats found it. 

340 raw_label = entry.get("vendor_label") 

341 label_errors = cfg.vendor_label_errors(raw_label, where=where) 

342 vendor_label = _text(raw_label) 

343 if label_errors: 

344 warnings.extend(f"{message}; ignoring it" for message in label_errors) 

345 vendor_label = None 

346 fields = { 

347 "name": name, 

348 "transport": transport, 

349 "model": _text(entry.get("model")), 

350 "effort": _text(entry.get("effort")), 

351 "review_args": review_args, 

352 "args": impl_args, 

353 "vendor_label": vendor_label, 

354 "source": "registry", 

355 } 

356 if transport == "api": 

357 endpoint = _text(entry.get("endpoint")) 

358 issues = cfg.endpoint_issues(endpoint, where=where, env=env) 

359 remote_gate = any(cfg.ALLOW_REMOTE_ENDPOINT_ENV in issue for issue in issues) 

360 key_env = _text(entry.get("api_key_env")) 

361 issues.extend(_api_key_env_issues(key_env, where=where)) 

362 if issues: 

363 warnings.extend(issues) 

364 if remote_gate: 

365 # Say it in the registry's own voice. The endpoint rules are the 

366 # project profile's, and their message says "not in this file" — which 

367 # in a home-directory registry reads as though some *other* file could 

368 # grant it. None can: the opt-in is environment-only precisely because 

369 # a file must not be able to widen its own reach. 

370 warnings.append( 

371 f"{where}: not registered. Reaching your own remote endpoint needs " 

372 f"{cfg.ALLOW_REMOTE_ENDPOINT_ENV}=1 exported in your shell — no " 

373 "registry entry can grant itself that" 

374 ) 

375 return None, warnings 

376 return ( 

377 Provider(vendor=OPENAI_COMPATIBLE, endpoint=endpoint, api_key_env=key_env, **fields), 

378 warnings, 

379 ) 

380 command = _text(entry.get("command")) 

381 if not command: 

382 warnings.append( 

383 f"{where}: transport {transport!r} requires a non-empty 'command' — the " 

384 "executable keel runs" 

385 ) 

386 return None, warnings 

387 vendor = "cli" if transport == "cli" else "local" 

388 model_arg = _text(entry.get("model_arg")) or (DEFAULT_MODEL_ARG if transport == "cli" else None) 

389 return Provider(vendor=vendor, command=command, model_arg=model_arg, **fields), warnings 

390 

391 

392def _api_key_env_issues(key_env: str | None, *, where: str) -> list[str]: 

393 """Rules for the **name** of a registry entry's API-key env var. 

394 

395 The denylist is shared with ``knobs.delegate_profiles``: a high-privilege system 

396 credential (``GITHUB_TOKEN``, ``AWS_*``, ``SSH_AUTH_SOCK``, …) may never become an 

397 ``Authorization`` header, wherever the entry was written. 

398 

399 The project profile's *allowlist* is deliberately **not** applied here. That list 

400 exists because ``project.yaml`` is committed and reviewed by people other than its 

401 author — the threat model is a config an attacker influenced through a pull 

402 request. This file is not committed and not shared: it sits in the operator's own 

403 home directory at the same trust level as their shell profile, and #1011's own 

404 example (an operator whose only key is ``XAI_API_KEY``) is exactly the case an 

405 allowlist of seven vendor names would refuse. The probe reads presence only — it 

406 never reads the value, and never sends it anywhere. 

407 """ 

408 if not key_env: 

409 return [ 

410 f"{where}: transport 'api' requires 'api_key_env' — the *name* of the " 

411 "environment variable holding the key, never the key itself" 

412 ] 

413 if not _ENV_NAME_OK.issuperset(key_env) or key_env[0].isdigit(): 

414 return [ 

415 f"{where}: api_key_env {key_env!r} is not a valid environment variable name " 

416 "(letters, digits, underscore; not starting with a digit) — this field takes " 

417 "a name, not a key" 

418 ] 

419 if key_env.upper() in cfg.BLOCKED_ENV_KEY_NAMES or key_env.upper().startswith( 

420 cfg.BLOCKED_ENV_PREFIXES 

421 ): 

422 return [ 

423 f"{where}: api_key_env {key_env!r} names a high-privilege system credential " 

424 "and may not be used as a provider key" 

425 ] 

426 return [] 

427 

428 

429def _text(value: Any) -> str | None: 

430 """A non-blank string, or ``None`` (so a blank field reads as unset).""" 

431 return value.strip() if isinstance(value, str) and value.strip() else None 

432 

433 

434def _string_tuple( 

435 value: Any, *, where: str, key: str = "review_args" 

436) -> tuple[tuple[str, ...], list[str]]: 

437 if value is None: 

438 return (), [] 

439 if not isinstance(value, list) or not all(isinstance(item, str) for item in value): 

440 return (), [f"{where}: '{key}' must be a list of strings — ignored"] 

441 return tuple(value), [] 

442 

443 

444def builtin_providers() -> tuple[Provider, ...]: 

445 """Every vendor keel understands with no configuration at all.""" 

446 providers = [ 

447 Provider( 

448 name=vendor, 

449 vendor=vendor, 

450 transport="cli", 

451 command=vendor, 

452 model_arg=DEFAULT_MODEL_ARG, 

453 source="builtin", 

454 ) 

455 for vendor in agents.CLI_VENDORS 

456 ] 

457 providers.extend( 

458 Provider( 

459 name=vendor, 

460 vendor=vendor, 

461 transport="local", 

462 command=OLLAMA_COMMAND, 

463 endpoint=OLLAMA_TAGS_URL, 

464 source="builtin", 

465 ) 

466 for vendor in agents.LOCAL_VENDORS 

467 ) 

468 providers.extend( 

469 Provider( 

470 name=vendor, 

471 vendor=vendor, 

472 transport="api", 

473 api_key_env=env_key_name(vendor), 

474 source="builtin", 

475 ) 

476 for vendor in agents.API_VENDORS 

477 ) 

478 return tuple(providers) 

479 

480 

481def profile_providers(config) -> tuple[Provider, ...]: 

482 """Providers from a project's ``knobs.delegate_profiles`` (empty when no config).""" 

483 if config is None: 

484 return () 

485 providers = [] 

486 for name in sorted(config.knobs.delegate_profiles): 

487 profile = config.knobs.delegate_profiles[name] 

488 api = profile.vendor == OPENAI_COMPATIBLE 

489 providers.append( 

490 Provider( 

491 name=name, 

492 vendor=profile.vendor, 

493 transport="api" if api else "cli", 

494 command=profile.command, 

495 endpoint=profile.endpoint, 

496 api_key_env=profile.api_key_env, 

497 model=profile.model, 

498 review_args=profile.role_args(review=True) if profile.review_args else (), 

499 args=tuple(profile.args or ()), 

500 source="profile", 

501 model_arg=None if api else (profile.model_arg or None), 

502 vendor_label=profile.vendor_label, 

503 ) 

504 ) 

505 return tuple(providers) 

506 

507 

508def registry_clashes(registry: Registry, config) -> list[str]: 

509 """Name clashes between the registry and the built-ins / this project's profiles. 

510 

511 A registry entry may not shadow either. The message names **both** sources, so an 

512 operator editing a file in ``$HOME`` learns which repository file it collided with 

513 rather than being told its own name is taken. 

514 """ 

515 builtins = agents.BUILTIN_DELEGATE_VENDORS 

516 profiles = {} if config is None else config.knobs.delegate_profiles 

517 errors: list[str] = [] 

518 for name in registry.names(): 

519 if name in builtins: 

520 errors.append( 

521 f"{registry.path}: provider {name!r} shadows the built-in delegate vendor " 

522 f"{name!r}; built-ins always win and may not be redefined " 

523 f"({', '.join(builtins)}) — rename the registry entry" 

524 ) 

525 elif name in profiles: 

526 errors.append( 

527 f"{registry.path}: provider {name!r} clashes with the project profile " 

528 f"knobs.delegate_profiles.{name}; the project profile wins — rename the " 

529 "registry entry" 

530 ) 

531 return errors 

532 

533 

534def plan_probes(config, registry: Registry | None = None) -> tuple[Provider, ...]: 

535 """Everything a probe should look at, in a deterministic order. 

536 

537 Built-ins first (dispatch order: CLI, local, hosted API), then this project's 

538 profiles, then the machine-level registry. A registry entry whose name clashes is 

539 **dropped** here rather than silently overriding: precedence is 

540 *built-in > project profile > registry*, and :func:`registry_clashes` reports the 

541 clash so the operator sees why the entry is missing. That is the same order 

542 :func:`keel.delegate.resolve_provider` dispatches on, and the same invariant 

543 :func:`keel.agents.resolve_delegate_profile` states — a built-in vendor always wins 

544 and may not be redefined, by a committed profile or by a file in ``$HOME``. Below the 

545 built-ins the project's own profiles win over the machine-level registry, so a 

546 repository can pin the provider its team shares. 

547 """ 

548 registry = Registry(path="") if registry is None else registry 

549 providers = list(builtin_providers()) 

550 profiles = profile_providers(config) 

551 providers.extend(profiles) 

552 taken = {provider.name for provider in providers} 

553 providers.extend(provider for provider in registry.providers if provider.name not in taken) 

554 return tuple(providers) 

555 

556 

557def tool_capable(providers: Iterable[Provider]) -> tuple[str, ...]: 

558 """Names of the providers that can run tools (i.e. drive git/PR steps themselves).""" 

559 return tuple(p.name for p in providers if p.capabilities()["tools"]) 

560 

561 

562def distinct_vendors(providers: Iterable[Provider]) -> tuple[str, ...]: 

563 """Distinct vendors across ``providers``, in first-seen order. 

564 

565 A review panel's independence is a property of *vendors*, not of provider entries: 

566 two profiles that both shell out to the same CLI are one vendor, and one opinion. 

567 """ 

568 return tuple(dict.fromkeys(p.vendor for p in providers)) 

569 

570 

571#: Characters a listed model id may contain. Wider than 

572#: :data:`keel.agents._MODEL_TOKEN_OK` on purpose — this parses a *listing* keel only 

573#: displays (``qwen2.5:7b``, ``anthropic/claude-opus-4-5``), and a token from here is 

574#: still re-validated by ``agents.is_safe_model_token`` before it can reach an argv. 

575_LISTED_MODEL_OK = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._:-/") 

576 

577#: Cap on a parsed model listing. A CLI that decides to print its whole catalogue 

578#: (or something that is not a listing at all) must not turn a doctor row into a wall. 

579MAX_LISTED_MODELS = 100 

580 

581 

582def parse_model_lines(text: str) -> tuple[str, ...]: 

583 """Best-effort model ids out of a CLI listing (``agy models``). 

584 

585 No agent CLI promises a machine-readable listing, so this reads the shape they all 

586 share — one model per line, possibly bulleted, possibly followed by columns of 

587 description — and keeps the first token of each line that could be a model id. 

588 Headers, rules and prose lines drop out because they carry characters no model id 

589 has. Pure, deterministic, and never raises: an unreadable listing yields ``()``, 

590 which reads as "this provider exposes no model list", not as an error. 

591 """ 

592 seen: dict[str, None] = {} 

593 for raw in (text or "").splitlines(): 

594 line = raw.strip() 

595 if not line or line.startswith("#") or line.endswith(":"): 

596 continue 

597 line = line.lstrip("-*\u2022 \t") 

598 if not line: 

599 continue 

600 token = line.split()[0] 

601 if not _LISTED_MODEL_OK.issuperset(token) or not any(c.isalnum() for c in token): 

602 continue 

603 seen.setdefault(token, None) 

604 if len(seen) >= MAX_LISTED_MODELS: 

605 break 

606 return tuple(seen) 

607 

608 

609def parse_tag_payload(data: Any) -> tuple[str, ...]: 

610 """Model names out of an Ollama ``/api/tags`` payload (``()`` when malformed).""" 

611 if not isinstance(data, dict): 

612 return () 

613 models = data.get("models") 

614 if not isinstance(models, list): 

615 return () 

616 names: dict[str, None] = {} 

617 for entry in models: 

618 if not isinstance(entry, dict): 

619 continue 

620 name = entry.get("name") or entry.get("model") 

621 if isinstance(name, str) and name.strip(): 

622 names.setdefault(name.strip(), None) 

623 if len(names) >= MAX_LISTED_MODELS: 

624 break 

625 return tuple(names)