promptgun 0.8.7 → 0.10.0

package/README.md

@@ -20,7 +20,7 @@ for await (const chunk of stream) {
 ```typescript
 const count /* type: boolean */ = await ai
   .chat('How many countries are in the EU')
-  .to(o => o.number())
+  .toNumber()
 ```
 Promptgun will both tell the LLM what shape its output data should be, parse that data to JS types and –if you use Typescript– return the matching Typescript type.
 
@@ -28,12 +28,10 @@ You can do this for types of any complexity:
 ```typescript
 const restaurants /* type: {name: string, address: string}[] */ = await ai
   .chat('Give 5 top restaurants in London')
-  .to(o => o
-    .array(e => e
-      .object(o => o
-        .hasString('name')
-        .hasString('address')
-      )
+  .toArray(o => o
+    .object(o => o
+      .hasString('name')
+      .hasString('address')
     )
   )
 ```
@@ -41,12 +39,10 @@ const restaurants /* type: {name: string, address: string}[] */ = await ai
 You can also put instructions to the LLM in your type spec:
 ```typescript
 const restaurants /* type: {name: string, address: string}[] */ = await ai
-  .chat('Give 5 top restaurants in London')
-  .to(o => o
-    .object(o => o
-      .hasString('name')
-      .hasString('description', 'A 50 character description')
-    )
+  .chat('Give the top restaurant in London')
+  .toObject(o => o
+    .hasString('name')
+    .hasString('description', 'A 50 character description')
   )
 ```
 
@@ -63,23 +59,19 @@ await ai
       )
     )
   )
-  .onElement(restaurantStream => restaurantStream
-    .onCompleteAs(restaurant => {
-      // do stuff every time a restaurant has come through
-    })
-  )
+  .onElement(restaurantStream /* type safe */ => {
+    console.log(await restaurantStream)
+  })
 ```
-#### Streamed, "dumb"
-You can also simply get the partial data, "what has come in so far". The data is parsed for you, even as the underlying JSON that is received is incomplete.
+
+And iterating (not awaiting) any streamed json element simply gives the stream of accumulated partial data, "what has come in so far" as it comes in. The data is parsed for you, even as the underlying JSON that is received is incomplete.
 ```typescript
 const parsedPartialJsonStream = ai
   .chat('What are the top 5 restaurants in New York City?')
