empty_content_diagnosis.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <string>
 
namespace entropic {
 
enum class EmptyContentCause {
    not_empty,          
    tool_call_only,     
    budget_truncated,   
    model_stopped,      
    unknown,            
};
 
inline EmptyContentCause diagnose_empty_content(bool content_empty,
                                                bool produced_tokens,
                                                const std::string& finish_reason,
                                                bool has_tool_calls) {
    EmptyContentCause cause = EmptyContentCause::unknown;
    if (!content_empty || !produced_tokens) {
        cause = EmptyContentCause::not_empty;
    } else if (has_tool_calls) {
        cause = EmptyContentCause::tool_call_only;
    } else if (finish_reason == "length") {
        cause = EmptyContentCause::budget_truncated;
    } else if (finish_reason == "stop") {
        cause = EmptyContentCause::model_stopped;
    }
    return cause;
}
 
inline std::string explain_empty_content(EmptyContentCause cause) {
    // The gh#137 case deliberately does NOT mention max_tokens: the model chose
    // to stop, so more budget changes nothing and naming it misdirects.
    static const std::string kBudget =
        "The generation hit its token budget while still inside a reasoning "
        "block, so no answer was ever produced and the content is empty. This "
        "is a budget problem: raise max_tokens for this tier.";
    static const std::string kStopped =
        "The model ended the turn while still inside an unterminated reasoning "
        "block, so the content is empty. finish_reason is 'stop', NOT 'length' "
        "— this is not a budget problem and raising max_tokens will not help. "
        "The prompt or tier configuration is not converging on an answer.";
    // gh#159: NOT a fault. `apply_adapter_parse` moves tool calls out of
    // content, so a well-behaved sequential turn arrives here looking
    // exactly like gh#137's failure. Says nothing about reasoning blocks,
    // max_tokens or convergence — a consumer ACTS on those words.
    static const std::string kToolCallOnly =
        "The turn's entire output was tool calls, which the adapter moved out "
        "of the content — nothing was lost. This is the expected shape for a "
        "sequential tool-call tier and needs no tuning.";
    static const std::string kUnknown =
        "The turn produced tokens but delivered no content, and the finish "
        "reason does not explain why. This is not a parse error; report it "
        "with the raw generation attached.";
 
    std::string out;
    if (cause == EmptyContentCause::tool_call_only) {
        out = kToolCallOnly;
    } else if (cause == EmptyContentCause::budget_truncated) {
        out = kBudget;
    } else if (cause == EmptyContentCause::model_stopped) {
        out = kStopped;
    } else if (cause == EmptyContentCause::unknown) {
        out = kUnknown;
    }
    return out;
}
 
}  // namespace entropic