Coverage for src/governed_harness/configuration/agent_contract.py: 100%
59 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Configuration of the agent contract (wave 11, #97).
3``agentContract`` turns on, for every agent call of a run, the versioned request and response
4contract (``agents/contract.py``): the minimal request of each call kind, the limits of the
5response, one cap of iterations per agent and a token budget and time limit derived from the
6size of the task. Absent, the run keeps the earlier behaviour and its configuration digest;
7``harness init`` writes the section."""
9from __future__ import annotations
11from typing import Any, Final, Literal
13from pydantic import Field, field_validator
15from governed_harness.configuration.agent_results import SizeClass, _Section, off_from_yaml
17AgentContractMode = Literal["enforce", "off"]
18BudgetProfile = Literal["uniform", "by-kind"]
20MAX_ITERATIONS_CEILING: Final = 6
21"""The most iterations a configuration may allow an agent: a larger cap is rejected."""
22DEFAULT_MAX_ITERATIONS: Final = 5
23DEFAULT_SUMMARY_CHARS: Final = 600
24DEFAULT_FIELD_CHARS: Final = 4000
26DEFAULT_RESULT_BYTES: Final[dict[str, int]] = {
27 "implement": 4_096,
28 "clarify": 32_768,
29 "plan": 32_768,
30 "locate": 32_768,
31 "review": 65_536,
32 "architecture": 65_536,
33 "acceptance": 262_144,
34}
35"""Largest ``result`` object (serialized JSON, UTF-8 bytes) a call kind may return."""
37DEFAULT_SIZE_BUDGETS: Final[dict[str, tuple[int, int]]] = {
38 "S": (50_000, 600),
39 "M": (200_000, 1_800),
40 "L": (800_000, 5_400),
41}
42"""Token budget and time limit (seconds) of one call by task size: starting values in a 1:4:16
43ratio, to be calibrated from the recorded usage (``harness routing calibrate``), not a measured
44optimum."""
47DEFAULT_KIND_BUDGETS: Final[dict[str, dict[str, int]]] = {
48 "implement": {"S": 120_000, "M": 300_000, "L": 800_000},
49 "read-only": {"S": 100_000, "M": 200_000, "L": 800_000},
50}
51"""Since 2.0.1 (``budgetProfile: by-kind``): the token budget of one call by kind and task size,
52from the counted tokens of the 2.0.0 pilot calls (about the 95th percentile times 1.5, never
53below the uniform budget); the time limits stay those of ``DEFAULT_SIZE_BUDGETS``."""
56class SizeBudget(_Section):
57 """The token budget and the time limit of one agent call for a task size."""
59 tokens: int | None = Field(default=None, ge=1000)
60 wall_seconds: int | None = Field(default=None, alias="wallSeconds", ge=1)
63class ResponseLimits(_Section):
64 """Caps on what an agent may send back to its parent (per field)."""
66 summary_chars: int | None = Field(default=None, alias="summaryChars", ge=40, le=5000)
67 result_bytes: int | None = Field(default=None, alias="resultBytes", ge=256)
68 field_chars: int | None = Field(default=None, alias="fieldChars", ge=80)
71class AgentContractConfig(_Section):
72 """The agent contract of a run (wave 11, #97).
74 * ``maxIterations``: the cap of iterations of one agent in a run, at most 6 (default 5);
75 an iteration is one call to the agent with its own outcome;
76 * ``budgets``: token budget and time limit of a call by task size (S, M, L);
77 * ``limits``: caps of the response (summary characters, result bytes, characters of any
78 text field of the result)."""
80 mode: AgentContractMode = "enforce"
81 max_iterations: int | None = Field(
82 default=None, alias="maxIterations", ge=1, le=MAX_ITERATIONS_CEILING
83 )
84 budgets: dict[SizeClass, SizeBudget] | None = None
85 limits: ResponseLimits | None = None
86 budget_profile: BudgetProfile | None = Field(default=None, alias="budgetProfile")
87 """Since 2.0.1: ``by-kind`` takes the token budget of a call from ``DEFAULT_KIND_BUDGETS``
88 (``implement`` apart from the read-only calls); ``uniform`` (the default) keeps one budget
89 per size, as in 2.0.0. A size of ``budgets`` with its own ``tokens`` wins over both."""
91 @field_validator("mode", mode="before")
92 @classmethod
93 def _bare_off(cls, value: Any) -> Any:
94 return off_from_yaml(value)
96 @property
97 def enabled(self) -> bool:
98 return self.mode == "enforce"
100 @property
101 def iterations(self) -> int:
102 return self.max_iterations or DEFAULT_MAX_ITERATIONS
104 def budget_for(self, size: SizeClass, kind: str | None = None) -> tuple[int, int]:
105 """The token budget and the time limit in seconds of a call for a task of ``size``
106 (under ``budgetProfile: by-kind``, also by the call's ``kind``)."""
107 tokens, seconds = DEFAULT_SIZE_BUDGETS[size]
108 if self.budget_profile == "by-kind" and kind is not None:
109 group = "implement" if kind == "implement" else "read-only"
110 tokens = DEFAULT_KIND_BUDGETS[group][size]
111 own = (self.budgets or {}).get(size)
112 if own is None:
113 return tokens, seconds
114 return own.tokens or tokens, own.wall_seconds or seconds
116 @property
117 def summary_chars(self) -> int:
118 return (self.limits.summary_chars if self.limits else None) or DEFAULT_SUMMARY_CHARS
120 @property
121 def field_chars(self) -> int:
122 return (self.limits.field_chars if self.limits else None) or DEFAULT_FIELD_CHARS
124 def result_bytes(self, kind: str) -> int:
125 own = self.limits.result_bytes if self.limits else None
126 return own or DEFAULT_RESULT_BYTES.get(kind, DEFAULT_RESULT_BYTES["clarify"])