refactor: add SimpleFieldMapper base class for trivial parameter mappers

[Kamilbenkirane]

Summary

Six parameter mapper classes at the protocol/provider level implement the identical validate-then-set pattern, differing only in the target field name.

Current Code (repeated 6 times)

class TemperatureMapper(ParameterMapper):
    """Map temperature to Chat Completions temperature field."""

    def map(self, request: dict[str, Any], value: object, model: Model) -> dict[str, Any]:
        validated_value = self._validate_value(value, model)
        if validated_value is None:
            return request
        request["temperature"] = validated_value  # only this line differs
        return request

Duplicated for: temperature, max_tokens (chatcompletions), temperature, max_output_tokens (openresponses), temperature, max_tokens (cohere).

Proposed Change

Add SimpleFieldMapper to src/celeste/parameters.py:

class SimpleFieldMapper(ParameterMapper):
    """Maps a parameter directly to a request field after validation."""
    field: str

    def map(self, request: dict[str, Any], value: Any, model: Model) -> dict[str, Any]:
        validated_value = self._validate_value(value, model)
        if validated_value is None:
            return request
        request[self.field] = validated_value
        return request

Each simple mapper becomes a 2-line class:

class TemperatureMapper(SimpleFieldMapper):
    field = "temperature"

Modality-level wrappers (e.g., modalities/text/providers/groq/parameters.py) are unchanged - they already just set name and inherit the protocol mapper.

Files to Modify

• src/celeste/parameters.py (add SimpleFieldMapper)
• src/celeste/protocols/chatcompletions/parameters.py (TemperatureMapper, MaxTokensMapper)
• src/celeste/protocols/openresponses/parameters.py (TemperatureMapper, MaxOutputTokensMapper)
• src/celeste/providers/cohere/chat/parameters.py (TemperatureMapper, MaxTokensMapper)

Rationale

6 identical 8-line implementations reduced to 6 two-line declarations. Complex mappers like ResponseFormatMapper and ThinkingMapper remain untouched. The SimpleFieldMapper is itself a clean, single-responsibility class.

[Kamilbenkirane]

Good direction — the DRY violation is real and worth fixing. A few thoughts:

Placement is correct. SimpleFieldMapper belongs in parameters.py, not inside any individual protocol. It encodes zero protocol knowledge; the protocol-specific part is just the string value of field. Scoping it to a single protocol would defeat the purpose.

Name: slight preference for FieldMapper. Simple prefix can read as 'naive/non-production' (cf. Java's SimpleDateFormat baggage). FieldMapper describes what it is without a complexity qualifier, and the existing ParameterMapper doesn't qualify its complexity either. That said, SimpleFieldMapper is defensible since it does communicate 'for trivial cases' at a glance.

Annotate field as ClassVar[str]. The proposed field: str annotation is not enforced at runtime — a subclass that forgets to set it fails with AttributeError at call time, not at definition time. This is consistent with how name: StrEnum is currently handled on ParameterMapper, but being explicit here would help:

from typing import ClassVar

class SimpleFieldMapper(ParameterMapper):
    """Maps a parameter directly to a request field after validation."""
    field: ClassVar[str]

    def map(self, request: dict[str, Any], value: Any, model: Model) -> dict[str, Any]:
        validated_value = self._validate_value(value, model)
        if validated_value is None:
            return request
        request[self.field] = validated_value
        return request

Scope is conservative — more mappers qualify. The 6 protocol-level mappers cited are just the start. There appear to be many more across providers that follow the same pattern:

• providers/anthropic/messages/parameters.py: TemperatureMapper, TopPMapper, TopKMapper, MaxTokensMapper, StopSequencesMapper
• providers/openai/images/parameters.py: PartialImagesMapper, QualityMapper, BackgroundMapper, OutputFormatMapper, StyleMapper, ModerationMapper, OutputCompressionMapper
• providers/openai/audio/parameters.py: VoiceMapper, SpeedMapper, InstructionsMapper

Worth deciding upfront whether this PR targets only the protocol layer or does a full sweep — a half-migrated codebase would be more confusing than the current state.

[Kamilbenkirane]

Follow-up after digging through the full codebase: the scope is significantly larger than the 6 protocol-level mappers cited.

Actual count: 41 classes across 13 files follow the same validate-then-set pattern at the protocol and provider level:

• protocols/chatcompletions/parameters.py — 2 (Temperature, MaxTokens)
• protocols/openresponses/parameters.py — 2 (Temperature, MaxOutputTokens)
• providers/anthropic/messages/parameters.py — 5 (Temperature, TopP, TopK, MaxTokens, StopSequences)
• providers/openai/images/parameters.py — 8 (Size, PartialImages, Quality, Background, OutputFormat, Style, Moderation, OutputCompression)
• providers/openai/audio/parameters.py — 3 (Voice, Speed, Instructions)
• providers/openai/videos/parameters.py — 1 (InputReference)
• providers/cohere/chat/parameters.py — 2 (Temperature, MaxTokens)
• providers/bfl/images/parameters.py — 6 (PromptUpsampling, Seed, SafetyTolerance, OutputFormat, Steps, Guidance)
• providers/byteplus/images/parameters.py — 2 (Size, Watermark)
• providers/xai/images/parameters.py — 3 (AspectRatio, NumImages, ResponseFormat)
• providers/xai/videos/parameters.py — 3 (Duration, AspectRatio, Resolution)
• providers/ollama/generate/parameters.py — 2 (Steps, NegativePrompt)
• providers/gradium/text_to_speech/parameters.py — 2 (Voice, OutputFormat)

Modality wrapper files (modalities/*/providers/*/parameters.py) need no changes — they already just set name and will inherit the new map() through the chain.

Google providers are intentionally excluded — they all use nested dict patterns (request.setdefault("generationConfig", {})["temperature"]), not flat request[field] assignment.

Two additional notes:

Name: Going with FieldMapper over SimpleFieldMapper as discussed in the previous comment.

Consistency fix in the same PR: name: StrEnum on ParameterMapper is currently a bare annotation, just like the proposed field: str would be. If we upgrade field to ClassVar[str], we should do the same for name → ClassVar[StrEnum] in the same commit. Adopting ClassVar for one and not the other would be an odd half-measure within the same hierarchy.