Agent Zero AI framework
llm_result.py DOX
Purpose
- Own canonical LLM result metadata shared by model transports, history, and tool-result processing.
- Preserve Responses API output items, provider response IDs, reasoning text, usage, and capability metadata in a serializable form.
Ownership
llm_result.pyowns the runtime implementation.llm_result.py.dox.mdowns durable notes about responsibilities, contracts, side effects, and verification for that implementation.- Classes:
ResponseItemResponseFunctionCallLLMResult- Top-level functions include metadata conversion, function-call output item construction, object normalization, output-text extraction, reasoning extraction, and function-call argument parsing.
Runtime Contracts
LLMResult.metadata()stores durable provider state underRESPONSE_METADATA_KEY: response IDs, structured output items, provider/mode/state, usage, capability data, and a nonemptyhistory_extrassnapshot for eligible local Responses turns. Accumulated prompt inputs, raw responses, and duplicated response/reasoning text are not persisted in history. Missing or non-string extras deserialize as empty for legacy chats.from_response(...)must preserve providerresponse_id,previous_response_id, raw output items, usage, and capability metadata.from_dict(...)preserves explicit modes, including the empty non-LLM sentinel; only missing or null modes use the legacyresponsesdefault.from_chat(...)must produce an equivalent chat-completions result withmode="chat_completions"andstate="off", preserving optional function-call output items and provider usage when the chat transport supplies them.- Function-call output items must preserve
call_idand optional acknowledged safety checks. repeat_response_text()combines response text and canonical calls for native repeat detection, excluding provider IDs, usage and separate reasoning. Non-native replies retain their full response text. This comparison value is transient and does not replace canonical call history or provider metadata.- Argument parsing must tolerate JSON strings, dictionaries, and malformed values without throwing.
Work Guidance
- Keep metadata backward-compatible with existing serialized chat history.
- Treat unknown response item types as preserved built-in items unless they are local function calls, message text, or reasoning.
- Avoid provider-specific assumptions in result parsing.
Verification
- Run
pytest tests/test_responses_architecture.py -qafter changing result metadata behavior. - Run focused history/tool-processing tests when changing function-call serialization.
Child DOX Index
No child DOX files.