# `A2UIAgent.Express`
[🔗](https://github.com/a2ui-elixir/a2ui/blob/v0.1.1/umbrella/apps/a2ui_agent/lib/a2ui_agent/express.ex#L1)

The Express inference format: the model writes a compact,
function-call notation between `<a2ui>` and `</a2ui>` tags, which the
agent compiles into A2UI messages.

    <a2ui>
    surface("booking")
    $/form/name = ""
    root = Card(form)
    form = Column([TextField("Name", $/form/name, ?required), submit])
    submit = Button(Text("Book"), action=Event("book", {name: $/form/name}))
    </a2ui>

Components take their properties positionally in the order their
catalog schema declares them (or by keyword), variables name
components, `$` paths bind data, `?name` writes a check rule and
`Event(...)` an action. The grammar is
`specification/inference_formats/express/Express.g4`;
`A2UIAgent.Express.Compiler` describes how each statement compiles.

Because arguments are positional, a catalog must be read with the key
order of its document: `A2UICore.Catalog.Basic`,
`A2UIAgent.CatalogConfig.from_path/2` and `A2UIAgent.CatalogProvider`
keep it. A catalog built from a map (a document decoded without
`objects: :ordered_objects`) has its properties ordered by name.

    {:ok, format} = A2UIAgent.Express.new(catalogs, examples: [example_turn])
    {:ok, prompt} = A2UIAgent.Express.prompt(format)
    parser = A2UIAgent.Express.parser(format)

Options:

  * `:examples` — few-shot example turns (lists of messages), rendered
    into the prompt as Express;
  * `:allowed_messages` — the message actions the prompt teaches
    (`nil`, the default, teaches all of them);
  * `:surface_id` — the surface of statements before any `surface`
    line (default `"main"`);
  * `:version` — the protocol version to write (default: the
    catalogs').

See `A2UIAgent.Express.Prompt` for the prompt and
`A2UIAgent.Express.Parser` for reading responses. The format also
provides the pieces `A2UIAgent.SkillGenerator` builds skills from.

# `t`
*since 0.1.0* 

```elixir
@type t() :: %A2UIAgent.Express{
  allowed_messages: [String.t()] | nil,
  catalogs: A2UIAgent.Express.Catalogs.t(),
  examples: [[map()]] | nil,
  surface_id: String.t()
}
```

# `base_rules`
*since 0.1.0* 

```elixir
@spec base_rules(t()) :: String.t()
```

The grammar rules of the prompt; see `A2UIAgent.Express.Prompt.base_rules/2`.

# `catalog_instructions`
*since 0.1.0* 

```elixir
@spec catalog_instructions(t(), String.t() | nil) :: String.t()
```

The signatures and instructions of one catalog (by id), or of all of
them; see `A2UIAgent.Express.Prompt.catalog_instructions/2`.

# `catalogs`
*since 0.1.0* 

```elixir
@spec catalogs(t()) :: [A2UICore.Catalog.t()]
```

The format's active catalogs, in order.

# `examples`
*since 0.1.0* 

```elixir
@spec examples(t(), String.t() | nil) ::
  {:ok, String.t()} | {:error, A2UICore.Error.t()}
```

The example turns as Express blocks. Examples are not kept per
catalog, so every catalog has the same ones.

# `new`
*since 0.1.0* 

```elixir
@spec new([A2UICore.Catalog.t()], keyword()) ::
  {:ok, t()} | {:error, A2UICore.Error.t()}
```

Creates the format. The catalogs must be non-empty, have distinct ids
and share a protocol version; several catalogs need v1.0.

# `parser`
*since 0.1.0* 

```elixir
@spec parser(t()) :: A2UIAgent.Express.Parser.t()
```

A fresh parser for the format's catalogs.

# `prompt`
*since 0.1.0* 

```elixir
@spec prompt(t()) :: {:ok, String.t()} | {:error, A2UICore.Error.t()}
```

The system prompt snippet; see `A2UIAgent.Express.Prompt`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*