EvoScientist-Multi/EvoScientist/llm

Model Runtime Layout

The model runtime has three configuration and execution boundaries.

Layer	Source	Owns	Must not own
Provider	configuration/provider.py	Adapter identity, credentials, endpoints, headers, connection defaults	Model capabilities, model token limits, derived tool transport
Model	configuration/model.py	Provider model ID, capabilities, limits, canonical parameters, access, billing	Credentials, base URL, SDK client options, derived tool transport
Invocation	invocation/contract.py	Immutable API mode, output parameter, tool transport, streaming flag, final SDK parameters	Admin persistence, credentials, routing decisions

Supporting modules have narrower responsibilities:

• model_config_v4.py normalizes and persists the Provider + ModelProfile admin contract, then projects it to the stable runtime schema.
• model_config.py parses and validates the runtime schema. It re-exports the provider and model contracts for compatibility with existing integrations.
• adapter_registry.py declares provider/model-family support and converts canonical model parameters into provider SDK parameters.
• runtime.py selects a frozen route, asks its adapter to compile parameters, compiles an InvocationPlan, and constructs the provider client from that plan only.

The call chain is fixed:

V4 Provider + ModelProfile
  -> normalize and validate
  -> V3 runtime projection
  -> select provider endpoint and model profile
  -> merge canonical model parameters
  -> provider adapter compilation
  -> immutable InvocationPlan validation
  -> provider SDK call

Important invariants:

1. Environment variables may provide secrets, proxy settings, and timeouts; they cannot select an API protocol or rewrite a compiled invocation.
2. tool_call_transport is not administrator configuration. It is derived as native when capabilities.tools=true, otherwise disabled.
3. Exactly one provider output-limit parameter is allowed in a compiled plan: max_output_tokens, max_completion_tokens, or max_tokens.
4. Provider-specific parameter names are selected by the adapter. Gateway, frontend, and generic runtime code must not guess them from model names.
5. Runtime logs report the final non-secret plan and parameter names. They must never include credentials, authorization headers, or raw secret values.
6. Provider input projection removes assistant history that has neither final text nor a tool call. A newly completed empty response receives one bounded same-route repair attempt, then fails as MODEL_PROVIDER_RESPONSE_INVALID.