OpenAI Client Module

This module provides a V client for interacting with OpenAI's API, allowing you to integrate OpenAI's services into your V applications.

Setup

1. Get your API key from OpenAI Platform
2. Configure the client using heroscript:

heroscript := '
!!openai.configure
    name:'default'
    openaikey:'your-api-key'    // Required: your OpenAI API key
    description:'My OpenAI API' // Optional
'

// Apply the configuration (only needs to be done once)
openai.play(heroscript: heroscript)!

Usage

Initialize Client

// Get a configured client instance
mut client := openai.get(name: 'something')!

// Or use default instance if name wasn't specified in configuration
mut client := openai.get()!

Examples

see examples/clients/openai

Complete Example

Here's a complete example showing common operations:

#!/usr/bin/env -S v run

import freeflowuniverse.crystallib.clients.openai

fn main() {
    // Get client instance (uses default if no name specified)
    mut client := openai.get()!

    // Your OpenAI API operations here
    // (Add specific operation examples once implemented)
}

fn get(args_ ArgsGet) !&OpenAIClient

fn heroscript_default() !string

fn play(args_ PlayArgs) !

fn switch(name string)

switch instance to be used for openai

fn (mut f OpenAIClient[Config]) cancel_fine_tune(fine_tune string) !FineTune

cancel a fine-tune that didn't finish yet

fn (mut f OpenAIClient[Config]) chat_completion(model_type ModelType, msgs Messages) !ChatCompletion

creates a new chat completion given a list of messages each message consists of message content and the role of the author

fn (mut f OpenAIClient[Config]) create_edit_image(args ImageEditArgs) !Images

edit images generation given a prompt and an existing image image needs to be in PNG format and transparent or else a mask of the same size needs to be specified to indicate where the image should be in the generated image the amount of images returned is specified by num_images

fn (mut f OpenAIClient[Config]) create_embeddings(args EmbeddingCreateArgs) !EmbeddingResponse

fn (mut f OpenAIClient[Config]) create_fine_tune(args FineTuneCreateArgs) !FineTune

creates a new fine-tune based on an already uploaded file

fn (mut f OpenAIClient[Config]) create_image(args ImageCreateArgs) !Images

Create new images generation given a prompt the amount of images returned is specified by num_images

fn (mut f OpenAIClient[Config]) create_moderation(input string, model ModerationModel) !ModerationResponse

fn (mut f OpenAIClient[Config]) create_tranlation(args AudioArgs) !AudioResponse

create translation to english from an audio file supported audio formats are mp3, mp4, mpeg, mpga, m4a, wav, or webm

fn (mut f OpenAIClient[Config]) create_transcription(args AudioArgs) !AudioResponse

create transcription from an audio file supported audio formats are mp3, mp4, mpeg, mpga, m4a, wav, or webm

fn (mut f OpenAIClient[Config]) create_variation_image(args ImageVariationArgs) !Images

create variations of the given image image needs to be in PNG format the amount of images returned is specified by num_images

fn (mut f OpenAIClient[Config]) delete_file(file_id string) !DeleteResp

deletes a file

fn (mut f OpenAIClient[Config]) get_file(file_id string) !File

returns a single file metadata

fn (mut f OpenAIClient[Config]) get_file_content(file_id string) !string

returns the content of a specific file

fn (mut f OpenAIClient[Config]) get_fine_tune(fine_tune string) !FineTune

get a single fine-tune information

fn (mut f OpenAIClient[Config]) get_model(model string) !Model

returns details of a model using the model id

fn (mut f OpenAIClient[Config]) list_files() !Files

list all files in client org

fn (mut f OpenAIClient[Config]) list_fine_tune_events(fine_tune string) !FineTuneEventList

returns all events for a fine tune in this account

fn (mut f OpenAIClient[Config]) list_fine_tunes() !FineTuneList

returns all fine-tunes in this account

fn (mut f OpenAIClient[Config]) list_models() !Models

list current models available in Open AI

fn (mut f OpenAIClient[Config]) upload_file(args FileUploadArgs) !File

upload file to client org, usually used for fine tuning

enum AudioRespType {
	json
	text
	srt
	verbose_json
	vtt
}

enum EmbeddingModel {
	text_embedding_ada
}

enum ImageRespType {
	url
	b64_json
}

enum ImageSize {
	size_256_256
	size_512_512
	size_1024_1024
}

enum ModelType {
	gpt_4_1106_preview
	gpt_4_vision_preview
	gpt_4
	gpt_4_32k
	gpt_3_5_turbo_1106
	gpt_3_5_turbo
	gpt_3_5_turbo_16k
	whisper_1
}

enum ModerationModel {
	text_moderation_latest
	text_moderation_stable
}

enum RoleType {
	system
	user
	assistant
	function
}

struct ArgsGet {
pub mut:
	name string = 'default'
}

///////FACTORY

struct AudioArgs {
pub mut:
	filepath        string
	prompt          string
	response_format AudioRespType
	temperature     int
	language        string
}

struct AudioResponse {
pub mut:
	text string
}

struct ChatCompletion {
pub mut:
	id      string
	object  string
	created u32
	choices []Choice
	usage   Usage
}

struct Choice {
pub mut:
	index         int
	message       MessageRaw
	finish_reason string
}

