% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/block-args.R
\name{new_block_arg}
\alias{new_block_arg}
\alias{new_block_args}
\alias{block_arg_description}
\alias{block_arg_example}
\alias{block_arg_type}
\alias{arg_string}
\alias{arg_number}
\alias{arg_integer}
\alias{arg_boolean}
\alias{arg_enum}
\alias{arg_array}
\alias{arg_object}
\title{Block argument specification}
\usage{
new_block_arg(description = NULL, example = NULL, type = NULL)

new_block_args(...)

block_arg_description(x, ...)

block_arg_example(x, ...)

block_arg_type(x, ...)

arg_string(description = NULL, required = TRUE)

arg_number(description = NULL, required = TRUE)

arg_integer(description = NULL, required = TRUE)

arg_boolean(description = NULL, required = TRUE)

arg_enum(values, description = NULL, required = TRUE)

arg_array(items, description = NULL, required = TRUE)

arg_object(..., description = NULL, required = TRUE)
}
\arguments{
\item{description}{Human- and model-facing description of an argument value}

\item{example}{A single worked value for an argument (or \code{NULL})}

\item{type}{Optional machine-readable type for the argument, built with the
\verb{arg_*()} descriptor constructors. A plain JSON-Schema-subset list; worked
examples are validated against it}

\item{...}{For \code{new_block_args()}, the per-argument \code{block_arg} objects (or
bare description strings); for \code{arg_object()}, the named field descriptors;
ignored by the \verb{block_arg_*()} getters}

\item{x}{A \code{block_arg} object, or a bare string taken as its description}

\item{required}{Whether the field is required, when nested in an
\code{arg_object()}}

\item{values}{Allowed string values, for \code{arg_enum()}}

\item{items}{Element descriptor, for \code{arg_array()}}
}
\value{
\code{new_block_arg()} returns a \code{block_arg} and \code{new_block_args()} a \code{block_args}
collection. The \verb{arg_*()} constructors each return a plain JSON-Schema node
(a list). The \verb{block_arg_*()} getters return the corresponding field of a
single argument (resolving a bare description string too).
}
\description{
Block constructor arguments can be documented with a structured
specification: each argument via \code{new_block_arg()} (a \code{description}, a single
worked \code{example}, and an optional machine-readable \code{type}), collected with
\code{new_block_args()}. A bare named character vector of descriptions, and the
empty \code{character()}, are also accepted and normalized into this form, so
existing registrations are unaffected. A single argument's fields are read
back with \code{block_arg_description()}, \code{block_arg_example()} and
\code{block_arg_type()}; block-level metadata (the whole argument set, worked
examples, guidance and keywords) is tabulated across blocks via
\code{\link[=block_metadata]{block_metadata()}}.
}
\details{
An argument's \code{type} is described with a small, dependency-free subset of
JSON Schema, built with the \verb{arg_*()} constructors: \code{arg_string()},
\code{arg_number()}, \code{arg_integer()} and \code{arg_boolean()} for scalars, \code{arg_enum()}
for a fixed set of string values, \code{arg_array()} for a homogeneous list and
\code{arg_object()} for a closed record of named fields (\code{additionalProperties: false}). Each returns a plain nested list mirroring the schema it denotes,
consumed directly -- blockr.ai binds it via \code{ellmer::type_from_schema()}, an
MCP or raw tool schema reads the JSON as-is -- and worked examples registered
alongside an argument are validated against it (see \code{\link[=register_block]{register_block()}}).
Semantic intent (e.g. "a column in the upstream data", "an R expression") is
carried in \code{description}, not in the type vocabulary.

The complete worked configuration of a block is the assembly of its
per-argument examples, keyed by argument name. When arguments interact, or
several few-shot examples are wanted, complete configurations are instead
supplied as a list via the \code{examples} argument of \code{\link[=register_block]{register_block()}} and
supersede that assembly; combining multiple per-argument examples is
intentionally not supported, as there is no safe way to form coherent
whole-block configurations from them.
}
\examples{
new_block_args(
  n = new_block_arg(
    "Number of rows to return",
    example = 5L,
    type = arg_integer()
  )
)

arg_object(
  conditions = arg_array(
    arg_object(column = arg_string(), value = arg_string())
  ),
  operator = arg_enum(c("&", "|"))
)

}
