promptgun 1.3.0 → 1.4.0

package/README.md

@@ -1,29 +1,34 @@
 # Promptgun
 
-The simplest, most advanced LLM prompting and agent library.
+The simplest, most advanced LLM prompting and agent client library for OpenAI:
+
+- **Type-safe** structured output, even when streaming
+- **Function calling / tools** with inline or reusable definitions
+- **Feedback loops**, response iteration based on response check
+- **Conversations**: trivally do multiple prompts while retaining context
+- **Strict JSON mode**: a prompting superpower for guaranteed schema compliance
+- **Image generation**: easy-to-use, well-documented, type-safe
+- **Live model docs right in your IDE**, hourly-updated from OpenAI website
+- Future: multi-provider support (drop me a message if you need it)
+
+For example:
 
 ```typescript
 const restaurants = ai
   .chat("Recommend 3 restaurants in Paris perfect for today's weather")
-  .tools(
-    defineTool({
-      name: 'get-weather',
-      parameters: spec => spec.string(),
-      function: async location => {
-        const response = await fetch(`https://api.weather.com/v1/current?location=${location}`)
-        return response.json()
-      }
-    })
-  )
-  .getArray(spec => spec.object(o => o
+  .tool('get-weather', s => s.string(), async loc => {
+    const res = await fetch(`https://api.weather.com/v1/current?location=${loc}`)
+    return res.json()
+  })
+  .getArray(s => s.object(o => o
     .hasString('name')
     .hasString('cuisine')
     .hasString('weatherReason', 'Why this restaurant fits today\'s weather')
   ))
 
-// Process each restaurant as it streams in
 for await (const restaurant of restaurants) {
-  console.log(`${restaurant.name} (${restaurant.cuisine}): ${restaurant.weatherReason}`)
+  // do stuff with a type-safe restaurant object,
+  // streamed as soon as they come in
 }
 ```
 
@@ -65,6 +70,7 @@ for await (const parsedPartialJson of parsedPartialJsonStream) {
 ```
 
 ### Data output - single
+Simply put `await` in front of your prompt to make it a single output rather than a streamed one:
 ```typescript
 const restaurants /* type: {name: string, address?: string}[] */ = await ai
   .chat('Give 5 top restaurants in London')
@@ -134,22 +140,21 @@ await conversation
   )
 ```
 
-## Response Validation with `.check()`
+## Response Iteration with `.check()`
 
-Validate AI responses and provide feedback for corrections. The AI will automatically retry with your feedback until validation passes or max attempts are reached.
+Iterate on AI responses by providing feedback for corrections. The AI will automatically retry with your feedback until validation passes or max attempts are reached.
 
 ### Basic Example
 ```typescript
 const password = await ai
   .chat("Generate a secure password")
-  .getObject(o => o.hasString('password'))
-  .check(response => {
-    const pwd = response.password;
-    if (pwd.length < 8) return 'Password must be at least 8 characters';
-    if (!/[A-Z]/.test(pwd)) return 'Password must contain uppercase letter';
-    if (!/[0-9]/.test(pwd)) return 'Password must contain a number';
+  .getObject(o => o.hasString('pwd'))
+  .check(({pwd}) => {
+    if (pwd.length < 8) return 'Password must be at least 8 characters'
+    if (!/[A-Z]/.test(pwd)) return 'Password must contain uppercase letter'
+    if (!/[0-9]/.test(pwd)) return 'Password must contain a number'
     // Return nothing/null/undefined when validation passes
-  }, 5); // Allow 5 attempts (default: 10)
+  }, 5) // Allow 5 attempts (default: 10)
 ```
 
 ### Multiple Checks
@@ -160,17 +165,18 @@ const user = await ai
   .getObject(o => o
     .hasString('email')
     .hasNumber('age')
-    .hasString('country'))
-  .check(response => {
-    if (!response.email.includes('@')) {
-      return 'Email must be valid';
+    .hasString('country')
+  )
+  .check(({email}) => {
+    if (!email.includes('@')) {
+      return 'Email must be valid'
     }
   }, 3)
-  .check(response => {
-    if (response.age < 0 || response.age > 150) {
-      return 'Age must be between 0 and 150';
+  .check(({age}) => {
+    if (age < 0 || age > 150) {
+      return 'Age must be between 0 and 150'
     }
-  }, 5);
+  }, 5)
 ```
 
 ### Error Handling
@@ -179,20 +185,20 @@ You can return errors as strings or throw them:
 const result = await ai
   .chat("Calculate the answer")
   .getObject(o => o.hasNumber('result'))
-  .check(response => {
+  .check(({result}) => {
     // Option 1: Return error string
-    if (response.result < 0) return 'Result must be positive';
+    if (result < 0) return 'Result must be positive'
 
     // Option 2: Throw error
-    if (response.result > 1000) {
-      throw new Error('Result too large');
+    if (result > 1000) {
+      throw new Error('Result too large')
     }
 
     // Option 3: Return array of errors
-    const errors = [];
-    if (response.result === 0) errors.push('Result cannot be zero');
-    if (errors.length > 0) return errors;
-  });
+    const errors = []
+    if (result === 0) errors.push('Result cannot be zero')
+    return errors
+  })
 ```
 
 ### Important Notes
@@ -201,6 +207,112 @@ const result = await ai
 - **Text responses**: `.check()` works with both JSON (`.getObject()`, `.getArray()`) and text responses
 - **Feedback loop**: Failed validations are sent back to the AI as feedback, allowing it to learn and correct
 
+## Tools
+
+### Inline Tool Definitions
+Tools can be added directly using `.tool()`:
+```typescript
+const result = await ai
+  .chat("What's the weather in Paris?")
+  .tool('get-weather', s => s.string(), async location => {
+    const res = await fetch(`https://api.weather.com/v1/current?location=${location}`)
+    return res.json()
+  })
+```
+
+### Reusable Tool Definitions
+For tools used across multiple prompts, define them once with `aiTool()`:
+```typescript
+const getWeather = aiTool('get-weather', s => s.string(), async location => {
+  const res = await fetch(`https://api.weather.com/v1/current?location=${location}`)
+  return res.json()
+})
+
+// Use in multiple prompts
+const parisWeather = await ai
+  .chat("What's the weather in Paris?")
+  .tools(getWeather)
+
+const londonWeather = await ai
+  .chat("What's the weather in London?")
+  .tools(getWeather)
+```
+
+You can pass multiple tools using `.tools()`:
+```typescript
+await ai
+  .chat("Plan a trip")
+  .tools(getWeather, getFlights, getHotels)
+```
+
+Or add them one by one with `.tool()`:
+```typescript
+await ai
+  .chat("Plan a trip")
+  .tool(getWeather)
+  .tool(getFlights)
+  .tool(getHotels)
+```
+
+## Strict JSON Mode
+
+Enable OpenAI's strict JSON mode for guaranteed type-safe responses using `.strict()`:
+```typescript
+const user = await ai
+  .chat("Get user info")
+  .getObject(o => o
+    .hasString('name')
+    .hasNumber('age')
+  )
+  .strict()
+```
+
+### Important: Nullable vs Optional Properties
+
+In strict mode, you **cannot use optional properties** (TypeScript's `?`). Instead, use nullable types:
+
+```typescript
+// ❌ Not allowed in strict mode - optional properties
+const user = await ai
+  .chat("Get user info")
+  .getObject(o => o
+    .hasString('name')
+    .canHaveString('nickname')  // ❌ This is {nickname?: string}
+  )
+  .strict()
+
+// ✅ Allowed in strict mode - nullable properties
+const user = await ai
+  .chat("Get user info")
+  .getObject(o => o
+    .hasString('name')
+    .has('nickname', s => s.string().orNull())  // ✅ This is {nickname: string | null}
+  )
+  .strict()
+```
+
+**The difference:**
+- **Optional** (`canHaveString`): Property may or may not exist → `{nickname?: string}` → Not allowed in strict mode
+- **Nullable** (`string().orNull()`): Property always exists but value can be null → `{nickname: string | null}` → Allowed in strict mode
+
+## Model Selection
+
+Switch models using either a string or the `AiModel` enum:
+
+```typescript
+// Using a string
+const result = await ai
+  .chat('Hello')
+  .model('gpt-5')
+
+// Using the enum - get in-place documentation!
+const result = await ai
+  .chat('Hello')
+  .model(AiModel.GPT_5)
+```
+
+**Why use the enum?** The `AiModel` enum provides in-place documentation for each model, updated hourly from the OpenAI website. This gives you real-time information about capabilities, context windows, and pricing right in your IDE.
+
 ## Other options
 Using the flex tier
 ```typescript

package/build/index.d.ts

@@ -1125,6 +1125,17 @@ export declare const AiModel: {
 
 export declare type AiModelId = (typeof AiModel)[keyof typeof AiModel];
 
+export declare function aiTool<T>(name: string, parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>, fn: ToolFunction<T>): ToolDefinition<T>;
+
+export declare function aiTool<T>(name: string, description: string, parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>, fn: ToolFunction<T>): ToolDefinition<T>;
+
+export declare function aiTool<T>(config: {
+    name: string;
+    description?: string;
+    parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>;
+    function: ToolFunction<T>;
+}): ToolDefinition<T>;
+
 export declare type AnyJson = string | null | boolean | number | JsonArray | JsonObject;
 
 export declare type ApiKeyChain = {
@@ -1246,17 +1257,16 @@ export declare class BasicPrompt<PSArgs> implements AsyncGenerator<string>, Prom
      * This error is propagated immediately without retry delays.
      *
      * @example
-     * Validate that a password guess meets requirements:
+     * Iterate on password generation until requirements are met:
      * ```ts
      * const result = await ai
      *   .chat("Generate a secure password")
-     *   .getObject(o => o.hasString('password'))
-     *   .check(response => {
-     *     const pwd = response.password;
-     *     if (pwd.length < 8) return 'Password must be at least 8 characters';
-     *     if (!/[A-Z]/.test(pwd)) return 'Password must contain uppercase letter';
-     *     if (!/[0-9]/.test(pwd)) return 'Password must contain a number';
-     *   }, 5);
+     *   .getObject(o => o.hasString('pwd'))
+     *   .check(({pwd}) => {
+     *     if (pwd.length < 8) return 'Password must be at least 8 characters'
+     *     if (!/[A-Z]/.test(pwd)) return 'Password must contain uppercase letter'
+     *     if (!/[0-9]/.test(pwd)) return 'Password must contain a number'
+     *   }, 5)
      * ```
      */
     check(check: CheckCallback<string>, attempts?: number): BasicPrompt<PSArgs>;
@@ -1280,6 +1290,14 @@ export declare class BasicPrompt<PSArgs> implements AsyncGenerator<string>, Prom
     getObject<T_obj extends {}>(properties: (arg: TypeMemberSpec<{}>) => TypeMemberSpec<T_obj>): JsonPrompt<PSArgs, T_obj>;
     getArray<T_arr extends AnyJson>(element: (arg: EmptyTypeSpec<unknown>) => TypeSpec<T_arr>): JsonArrayPrompt<PSArgs, T_arr>;
     getAny(): JsonPrompt<PSArgs, AnyJson>;
+    tool<T>(name: string, parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>, fn: ToolFunction<T>): BasicPrompt<PSArgs>;
+    tool<T>(name: string, description: string, parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>, fn: ToolFunction<T>): BasicPrompt<PSArgs>;
+    tool<T>(config: {
+        name: string;
+        description?: string;
+        parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>;
+        function: ToolFunction<T>;
+    }): BasicPrompt<PSArgs>;
     tools(tools: ToolDefinition[]): this;
     tools(...tools: (ToolDefinition | undefined)[]): this;
     private getResponseAsString;
@@ -1321,12 +1339,15 @@ export declare type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
-export declare function defineTool<T>(config: {
+/**
+ * @deprecated Use {@link aiTool} instead
+ */
+export declare function defineTool<T>(nameOrConfig: string | {
     name: string;
     description?: string;
     parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>;
     function: ToolFunction<T>;
-}): ToolDefinition<T>;
+}, parametersOrDescription?: string | ((spec: EmptyTypeSpec<unknown>) => TypeSpec<T>), fnOrParameters?: ToolFunction<T> | ((spec: EmptyTypeSpec<unknown>) => TypeSpec<T>), maybeFn?: ToolFunction<T>): ToolDefinition<T>;
 
 export declare type DeveloperMessage = {
     system?: undefined;
@@ -1613,21 +1634,22 @@ export declare class JsonPrompt<PSArgs, Json extends AnyJson = AnyJson> extends
      * This error is propagated immediately without retry delays.
      *
      * @example
-     * Validate JSON response structure:
+     * Iterate on JSON response until valid:
      * ```ts
      * const user = await ai
      *   .chat("Get user info for john@example.com")
      *   .getObject(o => o
      *     .hasString('email')
-     *     .hasNumber('age'))
-     *   .check(response => {
-     *     if (!response.email.includes('@')) {
-     *       return 'Email must be valid';
+     *     .hasNumber('age')
+     *   )
+     *   .check(({email, age}) => {
+     *     if (!email.includes('@')) {
+     *       return 'Email must be valid'
      *     }
-     *     if (response.age < 0 || response.age > 150) {
-     *       return 'Age must be between 0 and 150';
+     *     if (age < 0 || age > 150) {
+     *       return 'Age must be between 0 and 150'
      *     }
-     *   }, 3);
+     *   }, 3)
      * ```
      */
     check(check: CheckCallback<Json>, attempts?: number): JsonPrompt<PSArgs, Json>;
@@ -1639,6 +1661,14 @@ export declare class JsonPrompt<PSArgs, Json extends AnyJson = AnyJson> extends
     protected getResponse(): Promise<Json>;
     private _responseAsStringPromise?;
     protected getResponseAsString(): Promise<string>;
+    tool<T>(name: string, parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>, fn: ToolFunction<T>): JsonPrompt<PSArgs, Json>;
+    tool<T>(name: string, description: string, parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>, fn: ToolFunction<T>): JsonPrompt<PSArgs, Json>;
+    tool<T>(config: {
+        name: string;
+        description?: string;
+        parameters: (spec: EmptyTypeSpec<unknown>) => TypeSpec<T>;
+        function: ToolFunction<T>;
+    }): JsonPrompt<PSArgs, Json>;
     tools(tools: ToolDefinition[]): this;
     tools(...tools: (ToolDefinition | undefined)[]): this;
     protected _getResponseAsString(): Promise<string>;