|
| 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 | +} |
0 commit comments