bookclerk_plugin_abi::ai
The checks the host runs on model listings, model runs and their replies.
A plugin serves models on its ai entrypoint (crate::AiModels) and
any plugin with the grant calls them through the AI binding
(crate::AiRunner). Three things cross a trust boundary, and each is
checked by sans-IO code that the fuzz targets and the host share:
- A model plugin's listing (
check_models): the models it serves, each with a task, a revision and the facts a caller needs. - A caller's run on the
AIbinding (check_binding_run_params): a model name (AiModelName) and an input for exactly one task. The host checks the same input again before a model plugin sees it (check_entrypoint_run_params). - A model plugin's reply to a run (
check_run_output): for text embeddings, one finite vector per input text, of the length and revision the model declared.
Nothing here loads or runs a model.
| Item | Kind | Summary |
|---|---|---|
AiError |
enum | Why a model listing, run or reply was refused. |
AiModelName |
enum | A model as a caller names it on the AI binding. |
task_alias |
function | The name of a task in a task alias (text-embeddings). |
is_ai_model_id |
function | Whether id is a model id as a plugin lists it: a lowercase letter or digit, then lowercase letters, digits, ., _ and -, short enough that the longest plugin id still fits before it in MAX_AI_MODEL_NAME_BYTES. |
check_model |
function | Checks one listed model. |
check_models |
function | Checks a model plugin's listing: at most MAX_AI_MODELS well-formed models, each id once. |
check_input |
function | Checks the input of one run and says which task it is for. |
check_binding_run_params |
function | Checks a caller's run on the AI binding. |
check_entrypoint_run_params |
function | Checks a run before a model plugin sees it on its ai entrypoint. |
embedding_vectors |
function | Splits checked text-embedding output into its vectors. |
pack_embedding_vectors |
function | Packs vectors into the wire form of AiTextEmbeddingsOutput::vectors: little-endian 32-bit floats, concatenated. |
check_run_output |
function | Checks a model plugin's reply to a run against the input it answers and the model's listing. |
decode_ai_run_reply_bytes |
function | Decodes an AiRunReply from an unpacked Cap'n Proto message, the form a model plugin's reply crosses the plugin boundary in. |
encode_ai_run_reply_bytes |
function | Encodes an AiRunReply, the inverse of decode_ai_run_reply_bytes. |
decode_ai_run_params_bytes |
function | Decodes AiRunParams from an unpacked Cap'n Proto message, the form a plugin's run on the AI binding crosses the plugin boundary in. |
encode_ai_run_params_bytes |
function | Encodes AiRunParams, the inverse of decode_ai_run_params_bytes. |
decode_ai_models_reply_bytes |
function | Decodes an AiModelsReply from an unpacked Cap'n Proto message, the form a model plugin's listing crosses the plugin boundary in. |
encode_ai_models_reply_bytes |
function | Encodes an AiModelsReply, the inverse of decode_ai_models_reply_bytes. |
AI_ALIAS_NAMESPACE |
constant | The name space of task aliases: @library/text-embeddings names the model the library chose for the task. No plugin serving models may use it as its id. |
MAX_AI_REVISION_BYTES |
constant | Longest model revision digest, in bytes. Revisions are printable ASCII without spaces. |
MAX_AI_LANGUAGE_TAG_BYTES |
constant | Longest language tag on a model, in bytes (the longest well-formed BCP 47 tag). |
pub enum AiError {
BadModelName,
BadModelId,
UnknownAlias,
TooManyModels,
DuplicateModel(String),
BadRevision,
BadDimensions,
BadMaxTokens,
BadLanguages,
NoInput,
TooManyTexts,
BadText(usize),
VectorCount,
NotFinite(usize),
BadFallbacks,
DimensionsChanged,
RevisionChanged,
UnexpectedModelName,
}
Why a model listing, run or reply was refused.
Variants
BadModelName: A model name is not@<plugin id>/<model id>or a task alias, or is overMAX_AI_MODEL_NAME_BYTES.BadModelId: A model id is not[a-z0-9][a-z0-9._-]*, or its full name would be overMAX_AI_MODEL_NAME_BYTES.UnknownAlias: A task alias names no known task.TooManyModels: A listing has more thanMAX_AI_MODELSmodels.DuplicateModel: A listing names the same model id twice.BadRevision: A revision is empty, too long, or holds a space or a non-printable byte.BadDimensions: A vector length is zero, overMAX_AI_EMBED_DIMENSIONS, or missing on a text-embedding model.BadMaxTokens: A text-embedding model declares no token limit, or zero.BadLanguages: A model's language list is too long, repeats a tag or holds a malformed one.NoInput: A run carries no input for any task.TooManyTexts: A text-embedding input has more thanMAX_AI_EMBED_TEXTStexts.BadText: The text at this index is empty or overMAX_AI_EMBED_TEXT_BYTES.VectorCount: The reply's vector bytes are not one vector of the declared length per input text.NotFinite: The vector at this index holds a number that is not finite.BadFallbacks: The fallback indexes are not ascending, repeat, or point past the input.DimensionsChanged: The reply's vector length differs from the model's listing.RevisionChanged: The reply's revision differs from the model's listing.UnexpectedModelName: A model plugin's reply named a model; only the host does.
Implements: Clone, Debug, Display, Eq, Error, From<AiError>, PartialEq
pub enum AiModelName {
Model { plugin: String, model: String },
Alias(AiTask),
}
A model as a caller names it on the AI binding.
Variants
Model: One model of one plugin:@<plugin id>/<model id>.plugin: Id of the plugin that serves the model.model: The model's id within that plugin.
Alias: The model the library chose for a task:@library/<task>.
pub fn parse(name: &str) -> Result<Self, AiError>
Parses a model name.
name- The name as a caller wrote it.
The plugin and model it names, or the task it is an alias for.
AiError::BadModelName when the name is malformed or too long,
and AiError::UnknownAlias when it is @library/ followed by
something that is not a task.
Implements: Clone, Debug, Display, Eq, Hash, PartialEq
pub fn task_alias(task: AiTask) -> &'static str
The name of a task in a task alias (text-embeddings).
task- The task.
The alias segment after @library/.
pub fn is_ai_model_id(id: &str) -> bool
Whether id is a model id as a plugin lists it: a lowercase letter or
digit, then lowercase letters, digits, ., _ and -, short enough
that the longest plugin id still fits before it in
MAX_AI_MODEL_NAME_BYTES.
id- The model id, without its@<plugin id>/prefix.
True when the id is well formed.
pub fn check_model(model: &AiModel) -> Result<(), AiError>
Checks one listed model.
model- The model as the plugin listed it.
The first rule the model breaks.
pub fn check_models(list: &AiModelList) -> Result<(), AiError>
Checks a model plugin's listing: at most MAX_AI_MODELS well-formed
models, each id once.
list- The reply toAiModels.models.
The first rule the listing breaks.
pub fn check_input(input: &AiInput) -> Result<AiTask, AiError>
Checks the input of one run and says which task it is for.
input- The run's input.
The task whose field is set.
AiError::NoInput when no task's field is set, otherwise the first
rule that task's input breaks.
pub fn check_binding_run_params(
params: &AiRunParams,
) -> Result<(AiModelName, AiTask), AiError>
Checks a caller's run on the AI binding.
params- The params ofAiRunner.run.
The parsed model name and the task the input is for. An alias for another task than the input's is refused.
The first rule the name or the input breaks.
pub fn check_entrypoint_run_params(params: &AiRunParams) -> Result<AiTask, AiError>
Checks a run before a model plugin sees it on its ai entrypoint.
params- The params ofAiModels.run;modelis the plugin's own model id.
The task the input is for.
The first rule the model id or the input breaks.
pub fn embedding_vectors(output: &AiTextEmbeddingsOutput) -> Vec<Vec<f32>>
Splits checked text-embedding output into its vectors.
output- Output that passedcheck_run_output.
One vector per input text, in input order. Empty when dimensions is
zero.
pub fn pack_embedding_vectors(vectors: &[Vec<f32>]) -> Vec<u8>
Packs vectors into the wire form of [AiTextEmbeddingsOutput::vectors]:
little-endian 32-bit floats, concatenated.
vectors- The vectors, all of one length.
The bytes.
pub fn check_run_output(
model: &AiModel,
input: &AiInput,
reply: &AiRunOk,
) -> Result<(), AiError>
Checks a model plugin's reply to a run against the input it answers and the model's listing.
For text embeddings: the vector length is the one the model listed, there is exactly one vector per input text, every number is finite, the revision is the model's, and the fallback indexes are ascending, unique and inside the input.
model- The model as its plugin listed it (checked bycheck_model).input- The input the reply answers (checked bycheck_input).reply- The success payload ofAiModels.run.
The first rule the reply breaks.
pub fn decode_ai_run_reply_bytes(bytes: &[u8]) -> Result<Result<AiRunOk, PluginError>>
Decodes an AiRunReply from an unpacked Cap'n Proto message, the form
a model plugin's reply crosses the plugin boundary in.
bytes- The message bytes.
The reply: the output, or the plugin's typed error.
Returns the Cap'n Proto error the reader reports.
pub fn encode_ai_run_reply_bytes(reply: &Result<AiRunOk, PluginError>) -> Result<Vec<u8>>
Encodes an AiRunReply, the inverse of decode_ai_run_reply_bytes.
reply- The reply to encode.
The message bytes.
Returns the Cap'n Proto error the builder reports.
pub fn decode_ai_run_params_bytes(bytes: &[u8]) -> Result<AiRunParams>
Decodes AiRunParams from an unpacked Cap'n Proto message, the form a
plugin's run on the AI binding crosses the plugin boundary in.
bytes- The message bytes.
The run.
Returns the Cap'n Proto error the reader reports.
pub fn encode_ai_run_params_bytes(params: &AiRunParams) -> Result<Vec<u8>>
Encodes AiRunParams, the inverse of decode_ai_run_params_bytes.
params- The run to encode.
The message bytes.
Returns the Cap'n Proto error the builder reports.
pub fn decode_ai_models_reply_bytes(
bytes: &[u8],
) -> Result<Result<AiModelList, PluginError>>
Decodes an AiModelsReply from an unpacked Cap'n Proto message, the
form a model plugin's listing crosses the plugin boundary in.
bytes- The message bytes.
The listing, or the plugin's typed error.
Returns the Cap'n Proto error the reader reports.
pub fn encode_ai_models_reply_bytes(
reply: &Result<AiModelList, PluginError>,
) -> Result<Vec<u8>>
Encodes an AiModelsReply, the inverse of
decode_ai_models_reply_bytes.
reply- The listing to encode.
The message bytes.
Returns the Cap'n Proto error the builder reports.
pub const AI_ALIAS_NAMESPACE: &str = "library";
The name space of task aliases: @library/text-embeddings names the
model the library chose for the task. No plugin serving models may use
it as its id.
pub const MAX_AI_REVISION_BYTES: usize = 128;
Longest model revision digest, in bytes. Revisions are printable ASCII without spaces.
pub const MAX_AI_LANGUAGE_TAG_BYTES: usize = 35;
Longest language tag on a model, in bytes (the longest well-formed BCP 47 tag).
Generated from crates/bookclerk-plugin-abi at main · View as Markdown