Implementation:Ggml org Llama cpp Chat Header

Knowledge Sources	Ggml_org_Llama_cpp
Domains	Chat, API
Last Updated	2026-02-15 00:00 GMT

Overview

Declares the data structures and API for chat message handling, template rendering, tool calling, and output parsing across the entire chat/tool-calling subsystem.

Description

Defines `common_chat_msg` (role, content, tool_calls, reasoning_content), `common_chat_tool_call` (name, arguments, id), `common_chat_msg_diff` for streaming deltas, and `common_chat_tool` for available tool definitions. The `common_chat_format` enum lists all supported model-specific formats (Llama 3.x, DeepSeek, Mistral, Hermes, Functionary, etc.). `common_chat_templates_inputs` bundles messages, grammar, tools, and generation options, while `common_chat_params` holds the rendered prompt, grammar, grammar triggers, and format metadata. Declares functions for template creation, chat parameter application, and output parsing.

Usage

Include this header in any code that needs to work with the chat completions subsystem. It is the foundational type system used by the server, CLI tools, and any component that needs OpenAI-compatible chat completions with function calling support.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: common/chat.h
• Lines: 1-253

Signature

struct common_chat_tool_call {
    std::string name;
    std::string arguments;
    std::string id;
    bool operator==(const common_chat_tool_call & other) const;
};

struct common_chat_msg_content_part {
    std::string type;
    std::string text;
    bool operator==(const common_chat_msg_content_part & other) const;
};

struct common_chat_msg {
    std::string role;
    std::string content;
    std::vector<common_chat_msg_content_part> content_parts;
    std::vector<common_chat_tool_call> tool_calls;
    std::string reasoning_content;
    std::string tool_name;
    std::string tool_call_id;

    nlohmann::ordered_json to_json_oaicompat(bool concat_typed_text = false) const;
    bool empty() const;
    void set_tool_call_ids(std::vector<std::string> & ids_cache,
        const std::function<std::string()> & gen_tool_call_id);
};

struct common_chat_templates;
struct common_chat_tool;
struct common_chat_templates_inputs;
struct common_chat_params;
struct common_chat_parser_params;

// Template and parsing API
const common_chat_templates * common_chat_templates_init(
    const struct llama_model * model, const std::string & chat_template_override);
common_chat_params common_chat_templates_apply(
    const common_chat_templates * templates, const common_chat_templates_inputs & inputs);
common_chat_msg common_chat_parse(const std::string & input,
    common_chat_format format, const common_chat_parser_params & params);

Import

#include "common.h"
#include "peg-parser.h"
#include <functional>
#include <chrono>
#include <string>
#include <vector>
#include <map>
#include <nlohmann/json_fwd.hpp>

I/O Contract

Inputs

Name	Type	Required	Description
model	llama_model*	Yes (for template init)	Loaded model to extract chat template metadata
chat_template_override	string	No	Optional override for the model's built-in chat template
inputs	common_chat_templates_inputs	Yes	Messages, tools, grammar, and generation options
input	string	Yes (for parsing)	Raw model output text to parse
format	common_chat_format	Yes (for parsing)	Model-specific format enum (e.g., LLAMA_3_X, DEEPSEEK, HERMES)

Outputs

Name	Type	Description
common_chat_params	struct	Rendered prompt, GBNF grammar, grammar triggers, format metadata, and parser params
common_chat_msg	struct	Parsed chat message with role, content, reasoning_content, and tool_calls
JSON	nlohmann::ordered_json	OpenAI-compatible JSON representation via to_json_oaicompat()

Usage Examples

#include "chat.h"

// Initialize templates from model
auto * templates = common_chat_templates_init(model, "");

// Prepare inputs
common_chat_templates_inputs inputs;
inputs.messages = messages;
inputs.tools = tools_json;

// Apply templates to get prompt and grammar
common_chat_params params = common_chat_templates_apply(templates, inputs);
// params.prompt contains the rendered prompt
// params.grammar contains the GBNF grammar for constrained generation

// Parse model output
common_chat_msg msg = common_chat_parse(model_output, params.format, params.parser);
// msg.content has the text response
// msg.tool_calls has any extracted tool calls

Related Pages

• Principle:Ggml_org_Llama_cpp_Chat_Completions