Expand description
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§
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§
- Exact
Length - A
Validator
that creates a constraint that the string must be exactly a certain length. - Indexed
Array IndexedArray
is a wrapper around aVec
that should be used when you want to enforce a particular length.- Magic
Instantiate Parameters - 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. - Model
Settings - Type
Script Accumulator - 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§
Traits§
- Client
Instantiate - An extension trait for
OpenAIClient
that adds a method to instantiate a value. - Magic
Instantiate - 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 typeT
.
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§
- Magic
Instantiate - 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.