LCORE-1570: models/config: add CompactionConfiguration

Add the configuration class that controls when conversation
compaction triggers and how much recent context is kept verbatim.
Disabled by default so the addition is a pure no-op until an
operator opts in.

Fields and defaults match the spec doc exactly:

* enabled: bool — false. The master switch; everything below is
  inert when this is off.
* threshold_ratio: float — 0.7. Trigger when estimated input tokens
  exceed this fraction of the configured context window.
  field_validator clamps the value to [0, 1] inclusive so a
  misconfiguration surfaces at parse time, not at first request.
* token_floor: NonNegativeInt — 4096. Floor below which compaction
  cannot trigger, regardless of threshold_ratio. Protects very small
  context windows from spurious triggers. Zero is allowed (caller
  may want pure ratio-based triggering).
* buffer_turns: NonNegativeInt — 4. Initial size of the recent-turns
  buffer the runtime keeps verbatim. The runtime applies a degrading
  guard (4 -> 3 -> 2 -> 1 -> 0) when these turns themselves exceed
  the available budget, so zero is a legitimate fallback state.
* buffer_max_ratio: float — 0.3. Hard cap on the fraction of the
  context window the buffer zone may occupy.

The configuration is wired onto the root Configuration class as the
`compaction` field with a default_factory, so existing deployments
that have not configured a `compaction:` block in YAML continue to
parse unchanged and silently inherit the disabled-by-default
behavior.

Tests cover every field's default, the boundary values for both
ratio validators, NonNegativeInt's negative-rejection on
token_floor and buffer_turns, the extra='forbid' inherited from
ConfigurationBase, and that the root Configuration declares the
compaction field with the correct default-factory. Tests verify the
default-factory inspection-style to avoid having to construct a
full Configuration with all its other required sub-configurations.

Author: max-svistunov

src/models/config.py

@@ -1460,6 +1460,84 @@ def check_default_model_and_provider(self) -> Self:
         return self
 
 
+class CompactionConfiguration(ConfigurationBase):
+    """Configuration for conversation history compaction.
+
+    Compaction summarizes older conversation turns when their estimated
+    token count approaches the context window limit, keeping the
+    conversation usable instead of failing with HTTP 413. The
+    configuration here controls when compaction triggers and how much
+    recent context is preserved verbatim.
+
+    Attributes:
+        enabled: Master switch. When False, compaction never triggers
+            and other fields are inert.
+        threshold_ratio: Trigger compaction when estimated input tokens
+            exceed this fraction of the model's context window
+            (clamped to 0.0..1.0).
+        token_floor: Minimum estimated token count before compaction
+            can trigger, regardless of threshold_ratio. Prevents
+            triggering on very small context windows.
+        buffer_turns: Initial number of recent turns to keep verbatim.
+            The runtime applies a degrading guard — if these turns
+            exceed the available budget, it reduces buffer_turns by
+            one repeatedly until the budget fits, down to zero.
+        buffer_max_ratio: Hard cap on the fraction of the context
+            window the buffer zone may occupy, regardless of
+            buffer_turns.
+    """
+
+    enabled: bool = Field(
+        False,
+        title="Enable compaction",
+        description="When true, older conversation turns are summarized "
+        "when estimated tokens approach the context window limit.",
+    )
+    threshold_ratio: float = Field(
+        0.7,
+        title="Threshold ratio",
+        description="Trigger compaction when estimated tokens exceed "
+        "this fraction of the model's context window (0.0-1.0).",
+    )
+    token_floor: NonNegativeInt = Field(
+        4096,
+        title="Token floor",
+        description="Minimum token count before compaction can trigger. "
+        "Prevents triggering on very small context windows.",
+    )
+    buffer_turns: NonNegativeInt = Field(
+        4,
+        title="Buffer turns",
+        description="Number of recent turns to keep verbatim.",
+    )
+    buffer_max_ratio: float = Field(
+        0.3,
+        title="Buffer max ratio",
+        description="Maximum fraction of context window the buffer zone "
+        "can occupy, regardless of buffer_turns.",
+    )
+
+    @field_validator("threshold_ratio")
+    @classmethod
+    def _validate_threshold_ratio(cls, value: float) -> float:
+        """Reject threshold ratios outside the inclusive 0..1 range."""
+        if not 0.0 <= value <= 1.0:
+            raise ValueError(
+                "threshold_ratio must be between 0.0 and 1.0 (inclusive)"
+            )
+        return value
+
+    @field_validator("buffer_max_ratio")
+    @classmethod
+    def _validate_buffer_max_ratio(cls, value: float) -> float:
+        """Reject buffer-max ratios outside the inclusive 0..1 range."""
+        if not 0.0 <= value <= 1.0:
+            raise ValueError(
+                "buffer_max_ratio must be between 0.0 and 1.0 (inclusive)"
+            )
+        return value
+
+
 class ConversationHistoryConfiguration(ConfigurationBase):
     """Conversation history configuration."""
 
@@ -1932,6 +2010,15 @@ class Configuration(ConfigurationBase):
         description="Conversation history configuration.",
     )
 
