Skip to content

Commit 210f465

Browse files
committed
feat(agent): gate the final model request on a context window budget (issue #137)
1 parent 7383546 commit 210f465

16 files changed

Lines changed: 1440 additions & 8 deletions

File tree

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
/*
2+
* Copyright 2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.agent.budget;
17+
18+
import io.github.agentic.ai.agent.interceptor.ModelRequest;
19+
import io.github.agentic.ai.api.chat.ChatMessage;
20+
import io.github.agentic.ai.api.chat.ContentPart;
21+
import io.github.agentic.ai.api.chat.ToolCall;
22+
import io.github.agentic.ai.api.chat.ToolDefinition;
23+
24+
import java.util.HashSet;
25+
import java.util.Map;
26+
import java.util.Objects;
27+
import java.util.Set;
28+
29+
/**
30+
* The default estimator: a character based approximation of the token consumption of
31+
* a request.
32+
*
33+
* <p>
34+
* Unlike the message-only counters of the framework, the estimate covers the whole
35+
* request which is finally dispatched: the system message, the conversation, the
36+
* disclosed tool schemas and the reserved output.
37+
*
38+
* <p>
39+
* The tool schemas are counted for the bindings the request actually discloses. When
40+
* the request carries an explicit tool selection, only the selected bindings are
41+
* counted; the dynamic bindings of the request are always counted because they are
42+
* disclosed next to the selected ones.
43+
*/
44+
public final class ApproximateRequestTokenEstimator implements RequestTokenEstimator {
45+
46+
/**
47+
* The average number of characters per token used by the approximation.
48+
*/
49+
public static final int DEFAULT_CHARS_PER_TOKEN = 4;
50+
51+
private final int charsPerToken;
52+
53+
/**
54+
* Creates an estimator with the default character ratio.
55+
*/
56+
public ApproximateRequestTokenEstimator() {
57+
this(DEFAULT_CHARS_PER_TOKEN);
58+
}
59+
60+
/**
61+
* Creates an estimator with a custom character ratio.
62+
* @param charsPerToken the average number of characters per token, must be positive
63+
*/
64+
public ApproximateRequestTokenEstimator(int charsPerToken) {
65+
if (charsPerToken <= 0) {
66+
throw new IllegalArgumentException("charsPerToken must be positive");
67+
}
68+
this.charsPerToken = charsPerToken;
69+
}
70+
71+
@Override
72+
public RequestTokenEstimate estimate(ModelRequest request, ContextWindowBudget budget) {
73+
Objects.requireNonNull(request, "request must not be null");
74+
Objects.requireNonNull(budget, "budget must not be null");
75+
return new RequestTokenEstimate(systemTokens(request), messageTokens(request), toolSchemaTokens(request),
76+
budget.outputReserve(), EstimationAccuracy.APPROXIMATE);
77+
}
78+
79+
private int systemTokens(ModelRequest request) {
80+
ChatMessage systemMessage = request.getSystemMessage();
81+
return systemMessage == null ? 0 : messageTokens(systemMessage);
82+
}
83+
84+
private int messageTokens(ModelRequest request) {
85+
int total = 0;
86+
for (ChatMessage message : request.getMessages()) {
87+
total += messageTokens(message);
88+
}
89+
return total;
90+
}
91+
92+
private int messageTokens(ChatMessage message) {
93+
int total = 0;
94+
for (ContentPart part : message.content()) {
95+
if (part.text() != null) {
96+
total += tokens(part.text());
97+
}
98+
else if (part.data() != null) {
99+
total += tokens(part.data().length);
100+
}
101+
}
102+
for (ToolCall call : message.toolCalls()) {
103+
total += tokens(call.arguments());
104+
}
105+
return total;
106+
}
107+
108+
private int toolSchemaTokens(ModelRequest request) {
109+
Set<String> selection = request.hasToolSelection() ? new HashSet<>(request.getTools()) : null;
110+
int total = 0;
111+
for (ToolDefinition definition : request.getToolRegistry().definitions()) {
112+
if (selection == null || selection.contains(definition.name())) {
113+
total += definitionTokens(definition);
114+
}
115+
}
116+
for (ToolDefinition definition : request.getDynamicToolRegistry().definitions()) {
117+
total += definitionTokens(definition);
118+
}
119+
for (Map.Entry<String, String> description : request.getToolDescriptions().entrySet()) {
120+
total += tokens(description.getKey()) + tokens(description.getValue());
121+
}
122+
return total;
123+
}
124+
125+
private int definitionTokens(ToolDefinition definition) {
126+
return tokens(definition.name()) + tokens(definition.description()) + tokens(definition.inputSchema());
127+
}
128+
129+
private int tokens(String text) {
130+
if (text == null || text.isEmpty()) {
131+
return 0;
132+
}
133+
return tokens(text.length());
134+
}
135+
136+
private int tokens(int length) {
137+
if (length <= 0) {
138+
return 0;
139+
}
140+
return (length + charsPerToken - 1) / charsPerToken;
141+
}
142+
143+
}
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/*
2+
* Copyright 2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.agent.budget;
17+
18+
/**
19+
* The part of a request which exceeded the budget.
20+
*/
21+
public enum BudgetComponent {
22+
23+
/**
24+
* The system message.
25+
*/
26+
SYSTEM,
27+
28+
/**
29+
* The conversation.
30+
*/
31+
MESSAGES,
32+
33+
/**
34+
* The disclosed tool schemas.
35+
*/
36+
TOOL_SCHEMA,
37+
38+
/**
39+
* The tokens reserved for the completion.
40+
*/
41+
OUTPUT_RESERVE,
42+
43+
/**
44+
* The request as a whole.
45+
*/
46+
TOTAL
47+
48+
}
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
/*
2+
* Copyright 2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.agent.budget;
17+
18+
import java.util.Objects;
19+
20+
/**
21+
* A budget which was exceeded.
22+
*
23+
* <p>
24+
* The violation is a value, not a message: a caller can react to the classified
25+
* component instead of parsing an error string.
26+
*
27+
* @param component the part which exceeded the budget
28+
* @param estimatedTokens the estimated tokens of that part
29+
* @param limitTokens the tokens available for it
30+
*/
31+
public record BudgetViolation(BudgetComponent component, int estimatedTokens, int limitTokens) {
32+
33+
/**
34+
* Creates a budget violation.
35+
* @param component the part which exceeded the budget, must not be null
36+
* @param estimatedTokens the estimated tokens of that part, must not be negative
37+
* @param limitTokens the tokens available for it, must not be negative
38+
*/
39+
public BudgetViolation {
40+
Objects.requireNonNull(component, "component must not be null");
41+
if (estimatedTokens < 0 || limitTokens < 0) {
42+
throw new IllegalArgumentException("token counts must not be negative");
43+
}
44+
}
45+
46+
/**
47+
* Describes the violation of the total budget.
48+
* @param estimate the estimate which exceeded the budget, must not be null
49+
* @param budget the budget which was exceeded, must not be null
50+
* @return the violation
51+
*/
52+
public static BudgetViolation ofTotal(RequestTokenEstimate estimate, ContextWindowBudget budget) {
53+
Objects.requireNonNull(estimate, "estimate must not be null");
54+
Objects.requireNonNull(budget, "budget must not be null");
55+
return new BudgetViolation(BudgetComponent.TOTAL, estimate.totalTokens(), budget.inputTokenLimit());
56+
}
57+
58+
/**
59+
* The tokens which exceeded the budget.
60+
* @return the excess in tokens
61+
*/
62+
public int excessTokens() {
63+
return Math.max(0, estimatedTokens - limitTokens);
64+
}
65+
66+
}

0 commit comments

Comments
 (0)