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

An inference format: how the model is told to write A2UI, and how its
output is read back.

A format module builds a format value from the active catalogs
(`c:new/2`), renders the system prompt snippet (`c:prompt/1`) and
creates parsers (`c:parser/1`). A *format spec* names a format module
and the options it is created with, `{module, options}` (or just the
module); `create/3` turns a spec into a format for a set of catalogs,
the way an agent does once per request after negotiating catalogs.

`A2UIAgent.DirectJson` and `A2UIAgent.Express` are the built-in
formats.

A format that implements the optional callbacks `c:catalogs/1`,
`c:base_rules/1`, `c:catalog_instructions/2` and `c:examples/2` (the
pieces its prompt is made of) can also be packaged as skills
(`A2UIAgent.SkillGenerator`).

# `spec`
*since 0.1.0* 

```elixir
@type spec() :: module() | {module(), keyword()}
```

A format module with its options.

# `base_rules`
*since 0.1.0* *optional* 

```elixir
@callback base_rules(struct()) :: String.t()
```

The catalog-independent rules of the prompt.

# `catalog_instructions`
*since 0.1.0* *optional* 

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

The prompt's part for one catalog (by id), or for all of them (`nil`).

# `catalogs`
*since 0.1.0* *optional* 

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

The format's active catalogs, in order.

# `examples`
*since 0.1.0* *optional* 

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

The prompt's examples for one catalog (by id), or for all of them (`nil`).

# `new`
*since 0.1.0* 

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

Creates the format for `catalogs` (default catalog first). Options
include `:examples`, a list of example turns (each a list of
messages).

# `parser`
*since 0.1.0* 

```elixir
@callback parser(struct()) :: struct()
```

A fresh parser for the format's catalogs.

# `prompt`
*since 0.1.0* 

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

The system prompt snippet.

# `create`
*since 0.1.0* 

```elixir
@spec create(spec(), [A2UICore.Catalog.t()], [[map()]] | nil) ::
  {:ok, struct()} | {:error, A2UICore.Error.t()}
```

Creates the format a spec names for `catalogs`, passing `examples`.

---

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