ModelMeta.java

// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
// SPDX-FileCopyrightText: 2023-2025 Konstantin Herud
//
// SPDX-License-Identifier: MIT

package net.ladenthin.llama.value;

import com.fasterxml.jackson.databind.JsonNode;
import lombok.EqualsAndHashCode;

/**
 * Model metadata returned by {@link net.ladenthin.llama.LlamaModel#getModelMeta()}.
 * <p>
 * Typed getters cover all fields currently returned by the native {@code model_meta()}
 * function. The underlying {@link JsonNode} is also exposed via {@link #asJson()} so
 * that future fields added on the C++ side remain accessible without code changes.
 * </p>
 * <p>{@link #toString()} re-serializes to compact JSON and is suitable for
 * {@code assertEquals} in unit tests; it is intentionally handwritten (not
 * Lombok-generated) so the compact-JSON contract is preserved.
 * {@code equals}/{@code hashCode} are generated by Lombok over the underlying
 * {@link JsonNode} field; {@link JsonNode#equals} compares structural equality of the
 * JSON tree which is the correct value semantics for this wrapper.</p>
 */
@EqualsAndHashCode
public final class ModelMeta {

    private final JsonNode node;

    /**
     * Wraps the raw model-metadata JSON node returned by the native layer.
     *
     * @param node the JSON node holding the model metadata
     */
    public ModelMeta(JsonNode node) {
        this.node = node;
    }

    /**
     * Returns the vocabulary type identifier.
     *
     * @return vocabulary type identifier (e.g. SPM = 2, BPE = 1)
     */
    public int getVocabType() {
        return node.path("vocab_type").asInt(0);
    }

    /**
     * Returns the total number of tokens in the model vocabulary.
     *
     * @return total number of tokens in the model vocabulary
     */
    public int getNVocab() {
        return node.path("n_vocab").asInt(0);
    }

    /**
     * Context length the model was trained with.
     *
     * @return the training context length in tokens
     */
    public int getNCtxTrain() {
        return node.path("n_ctx_train").asInt(0);
    }

    /**
     * Embedding dimension of the model.
     *
     * @return the embedding dimension
     */
    public int getNEmbd() {
        return node.path("n_embd").asInt(0);
    }

    /**
     * Total number of model parameters.
     *
     * @return the parameter count
     */
    public long getNParams() {
        return node.path("n_params").asLong(0L);
    }

    /**
     * Model file size in bytes.
     *
     * @return the model file size in bytes
     */
    public long getSize() {
        return node.path("size").asLong(0L);
    }

    /**
     * Returns true if the model supports vision (image) input.
     *
     * @return {@code true} if the model accepts image input
     */
    public boolean supportsVision() {
        return node.at("/modalities/vision").asBoolean(false);
    }

    /**
     * Returns true if the model supports audio input.
     *
     * @return {@code true} if the model accepts audio input
     */
    public boolean supportsAudio() {
        return node.at("/modalities/audio").asBoolean(false);
    }

    /**
     * The model architecture string from GGUF {@code general.architecture} metadata
     * (e.g. {@code "llama"}, {@code "gemma3"}, {@code "mistral"}).
     * Returns an empty string if the field is absent in the GGUF file.
     *
     * @return the architecture identifier, or {@code ""} if absent
     */
    public String getArchitecture() {
        return node.path("architecture").asText("");
    }

    /**
     * The human-readable model name from GGUF {@code general.name} metadata.
     * Returns an empty string if the field is absent in the GGUF file.
     *
     * @return the model name, or {@code ""} if absent
     */
    public String getModelName() {
        return node.path("name").asText("");
    }

    /**
     * The model's resolved default chat template (Jinja), from GGUF
     * {@code tokenizer.chat_template} metadata.
     *
     * @return the chat template string, or {@code ""} if the model ships none
     */
    public String getChatTemplate() {
        return node.path("chat_template").asText("");
    }

    /**
     * Beginning-of-sentence token id.
     *
     * @return the BOS token id, or {@code -1} if the model defines none
     */
    public int getBosTokenId() {
        return node.at("/special_tokens/bos").asInt(-1);
    }

    /**
     * End-of-sentence token id.
     *
     * @return the EOS token id, or {@code -1} if the model defines none
     */
    public int getEosTokenId() {
        return node.at("/special_tokens/eos").asInt(-1);
    }

    /**
     * End-of-turn token id (used by chat- and FIM-aware models).
     *
     * @return the EOT token id, or {@code -1} if the model defines none
     */
    public int getEotTokenId() {
        return node.at("/special_tokens/eot").asInt(-1);
    }

    /**
     * Look up a raw GGUF metadata value by key (e.g. {@code "general.architecture"},
     * {@code "general.quantization_version"}). Large array metadata (tokenizer tokens/merges)
     * is truncated by the native layer, not returned in full.
     *
     * @param key the GGUF metadata key
     * @return the metadata value as a string, or {@code ""} if the key is absent
     */
    public String getMetadata(String key) {
        return node.path("metadata").path(key).asText("");
    }

    /**
     * Returns the underlying {@link JsonNode} for direct access to any field,
     * including fields added in future llama.cpp versions.
     *
     * @return the raw JSON node
     */
    public JsonNode asJson() {
        return node;
    }

    /** Re-serializes to compact JSON. Suitable for {@code assertEquals} in tests. */
    @Override
    public String toString() {
        return node.toString();
    }
}