+    compaction: CompactionConfiguration = Field(
+        default_factory=CompactionConfiguration,
+        title="Conversation compaction configuration",
+        description="Controls when conversation history is summarized "
+        "to keep the model's input below the context window limit. "
+        "Disabled by default — when disabled, requests that exceed the "
+        "window continue to surface as HTTP 413.",
+    )
+
     byok_rag: list[ByokRag] = Field(
         default_factory=list,
         title="BYOK RAG configuration",

tests/unit/models/config/test_compaction_configuration.py

@@ -0,0 +1,116 @@
+"""Unit tests for CompactionConfiguration and its placement on Configuration."""
+
+import pytest
+
+from models.config import CompactionConfiguration, Configuration
+
+
+def test_default_values() -> None:
+    """Default-construct CompactionConfiguration matches the spec defaults.
+
+    Defaults come from the conversation-compaction spec doc — disabled,
+    70% trigger, 4096 token floor, 4 buffer turns, 30% max buffer.
+    """
+    config = CompactionConfiguration()
+    assert config.enabled is False
+    assert config.threshold_ratio == 0.7
+    assert config.token_floor == 4096
+    assert config.buffer_turns == 4
+    assert config.buffer_max_ratio == 0.3
+
+
+def test_enabled_can_be_turned_on() -> None:
+    """The enabled master switch is configurable."""
+    config = CompactionConfiguration(enabled=True)
+    assert config.enabled is True
+
+
+def test_threshold_ratio_accepts_boundary_values() -> None:
+    """threshold_ratio accepts 0.0 and 1.0 inclusively."""
+    assert CompactionConfiguration(threshold_ratio=0.0).threshold_ratio == 0.0
+    assert CompactionConfiguration(threshold_ratio=1.0).threshold_ratio == 1.0
+
+
+def test_threshold_ratio_rejects_negative() -> None:
+    """threshold_ratio below 0 is rejected."""
+    with pytest.raises(
+        ValueError, match="threshold_ratio must be between 0.0 and 1.0"
+    ):
+        CompactionConfiguration(threshold_ratio=-0.1)
+
+
+def test_threshold_ratio_rejects_above_one() -> None:
+    """threshold_ratio above 1 is rejected."""
+    with pytest.raises(
+        ValueError, match="threshold_ratio must be between 0.0 and 1.0"
+    ):
+        CompactionConfiguration(threshold_ratio=1.1)
+
+
+def test_buffer_max_ratio_boundary_values() -> None:
+    """buffer_max_ratio accepts 0.0 and 1.0 inclusively."""
+    assert CompactionConfiguration(buffer_max_ratio=0.0).buffer_max_ratio == 0.0
+    assert CompactionConfiguration(buffer_max_ratio=1.0).buffer_max_ratio == 1.0
+
+
+def test_buffer_max_ratio_rejects_negative() -> None:
+    """buffer_max_ratio below 0 is rejected."""
+    with pytest.raises(
+        ValueError, match="buffer_max_ratio must be between 0.0 and 1.0"
+    ):
+        CompactionConfiguration(buffer_max_ratio=-0.05)
+
+
+def test_buffer_max_ratio_rejects_above_one() -> None:
+    """buffer_max_ratio above 1 is rejected."""
+    with pytest.raises(
+        ValueError, match="buffer_max_ratio must be between 0.0 and 1.0"
+    ):
+        CompactionConfiguration(buffer_max_ratio=1.5)
+
+
+def test_token_floor_rejects_negative() -> None:
+    """token_floor is NonNegativeInt and rejects negatives."""
+    with pytest.raises(ValueError):
+        CompactionConfiguration(token_floor=-1)
+
+
+def test_buffer_turns_rejects_negative() -> None:
+    """buffer_turns is NonNegativeInt and rejects negatives."""
+    with pytest.raises(ValueError):
+        CompactionConfiguration(buffer_turns=-1)
+
+
+def test_token_floor_zero_is_allowed() -> None:
+    """A zero token floor is allowed — caller may want pure ratio trigger."""
+    assert CompactionConfiguration(token_floor=0).token_floor == 0
+
+
+def test_buffer_turns_zero_is_allowed() -> None:
+    """Zero buffer turns are allowed — caller may want full summarization."""
+    assert CompactionConfiguration(buffer_turns=0).buffer_turns == 0
+
+
+def test_rejects_unknown_field() -> None:
+    """Unknown fields are forbidden via ConfigurationBase's extra='forbid'."""
+    with pytest.raises(ValueError):
+        CompactionConfiguration(unknown_field=True)  # type: ignore[call-arg]
+
+
+def test_root_configuration_has_compaction_field() -> None:
+    """The root Configuration declares a `compaction` field typed as
+    CompactionConfiguration with a default-factory that produces a
+    fresh CompactionConfiguration with the spec defaults."""
+    fields = Configuration.model_fields
+    assert "compaction" in fields, "Configuration must declare a compaction field"
+    field_info = fields["compaction"]
+    assert field_info.annotation is CompactionConfiguration
+
+    # default_factory must produce a CompactionConfiguration with disabled
+    # state — sanity check that the wiring isn't accidentally swapping in
+    # an enabled-by-default instance.
+    factory = field_info.default_factory
+    assert factory is not None
+    default = factory()  # type: ignore[call-arg]
+    assert isinstance(default, CompactionConfiguration)
+    assert default.enabled is False