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

1"""Configuration of the agent contract (wave 11, #97). 

2 

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.""" 

8 

9from __future__ import annotations 

10 

11from typing import Any, Final, Literal 

12 

13from pydantic import Field, field_validator 

14 

15from governed_harness.configuration.agent_results import SizeClass, _Section, off_from_yaml 

16 

17AgentContractMode = Literal["enforce", "off"] 

18BudgetProfile = Literal["uniform", "by-kind"] 

19 

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 

25 

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.""" 

36 

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.""" 

45 

46 

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``.""" 

54 

55 

56class SizeBudget(_Section): 

57 """The token budget and the time limit of one agent call for a task size.""" 

58 

59 tokens: int | None = Field(default=None, ge=1000) 

60 wall_seconds: int | None = Field(default=None, alias="wallSeconds", ge=1) 

61 

62 

63class ResponseLimits(_Section): 

64 """Caps on what an agent may send back to its parent (per field).""" 

65 

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) 

69 

70 

71class AgentContractConfig(_Section): 

72 """The agent contract of a run (wave 11, #97). 

73 

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).""" 

79 

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.""" 

90 

91 @field_validator("mode", mode="before") 

92 @classmethod 

93 def _bare_off(cls, value: Any) -> Any: 

94 return off_from_yaml(value) 

95 

96 @property 

97 def enabled(self) -> bool: 

98 return self.mode == "enforce" 

99 

100 @property 

101 def iterations(self) -> int: 

102 return self.max_iterations or DEFAULT_MAX_ITERATIONS 

103 

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 

115 

116 @property 

117 def summary_chars(self) -> int: 

118 return (self.limits.summary_chars if self.limits else None) or DEFAULT_SUMMARY_CHARS 

119 

120 @property 

121 def field_chars(self) -> int: 

122 return (self.limits.field_chars if self.limits else None) or DEFAULT_FIELD_CHARS 

123 

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"])