߲jNdZddlmZddlZddlmZmZddlmZm Z m Z erddl m Z ejeZeZd dZeGdd Zy) uProvider profile base class. A ProviderProfile declares everything about an inference provider in one place: auth, endpoints, client quirks, request-time quirks. The transport reads this instead of receiving 20+ boolean flags. Provider profiles are DECLARATIVE — they describe the provider's behavior. They do NOT own client construction, credential rotation, or streaming. Those stay on AIAgent. ) annotationsN) dataclassfield) TYPE_CHECKINGAnyCallable)AccountUsageSnapshotc8 ddlm}d|S#t$rYywxYw)uReturn a ``hermes-cli/`` UA string, with a stable fallback. Used by ``ProviderProfile.fetch_models`` so the catalog probe is not served the default ``Python-urllib/`` UA — some providers (OpenCode Zen, etc.) sit behind a WAF that returns 403 for that. r) __version__z hermes-cli/z hermes-cli) hermes_clir Exception)_vers 3/home/ubuntu/.hermes/hermes-agent/providers/base.py_profile_user_agentrs)2TF## s ceZdZUdZded<dZded<dZded<d Zded <d Zded <d Z ded <dZ ded <d Z ded<d Z ded<dZ ded<dZded<dZded<dZded<dZded<dZded<dZded<dZded<dZded <dZd!ed"<d Zded#<dZded$<dZded%<d Zded&<dZded'<ee(Zd)ed*<d Zded+<ee(Z d,ed-<dZ!d.ed/<dZ"d0ed1<dZ#ded2<d Z$ded3<ee(Z%d4ed5<ddd6 dMd7Z&dd8dNd9Z'dOd:Z(dPd;Z)dd< dQd=Z*dRdSd>Z+dd? dTd@Z,dUdAZ-dVdBZ.dWdCZ/dXdDZ0dYdEZ1 dZdFZ2d[dGZ3d\dHZ4d]dIZ5dddJdK d^dLZ6y)_ProviderProfileuABase provider profile — subclass or instantiate with overrides.strnamechat_completionsapi_modetuplealiases display_name description signup_urlenv_varsbase_url models_urlapi_key auth_typeTboolsupports_health_checksupports_model_listingNz Callable[[str, Any], Any] | None auth_handlerzCallable[[Any], Any] | Nonerefresh_credentialzCallable[..., Any] | Noneclassify_api_errorFsupports_visionsupports_vision_tool_messagessupports_prompt_cache_key str | Nonenative_reasoning_details_typeprocess_command process_argsprocess_command_env_varsprocess_args_env_varfallback_models)default_factorydict model_aliaseshostnamezdict[str, str]default_headersrfixed_temperature int | Nonedefault_max_tokensunsupported_response_formatsdefault_aux_modelzdict[str, dict[str, Any]]model_capabilities)rr!cy)aoReturn an account-usage snapshot for this provider, if available. The ``/usage`` command invokes this only when no built-in account usage fetcher owns the provider. Implementations may make their provider-specific request and must return an ``AccountUsageSnapshot`` or ``None``; exceptions fail open at the dispatch boundary. Nr)selfrr!s rfetch_account_usagez#ProviderProfile.fetch_account_usages)visioncy)uReturn a LIVE cheap-model id for auxiliary tasks, or "". ``default_aux_model`` is a hardcoded id in source, so it rots: when the provider retires that model every auxiliary call spends a round-trip 404ing before the retry net catches it. Providers that publish a machine-readable recommendation should override this and query it, so the cheap tier tracks the upstream catalog instead of a constant a human has to remember to bump. Contract: cheap to call (implementations must cache — this runs on client-resolution paths), never raises, and returns "" when it has no answer so the caller falls through to ``default_aux_model``. rr)r?rBs rresolve_aux_modelz!ProviderProfile.resolve_aux_modelsrAc|jr |jS|jr&ddlm}||jjxsdSy)uReturn the provider's base hostname for URL-based detection. Uses self.hostname if set explicitly, otherwise derives it from base_url. e.g. 'https://api.gmi-serving.com/v1' → 'api.gmi-serving.com' r)urlparser)r6r urllib.parserF)r?rFs r get_hostnamezProviderProfile.get_hostnames< ==== == -DMM*339r 9rAc|S)zProvider-specific message preprocessing. Called AFTER codex field sanitization, BEFORE developer role swap. Default: pass-through. r)r?messagess rprepare_messagesz ProviderProfile.prepare_messagess rA) session_idc iS)zrProvider-specific extra_body fields. Merged into the API kwargs extra_body. Default: empty dict. r)r?rLcontexts rbuild_extra_bodyz ProviderProfile.build_extra_bodys  rAcy)aReasoning config the main loop sends when ``agent.reasoning_effort`` is unset. None (default) hands the unset state to ``build_api_kwargs_extras`` as ``reasoning_config=None``, where each profile already decides (Nous/OpenRouter fill medium; Anthropic omits). A profile that would otherwise leave the route's own default in charge returns the config here so the agent records it as what went on the wire (the reasoning-rejection ladder reads that). Nrr?models rdefault_reasoning_configz(ProviderProfile.default_reasoning_configsrA)reasoning_configc  iifS)aProvider-specific kwargs split between extra_body and top-level api_kwargs. Returns (extra_body_additions, top_level_kwargs). The transport merges extra_body_additions into extra_body, and top_level_kwargs directly into api_kwargs. This split exists because some providers put reasoning config in extra_body (OpenRouter: extra_body.reasoning) while others put it as top-level api_kwargs (Kimi: api_kwargs.reasoning_effort). Default: ({}, {}). r)r?rTrNs rbuild_api_kwargs_extrasz'ProviderProfile.build_api_kwargs_extrass $2v rAc iS)zProvider-specific OpenAI client keyword arguments. Values are defaults: explicit runtime/custom-provider settings win. The returned mapping must be cheap to build and must not perform I/O. r)r?rNs rbuild_client_kwargs_extrasz*ProviderProfile.build_client_kwargs_extrass  rAcy)uReturn a default vision model id for this provider, or None. Overrideable hook for providers that discover their vision default at runtime (e.g. from a live catalog) rather than pinning one in code. Keeps provider-specific vision discovery inside the provider's plugin instead of a name-check branch in shared vision resolution. Default: None (no provider-specific vision model — the caller falls back to the user's chat model or the aggregator chain). Nr)r?s rdefault_vision_modelz$ProviderProfile.default_vision_modelsrAcy)zJProvider-qualified context bound; explicit user overrides take precedence.NrrQs rget_model_context_lengthz(ProviderProfile.get_model_context_lengthrAcy)zNOptional CostResult from canonical usage; distinguish estimates from invoices.Nr)r?rRusages rget_usage_costzProviderProfile.get_usage_costr]rAc|jS)uReturn the default max_tokens cap for *model*. Overrideable hook for providers that need per-model output caps — e.g. a relay that fronts several upstream backends, each with a different completion-token limit. The transport calls this when the user hasn't set an explicit max_tokens. Default: return self.default_max_tokens (the static profile field), ignoring the model name. Override in a subclass to vary the cap per-model. )r:rQs rget_max_tokenszProviderProfile.get_max_tokens s&&&rAcy)u/Declared reasoning-effort vocabulary for *model* on this provider. Overrideable hook for providers whose gateway validates ``reasoning.effort`` per model instead of ignoring or clamping unknown levels server-side (Ramp Router derives this from its live ``/v1/models`` catalog). The Responses transport consults it before falling back to its built-in per-backend vocabularies; it is the profile-declared analog of the OpenRouter catalog clamp on the chat-completions path (``openrouter_model_reasoning_capabilities``). Tri-state contract: - ``None`` — unknown/undeclared: the transport keeps its default vocabulary for the wire (this base implementation). - ``()`` — the model accepts NO reasoning parameters at all; the transport must omit reasoning fields entirely (some gateways return HTTP 400 rather than ignoring them). - non-empty tuple — clamp the requested effort onto these levels (``agent.reasoning_effort.clamp_effort`` semantics: nearest weaker supported level, never escalate). Implementations are called on the per-request hot path and must not block on network I/O — answer from a cache and return None while cold. NrrQs rsupported_reasoning_effortsz+ProviderProfile.supported_reasoning_effortss6rAc y)uReturn a provider-specific client, or ``None`` for the standard one. Most providers speak OpenAI-compatible HTTP and want the shared ``openai.OpenAI`` client the core builds — they inherit this and return ``None``. A provider whose wire protocol is not HTTP at all (the ACP subprocess shims) or which needs a native SDK overrides this and returns its own client object. ``client_kwargs`` is the same mapping the core would have passed to ``openai.OpenAI`` (``api_key``, ``base_url``, ``command``, ``args``, timeouts, headers…). Unknown keys must be tolerated: the core adds to this mapping over time, so an override should accept ``**kwargs`` and pick what it needs rather than enumerate. Returning ``None`` (the default) is always safe — the caller falls through to its existing construction path. This is the hook that lets a provider ship *outside* this tree: with it, a profile registered from ``~/.hermes/plugins/model-providers/`` or a pip entry point can supply its own transport without any core edit. See ``plugins/model-providers/copilot-acp/`` for the in-tree example. Nr)r? client_kwargss r create_clientzProviderProfile.create_client4s.rAc y)zExternal-process providers: ``{available, logged_in, plan, detail, login_command}`` from the CLI itself so setup can gate on login. ``None`` = nothing to report beyond executable presence.Nrr?kwargss r setup_statuszProviderProfile.setup_statusMrAc y)zExternal-process providers: the account's live picker as ``[{id, label, note}]`` without any inference request; ``None`` falls back to ``fallback_models``.Nrris rdiscover_modelszProviderProfile.discover_modelsRrlrAg @)r!rtimeoutch|jsy|xsdj}|xs |j}t|xr1|j d|jxsdj dk7}|r|j ddz}n7|j xsdj}|s|sy|j ddz}ddl}ddl} ddlm } | jj|} |r| jdd|| jd d | jd t|jjD]\} } | j| |  | | | 5}|j!|j#j%}dddt't(r|n|j+d g}|Dcgc]}t'|t,sd|vs|dc}S#1swYVxYwcc}w#t.$r+}t0j3d|j4|Yd}~yd}~wwxYw)ugFetch the live model list from the provider's models endpoint. Returns a list of model ID strings, or None if the fetch failed or the provider does not support live model listing. Resolution order for the endpoint URL: 1. base_url + "/models", but ONLY when the caller passed a base_url that differs from this profile's default (a user-configured model.base_url pointing at a proxy/custom endpoint). Callers pass base_url unconditionally — falling back to the profile default when the user configured nothing — so equality with self.base_url means "not customised" and must not shadow models_url. 2. self.models_url (explicit override — use when the models endpoint differs from the inference base URL, e.g. OpenRouter exposes a public catalog at /api/v1/models while inference is at /api/v1) 3. self.base_url + "/models" (standard OpenAI-compat fallback) The default implementation sends Bearer auth when api_key is given and forwards self.default_headers. Override to customise auth, path, response shape, or to return None for providers with no REST catalog. Callers must always fall back to the static _PROVIDER_MODELS list when this returns None. Nr/z/modelsr)open_credentialed_url AuthorizationzBearer Acceptzapplication/jsonz User-Agent)rodataidzfetch_models(%s): %s)r%striprr#rstripr jsonurllib.requesthermes_cli.urllib_securityrrrequestRequest add_headerrr7itemsloadsreaddecode isinstancelistgetr4r loggerdebugr)r?r!rro caller_baseeffective_base custom_baseurlryurllibrrreqkvresprurmexcs r fetch_modelszProviderProfile.fetch_modelsWsB**~2,,. $5 ;'   s # (;'C'CC'H H  $$S)I5C??(b//1C%$++C09<Dnn$$S)  NN?ggY,? @ x!34 |%8%:;((..0 !DAq NN1a  ! &sG< 8zz$))+"4"4"67 8&tT2D8LE%*PjD.AdaiAdGP P 8 8Q  LL/C @ sH G=).G,0G=G8G8"G8)G=,G51 G== H1!H,,H1)rr,r!r,returnzAccountUsageSnapshot | None)rBr#rrrr)rJlist[dict[str, Any]]rr)rLr,rNrrdict[str, Any])N)rRr,r dict | None)rTrrNrrz%tuple[dict[str, Any], dict[str, Any]])rNrrr)rr,)rRrrr9)rRrr_rr Any | None)rRr,rr9)rRr,rztuple[str, ...] | None)rfrrr)rjrrzdict[str, Any] | None)rjrrzlist[dict[str, Any]] | None)r!r,rr,rofloatrzlist[str] | None)7__name__ __module__ __qualname____doc____annotations__rrrrrrrr r"r$r%r&r'r(r)r*r+r-r.r/r0r1r2rr4r5r6r7r8r:r;r<r=r@rDrHrKrOrSrVrXrZr\r`rbrdrgrkrnrrrArrr)sK I&Hc&GUL#KJHeHcJIs"&4&#'D'6:L296:3:4818"OT!+/!4. ',t+ 15!:4OSL%&(e( "#"  OU 5M45Hc',D&AO^A"s!%) )*, %, s5:$4O1O )-D % 7A  $ 38 +/';> )-&  / (  ' :2 ## HH H  H  HrArr)r __future__rlogging dataclassesrrtypingrrragent.account_usager getLoggerrrobjectOMIT_TEMPERATURErrrrArrs^ #(//8   8 $8  uu urA