% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api_llamacpp.R
\name{llamacpp_chat}
\alias{llamacpp_chat}
\title{Send LLM Messages to a llama.cpp Server}
\usage{
llamacpp_chat(
  .llm,
  .model = "local-model",
  .max_tokens = 1024,
  .temperature = NULL,
  .top_p = NULL,
  .stop = NULL,
  .stream = FALSE,
  .tools = NULL,
  .tool_choice = NULL,
  .json_schema = NULL,
  .grammar = NULL,
  .logprobs = FALSE,
  .top_logprobs = NULL,
  .seed = NULL,
  .thinking = NULL,
  .thinking_budget = NULL,
  .server = Sys.getenv("LLAMACPP_SERVER", "http://localhost:8080"),
  .api_key = Sys.getenv("LLAMACPP_API_KEY", ""),
  .timeout = 120,
  .verbose = FALSE,
  .dry_run = FALSE,
  .max_tries = 3,
  .max_tool_rounds = 10
)
}
\arguments{
\item{.llm}{An \code{LLMMessage} object containing the conversation history.}

\item{.model}{The model name (default: \code{"local-model"}). llama.cpp ignores this
value and serves whatever GGUF is loaded; the default is a clear placeholder.}

\item{.max_tokens}{Maximum tokens in the response (default: 1024).}

\item{.temperature}{Controls randomness (0–2, optional).}

\item{.top_p}{Nucleus sampling parameter (0–1, optional).}

\item{.stop}{One or more stop sequences (optional).}

\item{.stream}{Logical; if TRUE, streams the response (default: FALSE).}

\item{.tools}{Either a single TOOL object or a list of TOOL objects.}

\item{.tool_choice}{Tool-calling behavior: \code{"none"}, \code{"auto"}, or \code{"required"} (optional).}

\item{.json_schema}{A JSON schema as an R list to enforce structured output. Passed
as \verb{response_format = \{type: "json_schema", ...\}} — enforced at the sampler level.}

\item{.grammar}{A BNF grammar string to constrain sampling to any formal language
(e.g. \code{"root ::= [0-9]{4}"} for a 4-digit year). Takes precedence over
\code{.json_schema} when both are set; use one or the other.}

\item{.logprobs}{Logical; if TRUE, returns token log-probabilities (default: FALSE).}

\item{.top_logprobs}{Integer; number of top-alternative log-prob entries to return
per token (1–20, optional). Requires \code{.logprobs = TRUE}.}

\item{.seed}{Integer; random seed for reproducible outputs (optional).}

\item{.thinking}{Logical; if TRUE, enables extended reasoning/thinking mode for models
that support it (e.g. Qwen3). \code{NULL} (default) lets the server decide; \code{FALSE}
explicitly disables it for faster responses; \code{TRUE} forces it on. The thinking
trace is accessible via \code{get_metadata(result)$api_specific$thinking}.}

\item{.thinking_budget}{Integer; maximum tokens the model may use for thinking when
\code{.thinking = TRUE}. \code{NULL} uses the server default (optional).}

\item{.server}{Base URL of the llama.cpp server. Defaults to the \code{LLAMACPP_SERVER}
environment variable, falling back to \code{"http://localhost:8080"}.}

\item{.api_key}{API key for the llama.cpp server. Defaults to the \code{LLAMACPP_API_KEY}
environment variable. Leave unset if the server was started without \code{--api-key}.}

\item{.timeout}{Request timeout in seconds (default: 120).}

\item{.verbose}{If TRUE, displays additional information (default: FALSE).}

\item{.dry_run}{If TRUE, returns the request object without executing it (default: FALSE).}

\item{.max_tries}{Maximum retries (default: 3).}

\item{.max_tool_rounds}{Maximum tool use iterations (default: 10).}
}
\value{
A new \code{LLMMessage} object containing the original messages plus the
assistant's response.
}
\description{
Sends a message history to a local llama.cpp server using the OpenAI-compatible
Chat Completions API. Supports BNF grammar constraints (a llama.cpp-specific
feature that enforces output format at the token sampling level) and token
logprobs for uncertainty quantification.
}
