Enum Error 

#[non_exhaustive]
pub enum Error {
    EngineBusy,
    WeightsAlreadyLoaded,
    WrongModel {
        expected: Model,
    },
    UnsupportedWeights {
        tag: u32,
    },
    Load,
    LoadFailed {
        model: Model,
        detail: String,
    },
    Init,
    InitFailed {
        detail: String,
    },
    Complete {
        detail: String,
    },
    Truncated {
        capacity: usize,
    },
    Embed,
    EmbedFailed {
        detail: String,
    },
    InteriorNul {
        field: &'static str,
    },
    SpeechModelNotLoaded,
    AudioTooLong {
        samples: usize,
    },
    NonFiniteSample {
        index: usize,
    },
    Transcribe {
        detail: String,
    },
    EmbedAudio {
        detail: String,
    },
    UnsupportedLanguage {
        code: String,
    },
    InvalidKeyword {
        keyword: String,
    },
    Envelope {
        text: String,
        source: Error,
    },
    Arguments {
        source: Error,
    },
    Tools {
        source: Error,
    },
    Io(Error),
    Download {
        url: String,
        detail: String,
    },
    ChecksumMismatch {
        expected: String,
        actual: String,
    },
}

Everything that can go wrong while loading weights or driving the engine.

The enum is #[non_exhaustive]: matching it needs a _ arm, and new variants are not a breaking change.

Examples

use cactus_rs::Error;

let err = Error::Truncated { capacity: 65_536 };
assert!(err.to_string().contains("65536"));
assert!(err.to_string().contains("Help:"));

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

EngineBusy

Another instance of the same model is alive in this process: a second Needle while one exists, or a second Whistle while one exists.

WeightsAlreadyLoaded

Weights of the same kind were already loaded, and the new archive is a different one.

WrongModel

The archive holds the other kind of model than the one being built.

Needle 3 and Whistle archives carry the same magic tag, so the kind is read from the archive’s tensor directory before the engine sees it. A wrong archive is never loaded: the engine would have swapped it in over the model of that kind.

Fields

expected: Model

The model that was being built.

UnsupportedWeights

The archive is not a Needle 3 or Whistle .cact file: a wrong magic tag, or the right one over a tensor directory that cannot be read.

Fields

tag: u32

The little-endian u32 read from the first four bytes of the archive. It is the right tag, 0x05E12A84, when the tensor directory after it is truncated or malformed.

Load

Not returned since 0.2.1; see Error::LoadFailed, which carries the engine’s reason.

LoadFailed

needle_load rejected the archive; detail is the engine’s own reason.

Fields

model: Model

The model that was being built.

detail: String

The engine’s own reason, from needle_last_error.

Init

Not returned since 0.2.1; see Error::InitFailed, which carries the engine’s reason.

InitFailed

needle_init failed; detail includes the engine’s reason (e.g. the measured token count when the prefix overflows the context).

Fields

detail: String

The engine’s own reason, from needle_last_error, with the count needle_init returned.

Complete

needle_complete failed, with whatever detail the engine wrote into the buffer.

Fields

detail: String

The error field of the engine’s error envelope, or the raw text when it had none.

Truncated

The engine filled the output buffer and silently cut the envelope short.

Fields

capacity: usize

The capacity of the output buffer, in bytes, that the response filled.

Embed

Not returned since 0.2.1; see Error::EmbedFailed, which carries the engine’s reason.

EmbedFailed

needle_embed failed on text: the engine’s reason, or a float-count mismatch (“engine wrote N floats, expected D”).

Fields

detail: String

The engine’s own reason, from needle_last_error, or the float-count mismatch.

InteriorNul

A string bound for the C API contains an interior NUL byte.

Fields

field: &'static str

Which input held the NUL: "system prompt", "tools", "input", "tool index" or "keywords".

SpeechModelNotLoaded

An audio completion was asked for, and no speech model is loaded.

AudioTooLong

The clip is longer than the engine accepts.

Fields

samples: usize

The number of samples in the clip.

NonFiniteSample

A sample of the clip is NaN or infinite.

Fields

index: usize

The position of the first non-finite sample.

Transcribe

needle_transcribe failed, with the engine’s reason.

Fields

detail: String

The engine’s own reason, from needle_last_error.

EmbedAudio

needle_embed failed on a clip, with the engine’s reason.

Fields

detail: String

The engine’s own reason, from needle_last_error.

UnsupportedLanguage

A language code is not one Whistle transcribes.

Fields

code: String

The code that was given.

InvalidKeyword

A keyword holds a line break.

Fields

keyword: String

The keyword as it was given.

Envelope

The engine’s response was not the JSON envelope this crate expects.

Fields

text: String

The first few hundred bytes of the response, for the report.

source: Error

The serde_json error that rejected it.

Arguments

A tool call’s arguments did not fit the requested Rust type.

Fields

source: Error

The serde_json error that rejected the arguments.

Tools

The tool declarations could not be written as JSON for the engine.

Fields

source: Error

The serde_json error that rejected the declarations.

Io(Error)

Reading or writing a file failed.

Download

Downloading the weight archive failed.

Fields

url: String

The URL that was being fetched.

detail: String

What went wrong, as reported by the HTTP client.

ChecksumMismatch

A downloaded archive did not match its pinned SHA-256.

Fields

expected: String

The SHA-256 this crate pins, lowercase hex.

actual: String

The SHA-256 of the bytes that arrived, lowercase hex.

Implementations

impl Error

pub fn detail(&self) -> Option<&str>

The underlying reason in the error’s own words, for the variants that carry one.

That is the engine’s text for Error::Complete, Error::Transcribe, Error::EmbedAudio, Error::LoadFailed, Error::InitFailed and Error::EmbedFailed, and the HTTP client’s for Error::Download. Every other variant returns None.

Examples

use cactus_rs::Error;

let err = Error::InitFailed {
    detail: "prefix of 40000 tokens exceeds the context".to_owned(),
};
assert_eq!(err.detail(), Some("prefix of 40000 tokens exceeds the context"));
assert_eq!(Error::EngineBusy.detail(), None);

pub fn envelope(text: &str, source: Error) -> Self

Builds an Error::Envelope with the response text truncated to a loggable excerpt.

Examples

use cactus_rs::Error;

let source = serde_json::from_str::<serde_json::Value>("{").unwrap_err();
let err = Error::envelope(&"x".repeat(1000), source);
assert!(err.to_string().contains("(truncated)"));

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.