validate.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include <entropic/config/validate.h>
#include <entropic/types/logging.h>
 
// gh#144 (v2.12.0): pure session-pool geometry + conflict rules.
#include "../inference/session_pool_util.h"
// gh#153 #42(iii) (v2.13.0): pure expert-offload conflict rules. Vendor-free
// on purpose — entropic-config links no llama.cpp.
#include "../inference/expert_offload.h"
 
static auto s_log = entropic::log::get("config");
 
namespace entropic::config {
 
std::string validate_allowed_tools(const std::vector<std::string>& tools)
{
    for (const auto& entry : tools) {
        if (entry.find('.') == std::string::npos) {
            return "allowed_tools entry '" + entry
                   + "' must use '{server_name}.{tool_name}' format";
        }
    }
    return "";
}
 
std::string validate(const ModelConfig& config)
{
    std::string err;
 
    if (config.context_length < 512 || config.context_length > 131072) {
        err = "context_length must be in [512, 131072], got "
              + std::to_string(config.context_length);
    } else if (config.adapter.empty()) {
        err = "adapter must not be empty";
    } else if (config.n_batch < 1) {
        err = "n_batch must be >= 1, got "
              + std::to_string(config.n_batch);
    } else if (config.allowed_tools.has_value()) {
        err = validate_allowed_tools(*config.allowed_tools);
    }
 
    // gh#144 (v2.12.0): a session pool and the gh#98 batch fan-out want
    // opposite KV buffers. Refuse the combination by name at CONFIGURE time
    // rather than picking one silently — either choice would fail later and
    // far from its cause (a pool without private streams, or seq_cp
    // asserting at decode).
    if (err.empty()) {
        err = session_pool_conflict_reason(config);
    }
 
    // gh#153 #42(iii) (v2.13.0): expert offload is EXPERIMENTAL and its
    // impossible combinations are refused by name here rather than
    // discovered as "the knob did nothing" after a multi-second load.
    if (err.empty()) {
        err = expert_offload_conflict_reason(config);
    }
 
    return err;
}
 
std::string validate(const ModelsConfig& config)
{
    if (!config.tiers.empty()
        && config.tiers.count(config.default_tier) == 0) {
        return "default tier '" + config.default_tier
               + "' not in tiers";
    }
    return "";
}
 
std::string validate(const CompactionConfig& config)
{
    std::string err;
 
    if (config.threshold_percent < 0.5f
        || config.threshold_percent > 0.99f) {
        err = "compaction.threshold_percent must be in [0.5, 0.99], got "
              + std::to_string(config.threshold_percent);
    } else if (config.warning_threshold_percent
               >= config.threshold_percent) {
        err = "compaction.warning_threshold_percent ("
              + std::to_string(config.warning_threshold_percent)
              + ") must be less than threshold_percent ("
              + std::to_string(config.threshold_percent) + ")";
    } else if (config.preserve_recent_turns < 1
               || config.preserve_recent_turns > 10) {
        err = "compaction.preserve_recent_turns must be in [1, 10], got "
              + std::to_string(config.preserve_recent_turns);
    } else if (config.tool_result_ttl < 1) {
        // v2.1.3 #6 / TTL clamp removal: tool_result_ttl was previously
        // documented as "1–20" but never actually validated. The upper
        // bound was always advisory — consumers can pick whatever
        // makes sense for their workload (long delegations on large
        // context windows benefit from large TTLs). Lower bound IS
        // enforced because TTL=0 would prune every result on the next
        // iteration, which is nonsensical and almost certainly a
        // misconfiguration rather than an intent.
        err = "compaction.tool_result_ttl must be >= 1, got "
              + std::to_string(config.tool_result_ttl);
    }
 
    return err;
}
 
std::string validate_fallback_tier(
    const std::string& fallback,
    const std::unordered_map<std::string, TierConfig>& tiers)
{
    if (tiers.count(fallback) == 0) {
        return "routing.fallback_tier '" + fallback + "' not in tiers";
    }
    return "";
}
 
std::string validate_tier_map(
    const std::unordered_map<std::string, std::string>& tier_map,
    const std::unordered_map<std::string, TierConfig>& tiers)
{
    for (const auto& [key, tier] : tier_map) {
        if (tiers.count(tier) == 0) {
            return "routing.tier_map['" + key + "'] = '" + tier
                   + "' not in tiers";
        }
    }
    return "";
}
 
std::string validate_handoff_rules(
    const std::unordered_map<std::string, std::vector<std::string>>& rules,
    const std::unordered_map<std::string, TierConfig>& tiers)
{
    for (const auto& [source, targets] : rules) {
        if (tiers.count(source) == 0) {
            return "routing.handoff_rules key '" + source
                   + "' not in tiers";
        }
        for (const auto& target : targets) {
            if (tiers.count(target) == 0) {
                return "routing.handoff_rules['" + source
                       + "'] contains '" + target + "' not in tiers";
            }
        }
    }
    return "";
}
 
std::string validate_classification_routable(const RoutingConfig& routing) {
    bool has_prompt = routing.classification_prompt.has_value()
                   && !routing.classification_prompt->empty();
    if (routing.enabled && has_prompt && routing.tier_map.empty()) {
        return "routing.classification_prompt is set but routing.tier_map is "
               "empty — the router emits a digit that maps to no tier, so every "
               "route falls back to the default (configure routing.tier_map)";
    }
    return "";
}
 
std::string validate_routing(
    const RoutingConfig& routing,
    const ModelsConfig& models)
{
    std::string err;
 
    if (models.tiers.empty()) {
        /* no tiers — nothing to validate */
    } else if (routing.enabled && !models.router.has_value()) {
        err = "routing.enabled is true but models.router is not configured";
    } else {
        err = validate_fallback_tier(routing.fallback_tier, models.tiers);
 
        if (err.empty()) {
            err = validate_tier_map(routing.tier_map, models.tiers);
        }
        if (err.empty()) {
            err = validate_handoff_rules(routing.handoff_rules, models.tiers);
        }
        if (err.empty()) {
            err = validate_classification_routable(routing);
        }
    }
 
    return err;
}
 
std::string warn_auto_chain_without_targets(
    const std::unordered_map<std::string, TierConfig>& tiers,
    const std::unordered_map<std::string, std::vector<std::string>>&
        handoff_rules)
{
    std::string warnings;
    for (const auto& [name, tier] : tiers) {
        if (tier.auto_chain.has_value() && !tier.auto_chain->empty()
            && handoff_rules.count(name) == 0) {
            if (!warnings.empty()) {
                warnings += "; ";
            }
            warnings += "tier '" + name
                        + "' has auto_chain but no handoff_rules entry";
        }
    }
    return warnings;
}
 
std::string validate(const PromptCacheConfig& config)
{
    if (config.enabled && config.max_bytes == 0) {
        return "inference.prompt_cache: enabled=true but max_bytes=0";
    }
    return "";
}
 
static std::string validate_model_tiers(const ModelsConfig& models)
{
    std::string err = validate(models);
 
    if (err.empty()) {
        for (const auto& [name, tier] : models.tiers) {
            err = validate(static_cast<const ModelConfig&>(tier));
            if (!err.empty()) {
                err = "models." + name + ": " + err;
                break;
            }
        }
    }
 
    if (err.empty() && models.router.has_value()) {
        err = validate(*models.router);
        if (!err.empty()) {
            err = "models.router: " + err;
        }
    }
 
    return err;
}
 
static bool holds_grammars(const std::filesystem::path& dir)
{
    std::error_code ec;
    if (!std::filesystem::is_directory(dir, ec)) { return false; }
    bool found = false;
    for (const auto& entry : std::filesystem::directory_iterator(dir, ec)) {
        if (entry.path().extension() == ".gbnf") {
            found = true;
            break;
        }
    }
    return found;
}
 
std::vector<std::filesystem::path> grammar_search_paths(
    const ParsedConfig& config,
    const std::filesystem::path& data_dir)
{
    std::vector<std::filesystem::path> dirs;
    if (!config.config_dir.empty()) {
        dirs.push_back(config.config_dir / "grammars");
    }
    // The facade's data_dir fallback runs only when the config_dir load
    // registered nothing, so include it on exactly that condition —
    // otherwise this would accept a stem the registry will not hold.
    if (!data_dir.empty() && (dirs.empty() || !holds_grammars(dirs.front()))) {
        dirs.push_back(data_dir / "grammars");
    }
    return dirs;
}
 
static bool grammar_stem_resolves(
    const std::string& stem,
    const std::vector<std::filesystem::path>& search_dirs)
{
    bool found = false;
    for (const auto& dir : search_dirs) {
        std::error_code ec;
        if (std::filesystem::exists(dir / (stem + ".gbnf"), ec)) {
            found = true;
            break;
        }
    }
    return found;
}
 
static std::string describe_search_dirs(
    const std::vector<std::filesystem::path>& search_dirs)
{
    if (search_dirs.empty()) {
        return "no grammar search path is configured "
               "(set config_dir, or install the bundled data directory)";
    }
    std::string list;
    for (const auto& dir : search_dirs) {
        if (!list.empty()) { list += ", "; }
        list += dir.string();
    }
    return list;
}
 
std::string warn_unresolved_tier_grammars(
    const ParsedConfig& config,
    const std::vector<std::filesystem::path>& search_dirs)
{
    std::vector<std::string> unresolved;
    for (const auto& [name, tier] : config.models.tiers) {
        if (!tier.grammar.has_value()) { continue; }
        // The registry keys on the file stem: "compactor.gbnf" and
        // "compactor" name the same grammar (normalize_grammar_key).
        const auto stem = tier.grammar->stem().string();
        if (stem.empty() || grammar_stem_resolves(stem, search_dirs)) {
            continue;
        }
        unresolved.push_back("models." + name + " -> '" + stem + "'");
    }
    if (unresolved.empty()) { return ""; }
 
    std::string list;
    for (const auto& entry : unresolved) {
        if (!list.empty()) { list += ", "; }
        list += entry;
    }
    return "grammar not resolvable yet for " + list
         + " — searched " + describe_search_dirs(search_dirs)
         + ". Register each key with entropic_grammar_register_file() or "
           "entropic_grammar_register() before the first run on that tier, "
           "or place <stem>.gbnf in a grammar search path. A run on such a "
           "tier before then fails with ENTROPIC_ERROR_GRAMMAR_NOT_FOUND "
           "rather than decoding unconstrained (gh#154).";
}
 
std::string validate_config(
    const ParsedConfig& config,
    std::vector<std::string>& warnings)
{
    s_log->info("Config validation start");
    std::string err = validate_model_tiers(config.models);
 
    if (err.empty()) {
        err = validate_routing(config.routing, config.models);
    }
    if (err.empty()) {
        err = validate(config.compaction);
    }
    if (err.empty()) {
        err = validate(config.prompt_cache);
    }
    if (err.empty()) {
        auto w = warn_auto_chain_without_targets(
            config.models.tiers, config.routing.handoff_rules);
        if (!w.empty()) {
            warnings.push_back(w);
        }
    }
 
    if (err.empty()) {
        s_log->info("Config validation passed ({} warning(s))",
                    warnings.size());
    } else {
        s_log->error("Config validation failed: {}", err);
    }
    return err;
}
 
} // namespace entropic::config