% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/chat.R
\name{chat_llamar}
\alias{chat_llamar}
\title{Chat with a local model through an ellmer::Chat object}
\usage{
chat_llamar(
  model_path = NULL,
  base_url = NULL,
  port = 11434L,
  n_ctx = 4096L,
  n_gpu_layers = -1L,
  model_id = NULL,
  system_prompt = NULL,
  timeout = 180,
  ...
)
}
\arguments{
\item{model_path}{Path to a GGUF model file. Spawns a server (mode A).
Mutually exclusive with \code{base_url}.}

\item{base_url}{Base URL of a running OpenAI-compatible server, e.g.
\code{"http://127.0.0.1:11434/v1"}. Connects to it (mode B). Mutually
exclusive with \code{model_path}.}

\item{port}{Port for the spawned server (mode A only). Default
\code{11434}.}

\item{n_ctx, n_gpu_layers}{Passed to \code{\link{llama_serve_openai}}
when spawning (mode A only).}

\item{model_id}{Model identifier reported to ellmer. Defaults to the
model file's base name in mode A; \code{"llamar"} in mode B.}

\item{system_prompt}{Optional system prompt for the chat.}

\item{timeout}{Seconds to wait for a spawned server to accept
connections before erroring (mode A only). Default \code{180} — large
models (e.g. a 14B at Q8) can take a couple of minutes to load from disk.}

\item{...}{Passed on to \code{\link[ellmer]{chat_vllm}}.}
}
\value{
An \pkg{ellmer} \code{Chat} object. In mode A it additionally
  carries the background process handle (see \code{\link{chat_llamar_stop}}).
}
\description{
Returns an \pkg{ellmer} \code{Chat} object backed by a local GGUF model,
so the whole ellmer / ragnar toolchain (turns, tools, streaming,
structured output, \code{ragnar_register_tool_retrieve()}, …) works
against local inference. Transport is the OpenAI-compatible HTTP API
from \code{\link{llama_serve_openai}}; this function is a thin
\code{\link[ellmer]{chat_vllm}} wrapper over it. (We use the vLLM provider
because it speaks \code{/v1/chat/completions} — the de-facto standard our
server implements — whereas ellmer's \code{chat_openai}/
\code{chat_openai_compatible} target OpenAI's newer \code{/v1/responses}.)
}
\details{
Two modes, picked by which argument you pass (DBI-style — like
\code{DBI::dbConnect()} accepting either connection parameters or a
ready connection):

\describe{
  \item{\code{base_url}}{Connect to a server you already started (e.g.
    \code{llama_serve_openai()} in another process, or a worker pool).
    No process is spawned.}
  \item{\code{model_path}}{Spin up \code{llama_serve_openai()} in a
    background R process (via \pkg{callr}), wait for it to come up, and
    return a \code{Chat} pointed at it. The server process's lifetime is
    tied to the returned object: when it is garbage-collected (or R
    exits), the process is killed. Stop it eagerly with
    \code{\link{chat_llamar_stop}}.}
}

Exactly one of \code{base_url} or \code{model_path} must be supplied.
}
\section{Concurrency}{

The server is single-sequence (one request at a time); see
\code{\link{llama_serve_openai}}. For parallel sessions, run a pool of
servers on different ports and create one \code{chat_llamar(base_url=)}
per worker.
}

\section{Tool calls}{

Tool calling and structured output are mediated by the OpenAI protocol,
so they work only as far as the server implements them. The current
server does not emit \code{tool_calls} yet (see TODO), so ellmer tools
registered on the returned chat will not be invoked by the model.
}

\examples{
\dontrun{
# Mode A: spawn a server for this model and chat with it.
chat <- chat_llamar(model_path = "model.gguf")
chat$chat("Why is the sky blue?")
chat_llamar_stop(chat)            # or let GC do it

# Mode B: connect to a server you already run.
llama_serve_openai("model.gguf", port = 11434L)   # in another process
chat <- chat_llamar(base_url = "http://127.0.0.1:11434/v1")
chat$chat("Hello!")
}
}
\seealso{
[llama_serve_openai], [chat_llamar_stop]
}
