Crate openai_magic_instantiate

This crate provides a way to instantiate well-typed and validated values using the OpenAI API.

The main trait is MagicInstantiate which can be derived automatically using the #[derive(MagicInstantiate)] macro.

For a type that implements MagicInstantiate, you can call instantiate to get a value of that type:

use openai_magic_instantiate::*;
 
#[derive(Debug, MagicInstantiate)]
// You can add descriptions to the struct and its fields that will appear
// as comments in the generated TypeScript
#[magic(description = "A simple container for a name and date of birth")]
// You can also add validators to the struct and its fields
// The validator's instructions will also appear as comments in the
// generated TypeScript, the validation will be called during instantiation
struct Person {
    #[magic(description = "<given name> <surname> (no middle)")]
    name: String,
 
    // Multiple validators can be used.
    // There are types provided for common assertions like Min and Max
    #[magic(validator = YearValidator)]
    #[magic(validator = Min(1900))]
    #[magic(validator = Max(2100))]
    year_of_birth: u32,
}
 
struct YearValidator;
 
impl Validator<u32> for YearValidator {
    fn instructions(&self) -> String {
        "Value must be a 4-digit year, do not use 2-digit abbreviations".into()
    }
 
    fn validate(&self, value: &u32) -> Result<(), String> {
        if *value < 1000 || *value > 9999 { 
            Err(format!("{} is not a 4-digit year", value))
        } else {
            Ok(())
        }
    }
}
 
async fn example() {
    let client = async_openai::Client::new();
    let person = client.instantiate::<Person>("President of the United States in 1954").await.unwrap();
    assert_eq!(person.name, "Dwight Eisenhower");
}

Internally, the library will compile these type definitions and instructions into a snippet of TypeScript code. Then, it will prompt the model to generate a JSON value of the specified type. The JSON value is then validated and converted to the Rust type.

For the example above, the following prompt is generated:

// Integer in [0, 4294967295]
type U32 = number;
 
// A simple container for a name and date of birth
type Person = {
    // <given name> <surname> (no middle)
    name: string;
    // Value must be a 4-digit year, do not use 2-digit abbreviations
    // Value must be greater than or equal to 1900
    // Value must be less than or equal to 2100
    yearOfBirth: U32;
};
 
President of the United States in 1954
 
Give the result as a JSON value of type Person.
Use minified JSON on a single line.
Use the exact type specified.

If you are just hacking up a quick script, you may find the make_magic! macro useful for reducing clutter. It generates a macro that you can use to instantiate values without having to pass the client around:

use openai_magic_instantiate::*;
 
#[derive(Debug, MagicInstantiate)]
struct Person {
    name: String,
    year_of_birth: u32,
} 
 
async fn example() {
    make_magic!(async_openai::Client::new());
 
    let Person { name, year_of_birth } = magic!("President of the United States in 1954");
     
    assert_eq!(name, "Dwight D. Eisenhower");
 
    // You can also use the macro to pass in arguments to the prompt like in format strings
    if magic!("{} was King of England", name) {
        unreachable!("Eisenhower was not King of England");
    }
}

Modules

• export

Macros

• make_magic
  make_magic! is a macro that generates a macro that you can use to instantiate values without having to pass the client around.

Structs

• ExactLength
  A Validator that creates a constraint that the string must be exactly a certain length.
• IndexedArray
  IndexedArray is a wrapper around a Vec that should be used when you want to enforce a particular length.
• MagicInstantiateParameters
  A wrapper around all the arguments needed to instantiate a value.
• Max
  A Validator that creates a maximum valid value constraint (i.e. a ceiling).
• MaxLength
  A Validator that creates a maximum length constraint for strings and lists.
• Min
  A Validator that creates a minimum valid value constraint (i.e. a floor).
• MinLength
  A Validator that creates a minimum length constraint for strings and lists.
• ModelSettings
• TypeScriptAccumulator
  Accumulates TypeScript definitions needed to define a type. You probably do not need to use interact with this type unless you are implementing MagicInstantiate manually.

Enums

• InstantiateError

Traits

• ClientInstantiate
  An extension trait for OpenAIClient that adds a method to instantiate a value.
• MagicInstantiate
  The MagicInstantiate trait is the main trait of this library, but you should not need to implement it manually. Prefer using the #[derive(MagicInstantiate)] macro instead.
• Validator
  A Validator is a type that can validate a value of type T.

Functions

• get_global_model_settings
  Get a copy of the current global model settings used for instantiate.
• mutate_global_model_settings
  If you want to set some global parameters for all instantiations, you can use this function to mutate them.

Derive Macros

• MagicInstantiate
  Derive the MagicInstantiate trait for a struct or enum. Descriptions and validators can be added to fields using the #[magic(description = ...)] and #[magic(validator = ...)] attributes.