Spec 003: model configuration, and why the quirks must not be configured

[adamjohnwright]

Answers a question asked directly: switching models needs "something to configure it with". Half right — and the wrong half is the expensive one.

Which model to use is a choice. Differs per deployment and soon per surface. Belongs in config.yml.

How a model must be called is a fact. gpt-5.6-luna accepts only temperature=1 and refuses function tools on /v1/chat/completions; gpt-4o-mini wants 0.0. Making a fact configurable adds no flexibility — only a way to be wrong, with the failure landing on a user's first question rather than when the mistake was made.

The evidence is one commit old: that temperature table was written with full attention on it and was wrong for eleven models (#189). An operator editing YAML has no better information and less context.

configure the choice, derive the consequences, validate the pair before the server takes traffic

Two contributed PRs to harvest

	#112 — @AaryanCode69	#151 — @bhavyakeerthi3
shape	nested ModelsConfig → LLMConfig/EmbeddingConfig	flat llm: "openai/gpt-4o-mini"
size	+50/−5, 5 files	+126/−3, 10 files

#112's structure is the better base — named fields, and base_url matters for Plant Reactome.

Both contain the same serious defect

Both make the embedding model configurable and pass it straight to get_embedding, bypassing resolve_embedding_model().

That function exists because a query embedded with a different model than built the stored vectors returns nonsense rather than an error. It reads the model from the bundle path, the only durable source of truth. It was written because a hardcoded bge-m3 default broke every fresh Reactome deployment while being correct for Plant Reactome.

#112's config_default.yml pins embedding.model: text-embedding-3-large. Applied to Plant Reactome that is the bge-m3 bug again from the other direction — and silent, because a wrong embedding model does not error, it just retrieves the wrong documents.

FR-004 makes the embedding model permanently non-configurable. The LLM half of both PRs is harvested, with credit to both contributors.

One decision for the team

D1 — does startup validate against the API, or only against the table? Recommendation: the table. It catches the pairing mistake for free and offline; a mistyped model name is a different, more obvious failure that no one will be confused by.

Spec 002's User Story 3 is marked superseded by this file.