-  .json(d => d
-    .canBeArray(el => el
-      .canBeObject(obj => obj
-        .hasString('name')
-        .hasString('address')
-      )
+  .toArray(o => o
+    .object(o => o
+      .hasString('name')
+      .hasString('address')
     )
   )
 for await (const parsedPartialJson of parsedPartialJsonStream) {
@@ -87,6 +79,25 @@ for await (const parsedPartialJson of parsedPartialJsonStream) {
 }
 ```
 
+### Image out
+```typescript
+await ai
+  .image('A black hole')
+  .imageSize('1024x1024') // optional
+  .model('gpt-image-1') // optional, default: gpt-image-1
+  .toFile('blackhole.png')
+```
+This writes the file, but it also returns a reference to that file:
+```typescript
+const file = await ai
+  .image('A black hole')
+  .toFile('blackhole.png')
+```
+You can also avoid writing a file altogether and get the byte array directly:
+```typescript
+const byteArray = await ai.image('A black hole')
+```
+
 ## Setup
 Before you do any prompts, do:
 ```typescript

package/build/index.d.ts

@@ -18,6 +18,7 @@ export declare class AIClient {
     chat<T extends undefined>(toPrompt: (args?: T) => Prompt): BasicPrompt<T>;
     chat<T>(toPrompt: (args: T) => Prompt, args: T): BasicPrompt<T>;
     chat<T = undefined>(toPrompt: (args?: T) => Prompt, args?: T): BasicPrompt<T>;
+    image(prompt: string): ImagePrompt;
 }
 
 export declare const AiModel: {
@@ -862,7 +863,12 @@ export declare class BasicPrompt<PSArgs> implements AsyncGenerator<string>, Prom
     finally(onfinally?: (() => void) | null | undefined): Promise<string>;
     get [Symbol.toStringTag](): string;
     to<Json extends AnyJson = AnyJson>(type: (value: EmptyTypeSpec<unknown>) => TypeSpec<Json>): JsonPrompt<PSArgs, Json>;
-    toJson(): JsonPrompt<PSArgs, AnyJson>;
+    toBoolean(): JsonPrompt<PSArgs, boolean>;
+    toString(): JsonPrompt<PSArgs, string>;
+    toNumber(): JsonPrompt<PSArgs, number>;
+    toObject<T_obj extends {}>(properties: (arg: TypeMemberSpec<{}>) => TypeMemberSpec<T_obj>): JsonPrompt<PSArgs, T_obj>;
+    toArray<T_arr extends AnyJson>(element: (arg: EmptyTypeSpec<unknown>) => TypeSpec<T_arr>): JsonPrompt<PSArgs, T_arr[]>;
+    toAny(): JsonPrompt<PSArgs, AnyJson>;
     private getResponseAsString;
 }
 
@@ -885,6 +891,8 @@ export declare type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
+export declare type ElementType<ArrayType extends AnyJson> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
+
 export declare class EmptyPropTypeSpec<T> extends PropTypeSpec<T> {
     array<T_arr = unknown>(element: (arg: EmptyTypeSpec<unknown>) => TypeSpec<T_arr>): FullPropTypeSpec<Combine<T, T_arr[]>>;
     object<T_obj extends {}>(properties: (arg: TypeMemberSpec<{}>) => TypeMemberSpec<T_obj>): FullPropTypeSpec<Combine<T, T_obj>>;
@@ -905,6 +913,7 @@ export declare class EmptyTypeSpec<T> extends TypeSpec<T> {
     constant<Value extends (string | number | boolean)>(value: Value, ...otherValues: Value[]): FullPropTypeSpec<Combine<T, Value>>;
     null(): FullTypeSpec<Combine<T, null>>;
     undefined(): FullTypeSpec<Combine<T, undefined>>;
+    any(): FullTypeSpec<Combine<T, AnyJson>>;
 }
 
 export declare class FullPropTypeSpec<T> extends PropTypeSpec<T> {
@@ -936,6 +945,52 @@ export declare type HandshakeData = {
     withinQuotum: boolean;
 };
 
+export declare class ImageFilePrompt implements Promise<File> {
+    private prompt;
+    private _model;
+    private _imageSize;
+    private fileName;
+    private aiClient;
+    constructor(prompt: string, _model: OpenaiImageModelId | undefined, _imageSize: ImageSize | undefined, fileName: string, aiClient: AIClient);
+    then<TResult1 = File, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<File | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<File>;
+    get [Symbol.toStringTag](): string;
+    model(model: OpenaiImageModelId): this;
+    /**
+     * The size of the generated images. Must be one of `1024x1024`, `1536x1024`
+     * (landscape), `1024x1536` (portrait), or `auto` (default value) for
+     * `gpt-image-1`, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and
+     * one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`.
+     */
+    size(imageSize: ImageSize): this;
+    private getResponseAsFile;
+}
+
+export declare class ImagePrompt implements Promise<Buffer> {
+    private prompt;
+    private _model;
+    private _imageSize;
+    private aiClient;
+    constructor(prompt: string, _model: OpenaiImageModelId | undefined, _imageSize: ImageSize | undefined, aiClient: AIClient);
+    then<TResult1 = Buffer, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<Buffer | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<Buffer>;
+    get [Symbol.toStringTag](): string;
+    model(model: OpenaiImageModelId): this;
+    /**
+     * The size of the generated images. Must be one of `1024x1024`, `1536x1024`
+     * (landscape), `1024x1536` (portrait), or `auto` (default value) for
+     * `gpt-image-1`, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and
+     * one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`.
+     */
+    size(imageSize: ImageSize): this;
+    toFile(fileName: string): ImageFilePrompt;
+    private getResponseAsString;
+}
+
+export declare type ImageSize = '1024x1024' | '1536x1024' | '1024x1536' | '256x256' | '512x512' | '1792x1024' | '1024x1792';
+
 export declare type JsonArray = AnyJson[];
 
 export declare type JsonExcerpt = {
@@ -947,7 +1002,7 @@ export declare type JsonObject = {
     [key: string]: AnyJson;
 };
 
-export declare class JsonPrompt<PSArgs, Json extends AnyJson = AnyJson> extends StreamedJsonChildElement implements AsyncGenerator<AnyJson>, Promise<Json> {
+export declare class JsonPrompt<PSArgs, Json extends AnyJson = AnyJson> extends StreamedJsonChildElement<Json> implements AsyncGenerator<AnyJson>, Promise<Json> {
     private aiClient;
     private promptSupplier;
     private promptSupplierArgs;
@@ -995,16 +1050,10 @@ export declare class JsonPrompt<PSArgs, Json extends AnyJson = AnyJson> extends
 
 export declare type Message = SystemMessage | UserMessage | AssistantMessage;
 
-export declare class ModelNotSupportedError extends Error {
-}
-
 export declare function newAIClient(promptGridApiKey: string): AIClient;
 
 export declare function newAIClient(config: PromptGunConfig): AIClient;
 
-export declare class NoAiCredientialsError extends Error {
-}
-
 export declare type NullType = BaseType<'null'>;
 
 export declare type NumberType = BaseType<'number'>;
@@ -1022,6 +1071,14 @@ export declare function obtainAiClientData(config: PromptGunConfig): {
     openai: Promise<string | undefined>;
 };
 
+export declare const OpenaiImageModel: {
+    readonly dall_e_2: "dall-e-2";
+    readonly dall_e_3: "dall-e-3";
+    readonly gpt_image_1: "gpt-image-1";
+};
+
+export declare type OpenaiImageModelId = (typeof OpenaiImageModel)[keyof typeof OpenaiImageModel];
+
 export declare type Opts = {
     model?: 'gpt-4o';
 };
@@ -1046,11 +1103,7 @@ export declare type PromptGunConfig = {
     apiKeys?: AccessTokens;
 };
 
-export declare function promptLLM<T>(args: T, toPrompt: (args: T) => Prompt): Flux<string>;
-
-export declare function promptLLM<T>(args: T, toPrompt: (args: T) => Prompt, json: true): StreamedJsonRootElement;
-
-export declare function promptLLM<T>(args: T, toPrompt: (args: T) => Prompt, json?: boolean): Flux<string> | StreamedJsonRootElement;
+export declare type PropType<ObjectType extends AnyJson, PropName extends string> = ObjectType extends Record<PropName, infer PropType extends AnyJson> ? PropType : never;
 
 export declare abstract class PropTypeSpec<T> extends TypeSpec<T> {
     private _comments;
@@ -1063,11 +1116,11 @@ export declare abstract class PropTypeSpec<T> extends TypeSpec<T> {
 
 export declare function setupAI(arg: string | PromptGunConfig): void;
 
-export declare class StreamedJsonChildElement extends StreamedJsonElement {
+export declare class StreamedJsonChildElement<T extends AnyJson> extends StreamedJsonElement<T> {
     constructor();
 }
 
-export declare abstract class StreamedJsonElement {
+export declare abstract class StreamedJsonElement<T extends AnyJson> implements Promise<T> {
     protected readonly receivedJson: string[];
     private readonly propertyCallbacks;
     private onElementCallbacks;
@@ -1076,19 +1129,24 @@ export declare abstract class StreamedJsonElement {
     private currentToken?;
     private state;
     private receivedExcerpts;
-    onElement(callback: (value: StreamedJsonElement) => void): this;
-    onProperty(propertyName: string, callback: (element: StreamedJsonElement) => void): this;
+    onElement(callback: (value: StreamedJsonElement<ElementType<T>>) => void): this;
+    onProperty<P extends string>(propertyName: P, callback: (element: StreamedJsonElement<PropType<T, P>>) => void): this;
     /**
      * @deprecated Does not work right now because FIELD_NAME
      * token comes after string value is already streaming
      */
-    onJsonStringProperty(propertyName: string, callback: (element: StreamedJsonElement) => void): this;
+    onJsonStringProperty<P extends string>(propertyName: P, callback: (element: StreamedJsonElement<PropType<T, P>>) => void): this;
     onEachExcerpt(callback: (value: JsonExcerpt) => void): this;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    get [Symbol.toStringTag](): string;
+    private getResponseAsPromise;
     /**
      * @param onComplete - a callback that will receive the complete JSON
      *                   string for this element once it's done streaming
      */
-    onComplete(onComplete: (value: string) => void): void;
+    private onComplete;
     private _onComplete;
     onCompleteAsync(onComplete: (value: string) => Promise<void>): void;
     onCompleteAs<T>(onComplete: (value: T) => void): void;
@@ -1111,7 +1169,7 @@ export declare abstract class StreamedJsonElement {
     private toAsync;
 }
 
-export declare class StreamedJsonRootElement extends StreamedJsonElement {
+export declare class StreamedJsonRootElement<T extends AnyJson> extends StreamedJsonElement<T> {
     protected readonly jsonTokenFlux: Flux<JsonExcerpt>;
     constructor(jsonTokenFlux: Flux<JsonExcerpt>);
     whenComplete(): Promise<string>;