struct DeleteResp {
pub mut:
	id      string
	object  string
	deleted bool
}

struct Embedding {
pub mut:
	object    string
	embedding []f32
	index     int
}

struct EmbeddingCreateArgs {
	input []string       @[required]
	model EmbeddingModel @[required]
	user  string
}

struct EmbeddingResponse {
pub mut:
	object string
	data   []Embedding
	model  string
	usage  Usage
}

struct File {
pub mut:
	id         string
	object     string
	bytes      int
	created_at int
	filename   string
	purpose    string
}

struct FileUploadArgs {
pub:
	filepath string
	purpose  string
}

struct Files {
pub mut:
	data []File
}

struct FineTune {
pub:
	id               string
	object           string
	model            string
	created_at       int
	events           []FineTuneEvent
	fine_tuned_model string
	hyperparams      FineTuneHyperParams
	organization_id  string
	result_files     []File
	status           string
	validation_files []File
	training_files   []File
	updated_at       int
}

struct FineTuneCreateArgs {
pub mut:
	training_file                  string @[required]
	model                          string
	n_epochs                       int = 4
	batch_size                     int
	learning_rate_multiplier       f32
	prompt_loss_weight             f64
	compute_classification_metrics bool
	suffix                         string
}

struct FineTuneEvent {
pub:
	object     string
	created_at int
	level      string
	message    string
}

struct FineTuneEventList {
pub:
	object string
	data   []FineTuneEvent
}

struct FineTuneHyperParams {
pub:
	batch_size               int
	learning_rate_multiplier f64
	n_epochs                 int
	prompt_loss_weight       f64
}

struct FineTuneList {
pub:
	object string
	data   []FineTune
}

struct ImageCreateArgs {
pub mut:
	prompt     string
	num_images int
	size       ImageSize
	format     ImageRespType
	user       string
}

struct ImageEditArgs {
pub mut:
	image_path string
	mask_path  string
	prompt     string
	num_images int
	size       ImageSize
	format     ImageRespType
	user       string
}

struct ImageRequest {
pub mut:
	prompt          string
	n               int
	size            string
	response_format string
	user            string
}

struct ImageResponse {
pub mut:
	url      string
	b64_json string
}

struct ImageVariationArgs {
pub mut:
	image_path string
	num_images int
	size       ImageSize
	format     ImageRespType
	user       string
}

struct Images {
pub mut:
	created int
	data    []ImageResponse
}

struct Message {
pub mut:
	role    RoleType
	content string
}

struct MessageRaw {
pub mut:
	role    string
	content string
}

struct Messages {
pub mut:
	messages []Message
}

struct Model {
pub mut:
	id         string
	created    int
	object     string
	owned_by   string
	root       string
	parent     string
	permission []ModelPermission
}

struct ModelPermission {
pub mut:
	id                   string
	created              int
	object               string
	allow_create_engine  bool
	allow_sampling       bool
	allow_logprobs       bool
	allow_search_indices bool
	allow_view           bool
	allow_fine_tuning    bool
	organization         string
	is_blocking          bool
}

struct Models {
pub mut:
	data []Model
}

struct ModerationRequest {
mut:
	input string
	model string
}

struct ModerationResponse {
pub mut:
	id      string
	model   string
	results []ModerationResult
}

struct ModerationResult {
pub mut:
	categories      ModerationResultCategories
	category_scores ModerationResultCategoryScores
	flagged         bool
}

struct ModerationResultCategories {
pub mut:
	sexual                 bool
	hate                   bool
	harassment             bool
	selfharm               bool @[json: 'self-harm']
	sexual_minors          bool @[json: 'sexual/minors']
	hate_threatening       bool @[json: 'hate/threatening']
	violence_graphic       bool @[json: 'violence/graphic']
	selfharm_intent        bool @[json: 'self-harm/intent']
	selfharm_instructions  bool @[json: 'self-harm/instructions']
	harassment_threatening bool @[json: 'harassment/threatening']
	violence               bool
}

struct ModerationResultCategoryScores {
pub mut:
	sexual                 f32
	hate                   f32
	harassment             f32
	selfharm               f32 @[json: 'self-harm']
	sexual_minors          f32 @[json: 'sexual/minors']
	hate_threatening       f32 @[json: 'hate/threatening']
	violence_graphic       f32 @[json: 'violence/graphic']
	selfharm_intent        f32 @[json: 'self-harm/intent']
	selfharm_instructions  f32 @[json: 'self-harm/instructions']
	harassment_threatening f32 @[json: 'harassment/threatening']
	violence               f32
}

struct OpenAIClient {
pub mut:
	name        string = 'default'
	openaikey   string @[secret]
	description string
	url         string
	conn        ?&httpconnection.HTTPConnection
}

fn (mut client OpenAIClient) connection() !&httpconnection.HTTPConnection

struct PlayArgs {
pub mut:
	name       string = 'default'
	heroscript string // if filled in then plbook will be made out of it
	plbook     ?playbook.PlayBook
	reset      bool
	start      bool
	stop       bool
	restart    bool
	delete     bool
	configure  bool // make sure there is at least one installed
}

struct Usage {
pub mut:
	prompt_tokens     int
	completion_tokens int
	total_tokens      int
}