@rcrsr/rill-ext-openai 0.8.6 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @rcrsr/rill-ext-openai
 
-[rill](https://rill.run) extension for [OpenAI](https://platform.openai.com/docs) API integration. Provides `message`, `messages`, `embed`, `embed_batch`, and `tool_loop` host functions. Compatible with any OpenAI-compatible server (LM Studio, Ollama, vLLM).
+[rill](https://rill.run) extension for [OpenAI](https://platform.openai.com/docs) API integration. Provides `message`, `messages`, `embed`, `embed_batch`, `tool_loop`, and `generate` host functions. Compatible with any OpenAI-compatible server (LM Studio, Ollama, vLLM).
 
 > **Experimental.** Breaking changes will occur before stabilization.
 
@@ -20,7 +20,7 @@ import { createOpenAIExtension } from '@rcrsr/rill-ext-openai';
 
 const ext = createOpenAIExtension({
   api_key: process.env.OPENAI_API_KEY!,
-  model: 'gpt-4-turbo',
+  model: 'gpt-4o',
 });
 const prefixed = prefixFunctions('openai', ext);
 const { dispose, ...functions } = prefixed;
@@ -36,134 +36,15 @@ const result = await execute(parse(script), ctx);
 dispose?.();
 ```
 
-## Host Functions
-
-All functions return a dict with `content`, `model`, `usage`, `stop_reason`, `id`, and `messages`.
-
-### openai::message(text, options?)
-
-Send a single message to OpenAI.
-
-```rill
-openai::message("Analyze this code for security issues") => $response
-$response.content -> log
-$response.usage.output -> log
-```
-
-### openai::messages(messages, options?)
-
-Send a multi-turn conversation.
-
-```rill
-openai::messages([
-  [role: "user", content: "What is rill?"],
-  [role: "assistant", content: "A scripting language for AI agents."],
-  [role: "user", content: "Show me an example."]
-]) => $response
-$response.content -> log
-```
-
-### openai::embed(text)
-
-Generate an embedding vector for text. Requires `embed_model` in config.
-
-```rill
-openai::embed("Hello world") => $vector
-```
-
-### openai::embed_batch(texts)
-
-Generate embedding vectors for multiple texts in a single API call.
-
-```rill
-openai::embed_batch(["Hello", "World"]) => $vectors
-```
-
-### openai::tool_loop(prompt, options)
-
-Execute a tool-use loop where the model calls rill functions iteratively.
-
-```rill
-openai::tool_loop("Find the weather", [tools: $my_tools]) => $result
-$result.content -> log
-$result.turns -> log
-```
-
-## Configuration
-
-```typescript
-const ext = createOpenAIExtension({
-  api_key: process.env.OPENAI_API_KEY!,
-  model: 'gpt-4-turbo',
-  temperature: 0.7,
-  base_url: 'http://localhost:1234/v1', // OpenAI-compatible server
-  max_tokens: 4096,
-  max_retries: 3,
-  timeout: 30000,
-  system: 'You are a helpful assistant.',
-  embed_model: 'text-embedding-3-small',
-});
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `api_key` | string | required | OpenAI API key |
-| `model` | string | required | Model identifier |
-| `temperature` | number | undefined | Temperature (0.0-2.0) |
-| `base_url` | string | undefined | Custom API endpoint URL |
-| `max_tokens` | number | `4096` | Max tokens in response |
-| `max_retries` | number | undefined | Max retry attempts |
-| `timeout` | number | undefined | Request timeout in ms |
-| `system` | string | undefined | Default system prompt |
-| `embed_model` | string | undefined | Embedding model identifier |
-
-## Result Shape
-
-```typescript
-interface OpenAIResult {
-  content: string;     // response text
-  model: string;       // model used
-  usage: {
-    input: number;     // prompt tokens
-    output: number;    // completion tokens
-  };
-  stop_reason: string; // finish reason
-  id: string;          // request ID
-  messages: Array<{    // full conversation history
-    role: string;
-    content: string;
-  }>;
-}
-```
-
-## Lifecycle
-
-Call `dispose()` on the extension to cancel pending requests:
-
-```typescript
-const ext = createOpenAIExtension({ ... });
-// ... use extension ...
-await ext.dispose?.();
-```
-
-## Test Host
-
-A runnable example at `examples/test-host.ts` wires up the extension with the rill runtime:
-
-```bash
-pnpm exec tsx examples/test-host.ts
-pnpm exec tsx examples/test-host.ts -e 'openai::message("Tell me a joke") -> log'
-pnpm exec tsx examples/test-host.ts script.rill
-```
+## Documentation
 
-Requires `OPENAI_API_KEY` environment variable (or `--base-url` for local servers).
+See [full documentation](docs/extension-llm-openai.md) for configuration, functions, error handling, events, and examples.
 
-## Documentation
+## Related
 
-| Document | Description |
-|----------|-------------|
-| [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) | Extension contract and patterns |
-| [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) | Runtime context and host functions |
+- [rill](https://github.com/rcrsr/rill) — Core language runtime
+- [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) — Extension contract and patterns
+- [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) — Runtime context and host functions
 
 ## License
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { ExtensionResult } from '@rcrsr/rill';
+import { ExtensionConfigSchema, ExtensionResult } from '@rcrsr/rill';
 
 /**
  * Base configuration for LLM extensions
@@ -73,12 +73,8 @@ export type OpenAIExtensionConfig = LLMProviderConfig;
  * ```
  */
 export declare function createOpenAIExtension(config: OpenAIExtensionConfig): ExtensionResult;
-/**
- * @rcrsr/rill-ext-openai
- *
- * Extension for OpenAI API integration with rill scripts.
- */
 export declare const VERSION = "0.0.1";
+export declare const configSchema: ExtensionConfigSchema;
 
 export {
 	LLMProviderConfig as LLMExtensionConfig,

package/dist/index.js

@@ -1,10 +1,10 @@
 // src/factory.ts
 import OpenAI from "openai";
 import {
-  RuntimeError as RuntimeError4,
+  RuntimeError as RuntimeError6,
   emitExtensionEvent,
   createVector,
-  isCallable as isCallable2,
+  isDict as isDict2,
   isVector
 } from "@rcrsr/rill";
 
@@ -76,29 +76,152 @@ function mapProviderError(providerName, error, detect) {
 }
 
 // ../../shared/ext-llm/dist/tool-loop.js
-import { isCallable, isDict, RuntimeError as RuntimeError3 } from "@rcrsr/rill";
+import { invokeCallable, isCallable, isDict, isRuntimeCallable, RuntimeError as RuntimeError4 } from "@rcrsr/rill";
+
+// ../../shared/ext-llm/dist/schema.js
+import { RuntimeError as RuntimeError3 } from "@rcrsr/rill";
+var RILL_TYPE_MAP = {
+  string: "string",
+  number: "number",
+  bool: "boolean",
+  list: "array",
+  dict: "object",
+  vector: "object",
+  shape: "object"
+};
+function mapRillType(rillType) {
+  const jsonType = RILL_TYPE_MAP[rillType];
+  if (jsonType === void 0) {
+    throw new RuntimeError3("RILL-R004", `unsupported type: ${rillType}`);
+  }
+  return jsonType;
+}
+function buildPropertyFromStructuralType(rillType) {
+  if (rillType.type === "closure" || rillType.type === "tuple") {
+    throw new RuntimeError3("RILL-R004", `unsupported type for JSON Schema: ${rillType.type}`);
+  }
+  if (rillType.type === "any") {
+    return {};
+  }
+  if (rillType.type === "list") {
+    const property = { type: "array" };
+    if (rillType.element !== void 0) {
+      property.items = buildPropertyFromStructuralType(rillType.element);
+    }
+    return property;
+  }
+  if (rillType.type === "dict") {
+    return { type: "object" };
+  }
+  return { type: mapRillType(rillType.type) };
+}
+function buildJsonSchemaFromStructuralType(type, params) {
+  const properties = {};
+  const required = [];
+  if (type.type === "closure") {
+    const closureParams = type.params ?? [];
+    for (let i = 0; i < closureParams.length; i++) {
+      const [paramName, paramType] = closureParams[i];
+      const rillParam = params?.[i];
+      const property = buildPropertyFromStructuralType(paramType);
+      const description = rillParam?.annotations["description"];
+      if (typeof description === "string") {
+        property.description = description;
+      }
+      const enumAnnotation = rillParam?.annotations["enum"];
+      if (Array.isArray(enumAnnotation)) {
+        property.enum = enumAnnotation;
+      }
+      properties[paramName] = property;
+      if (rillParam === void 0 || rillParam.defaultValue === void 0) {
+        required.push(paramName);
+      }
+    }
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+function buildJsonSchema(rillSchema) {
+  const properties = {};
+  const required = [];
+  for (const [key, value] of Object.entries(rillSchema)) {
+    if (typeof value === "string") {
+      properties[key] = buildProperty(value);
+    } else if (typeof value === "object" && value !== null) {
+      properties[key] = buildProperty(value);
+    } else {
+      throw new RuntimeError3("RILL-R004", `unsupported type: ${String(value)}`);
+    }
+    required.push(key);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+function buildProperty(descriptor) {
+  if (typeof descriptor === "string") {
+    const jsonType2 = mapRillType(descriptor);
+    return { type: jsonType2 };
+  }
+  const rillType = descriptor["type"];
+  if (typeof rillType !== "string") {
+    throw new RuntimeError3("RILL-R004", `unsupported type: ${String(rillType)}`);
+  }
+  const jsonType = mapRillType(rillType);
+  const property = { type: jsonType };
+  const description = descriptor["description"];
+  if (typeof description === "string") {
+    property.description = description;
+  }
+  if ("enum" in descriptor) {
+    if (rillType !== "string") {
+      throw new RuntimeError3("RILL-R004", "enum is only valid for string type");
+    }
+    const enumValues = descriptor["enum"];
+    if (Array.isArray(enumValues)) {
+      property.enum = enumValues;
+    }
+  }
+  if (rillType === "list" && "items" in descriptor) {
+    const items = descriptor["items"];
+    if (typeof items === "string") {
+      property.items = buildProperty(items);
+    } else if (typeof items === "object" && items !== null) {
+      property.items = buildProperty(items);
+    }
+  }
+  if (rillType === "dict" && "properties" in descriptor) {
+    const nestedProps = descriptor["properties"];
+    if (typeof nestedProps === "object" && nestedProps !== null) {
+      const subSchema = buildJsonSchema(nestedProps);
+      property.properties = subSchema.properties;
+      property.required = subSchema.required;
+      property.additionalProperties = false;
+    }
+  }
+  return property;
+}
+
+// ../../shared/ext-llm/dist/tool-loop.js
 async function executeToolCall(toolName, toolInput, tools, context) {
   if (!isDict(tools)) {
-    throw new RuntimeError3("RILL-R004", "tools must be a dict mapping tool names to functions");
+    throw new RuntimeError4("RILL-R004", "tool_loop: tools must be a dict of name \u2192 callable");
   }
   const toolsDict = tools;
   const toolFn = toolsDict[toolName];
   if (toolFn === void 0 || toolFn === null) {
-    throw new RuntimeError3("RILL-R004", `Unknown tool: ${toolName}`);
+    throw new RuntimeError4("RILL-R004", `Unknown tool: ${toolName}`);
   }
   if (!isCallable(toolFn)) {
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: tool must be callable`);
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: tool must be callable`);
   }
   if (typeof toolInput !== "object" || toolInput === null) {
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: input must be an object`);
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: input must be an object`);
   }
   const callable = toolFn;
-  if (callable.kind !== "runtime" && callable.kind !== "application") {
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: tool must be application or runtime callable`);
+  if (callable.kind !== "runtime" && callable.kind !== "application" && callable.kind !== "script") {
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: tool must be application, runtime, or script callable`);
   }
   try {
     let args;
-    if (callable.kind === "application" && callable.params) {
+    if ((callable.kind === "application" || callable.kind === "script") && callable.params && callable.params.length > 0) {
       const params = callable.params;
       const inputDict = toolInput;
       args = params.map((param) => {
@@ -108,6 +231,12 @@ async function executeToolCall(toolName, toolInput, tools, context) {
     } else {
       args = [toolInput];
     }
+    if (callable.kind === "script") {
+      if (!context) {
+        throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: script callable requires a runtime context`);
+      }
+      return await invokeCallable(callable, args, context);
+    }
     const ctx = context ?? {
       parent: void 0,
       variables: /* @__PURE__ */ new Map(),
@@ -116,77 +245,122 @@ async function executeToolCall(toolName, toolInput, tools, context) {
     const result = callable.fn(args, ctx);
     return result instanceof Promise ? await result : result;
   } catch (error) {
-    if (error instanceof RuntimeError3) {
+    if (error instanceof RuntimeError4) {
       throw error;
     }
     const message = error instanceof Error ? error.message : "Unknown error";
-    throw new RuntimeError3("RILL-R004", `Invalid tool input for ${toolName}: ${message}`);
+    throw new RuntimeError4("RILL-R004", `Invalid tool input for ${toolName}: ${message}`);
+  }
+}
+function sanitizeToolName(name) {
+  const match = name.match(/^[a-zA-Z0-9_-]*/);
+  const sanitized = match ? match[0] : "";
+  return sanitized.length > 0 ? sanitized : name;
+}
+function patchResponseToolCallNames(response, nameMap) {
+  if (!nameMap.size || !response || typeof response !== "object")
+    return;
+  const resp = response;
+  if (Array.isArray(resp["choices"])) {
+    for (const choice of resp["choices"]) {
+      const msg = choice?.["message"];
+      const tcs = msg?.["tool_calls"];
+      if (Array.isArray(tcs)) {
+        for (const tc of tcs) {
+          const fn = tc?.["function"];
+          if (fn && typeof fn["name"] === "string") {
+            const orig = fn["name"];
+            const san = nameMap.get(orig);
+            if (san !== void 0)
+              fn["name"] = san;
+          }
+        }
+      }
+    }
+  }
+  if (Array.isArray(resp["content"])) {
+    for (const block of resp["content"]) {
+      const b = block;
+      if (b?.["type"] === "tool_use" && typeof b?.["name"] === "string") {
+        const orig = b["name"];
+        const san = nameMap.get(orig);
+        if (san !== void 0)
+          b["name"] = san;
+      }
+    }
+  }
+  if (Array.isArray(resp["functionCalls"])) {
+    for (const fc of resp["functionCalls"]) {
+      const f = fc;
+      if (typeof f?.["name"] === "string") {
+        const orig = f["name"];
+        const san = nameMap.get(orig);
+        if (san !== void 0)
+          f["name"] = san;
+      }
+    }
+  }
+  if (Array.isArray(resp["candidates"])) {
+    for (const cand of resp["candidates"]) {
+      const content = cand?.["content"];
+      const parts = content?.["parts"];
+      if (Array.isArray(parts)) {
+        for (const part of parts) {
+          const fc = part?.["functionCall"];
+          if (fc && typeof fc["name"] === "string") {
+            const orig = fc["name"];
+            const san = nameMap.get(orig);
+            if (san !== void 0)
+              fc["name"] = san;
+          }
+        }
+      }
+    }
   }
 }
 async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent, maxTurns = 10, context) {
   if (tools === void 0) {
-    throw new RuntimeError3("RILL-R004", "tools parameter is required");
+    throw new RuntimeError4("RILL-R004", "tools parameter is required");
   }
   if (!isDict(tools)) {
-    throw new RuntimeError3("RILL-R004", "tools must be a dict mapping tool names to functions");
+    throw new RuntimeError4("RILL-R004", "tool_loop: tools must be a dict of name \u2192 callable");
   }
   const toolsDict = tools;
   const toolDescriptors = Object.entries(toolsDict).map(([name, fn]) => {
     const fnValue = fn;
+    if (isRuntimeCallable(fnValue)) {
+      throw new RuntimeError4("RILL-R004", `tool_loop: builtin "${name}" cannot be used as a tool \u2014 wrap in a closure`);
+    }
     if (!isCallable(fnValue)) {
-      throw new RuntimeError3("RILL-R004", `tool '${name}' must be callable function`);
+      throw new RuntimeError4("RILL-R004", `tool_loop: tool "${name}" is not a callable`);
     }
     const callable = fnValue;
-    const description = callable.kind === "application" && callable.description ? callable.description : "";
-    const properties = {};
-    const required = [];
-    if (callable.kind === "application" && callable.params) {
-      for (const param of callable.params) {
-        let jsonSchemaType;
-        switch (param.typeName) {
-          case "string":
-            jsonSchemaType = "string";
-            break;
-          case "number":
-            jsonSchemaType = "number";
-            break;
-          case "bool":
-            jsonSchemaType = "boolean";
-            break;
-          case "list":
-            jsonSchemaType = "array";
-            break;
-          case "dict":
-          case "vector":
-            jsonSchemaType = "object";
-            break;
-          case null:
-            jsonSchemaType = "string";
-            break;
-          default:
-            jsonSchemaType = "string";
-            break;
-        }
-        const property = {
-          type: jsonSchemaType
-        };
-        if (param.description) {
-          property["description"] = param.description;
-        }
-        properties[param.name] = property;
-        if (param.defaultValue === null) {
-          required.push(param.name);
-        }
-      }
+    let description;
+    if (callable.kind === "script") {
+      description = callable.annotations["description"] ?? "";
+    } else {
+      description = callable.description ?? "";
+    }
+    let inputSchema;
+    const params = callable.kind === "application" ? callable.params ?? [] : callable.kind === "script" ? callable.params : [];
+    if (params.length > 0) {
+      const closureType = {
+        type: "closure",
+        params: params.map((p2) => [p2.name, p2.type ?? { type: "any" }])
+      };
+      const builtSchema = buildJsonSchemaFromStructuralType(closureType, [...params]);
+      inputSchema = {
+        type: "object",
+        properties: builtSchema.properties,
+        required: builtSchema.required
+      };
+    } else {
+      inputSchema = { type: "object", properties: {}, required: [] };
     }
     return {
       name,
       description,
-      input_schema: {
-        type: "object",
-        properties,
-        required
-      }
+      input_schema: inputSchema
     };
   });
   const providerTools = callbacks.buildTools(toolDescriptors);
@@ -203,7 +377,7 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
       response = await callbacks.callAPI(currentMessages, providerTools);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
-      throw new RuntimeError3("RILL-R004", `Provider API error: ${message}`, void 0, { cause: error });
+      throw new RuntimeError4("RILL-R004", `Provider API error: ${message}`, void 0, { cause: error });
     }
     if (typeof response === "object" && response !== null && "usage" in response) {
       const usage = response["usage"];
@@ -215,7 +389,17 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
         totalOutputTokens += outputTokens;
       }
     }
-    const toolCalls = callbacks.extractToolCalls(response);
+    const rawToolCalls = callbacks.extractToolCalls(response);
+    const nameMap = /* @__PURE__ */ new Map();
+    const toolCalls = rawToolCalls?.map((tc) => {
+      const sanitized = sanitizeToolName(tc.name);
+      if (sanitized !== tc.name)
+        nameMap.set(tc.name, sanitized);
+      return sanitized !== tc.name ? { ...tc, name: sanitized } : tc;
+    }) ?? null;
+    if (nameMap.size > 0) {
+      patchResponseToolCallNames(response, nameMap);
+    }
     if (toolCalls === null || toolCalls.length === 0) {
       return {
         response,
@@ -240,7 +424,7 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
         const duration = Date.now() - toolStartTime;
         consecutiveErrors++;
         let originalError;
-        if (error instanceof RuntimeError3) {
+        if (error instanceof RuntimeError4) {
           const prefix = `Invalid tool input for ${name}: `;
           if (error.message.startsWith(prefix)) {
             originalError = error.message.slice(prefix.length);
@@ -265,12 +449,20 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
           duration
         });
         if (consecutiveErrors >= maxErrors) {
-          throw new RuntimeError3("RILL-R004", `Tool execution failed: ${maxErrors} consecutive errors`);
+          throw new RuntimeError4("RILL-R004", `Tool execution failed: ${maxErrors} consecutive errors (last: ${name}: ${originalError})`);
         }
       }
     }
+    const assistantMessage = callbacks.formatAssistantMessage(response);
+    if (assistantMessage != null) {
+      currentMessages.push(assistantMessage);
+    }
     const toolResultMessage = callbacks.formatToolResult(toolResults);
-    currentMessages.push(toolResultMessage);
+    if (Array.isArray(toolResultMessage)) {
+      currentMessages.push(...toolResultMessage);
+    } else {
+      currentMessages.push(toolResultMessage);
+    }
   }
   return {
     response: null,
@@ -280,8 +472,128 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
   };
 }
 
+// ../../shared/ext-param/dist/param.js
+import { RuntimeError as RuntimeError5 } from "@rcrsr/rill";
+function validateParamName(name) {
+  if (name === "") {
+    throw new RuntimeError5("RILL-R001", "param name must not be empty");
+  }
+  if (/\s/.test(name)) {
+    throw new RuntimeError5("RILL-R001", "param name must be a valid identifier");
+  }
+}
+function buildAnnotations(desc) {
+  if (desc !== void 0) {
+    return { description: desc };
+  }
+  return {};
+}
+var p = {
+  /**
+   * IR-1: Creates a string parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @returns RillParam with type 'string'
+   */
+  str(name, desc) {
+    validateParamName(name);
+    return {
+      name,
+      type: { type: "string" },
+      defaultValue: void 0,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-2: Creates a number parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @param def - Optional default value
+   * @returns RillParam with type 'number'
+   */
+  num(name, desc, def) {
+    validateParamName(name);
+    return {
+      name,
+      type: { type: "number" },
+      defaultValue: def,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-3: Creates a boolean parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @param def - Optional default value
+   * @returns RillParam with type 'bool'
+   */
+  bool(name, desc, def) {
+    validateParamName(name);
+    return {
+      name,
+      type: { type: "bool" },
+      defaultValue: def,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-4: Creates a dict parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @param def - Optional default value
+   * @returns RillParam with type 'dict'
+   */
+  dict(name, desc, def) {
+    validateParamName(name);
+    return {
+      name,
+      type: { type: "dict" },
+      defaultValue: def,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-5: Creates a list parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param itemType - Optional element type; omitted when not provided
+   * @param desc - Optional description
+   * @returns RillParam with type 'list' (with element if itemType provided)
+   */
+  list(name, itemType, desc) {
+    validateParamName(name);
+    const type = itemType !== void 0 ? { type: "list", element: itemType } : { type: "list" };
+    return {
+      name,
+      type,
+      defaultValue: void 0,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-6: Creates a callable parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @returns RillParam with type 'closure'
+   */
+  callable(name, desc) {
+    validateParamName(name);
+    return {
+      name,
+      type: { type: "closure" },
+      defaultValue: void 0,
+      annotations: buildAnnotations(desc)
+    };
+  }
+};
+
 // src/factory.ts
-var DEFAULT_MAX_TOKENS = 4096;
+var DEFAULT_MAX_COMPLETION_TOKENS = 4096;
 var detectOpenAIError = (error) => {
   if (error instanceof OpenAI.APIError) {
     return {
@@ -303,7 +615,7 @@ function createOpenAIExtension(config) {
   });
   const factoryModel = config.model;
   const factoryTemperature = config.temperature;
-  const factoryMaxTokens = config.max_tokens ?? DEFAULT_MAX_TOKENS;
+  const factoryMaxTokens = config.max_tokens ?? DEFAULT_MAX_COMPLETION_TOKENS;
   const factorySystem = config.system;
   const factoryEmbedModel = config.embed_model;
   void factoryEmbedModel;
@@ -328,8 +640,8 @@ function createOpenAIExtension(config) {
     // IR-4: openai::message
     message: {
       params: [
-        { name: "text", type: "string" },
-        { name: "options", type: "dict", defaultValue: {} }
+        p.str("text"),
+        p.dict("options", void 0, {})
       ],
       fn: async (args, ctx) => {
         const startTime = Date.now();
@@ -337,7 +649,7 @@ function createOpenAIExtension(config) {
           const text = args[0];
           const options = args[1] ?? {};
           if (text.trim().length === 0) {
-            throw new RuntimeError4("RILL-R004", "prompt text cannot be empty");
+            throw new RuntimeError6("RILL-R004", "prompt text cannot be empty");
           }
           const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
           const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
@@ -354,7 +666,7 @@ function createOpenAIExtension(config) {
           });
           const apiParams = {
             model: factoryModel,
-            max_tokens: maxTokens,
+            max_completion_tokens: maxTokens,
             messages: apiMessages
           };
           if (factoryTemperature !== void 0) {
@@ -383,7 +695,9 @@ function createOpenAIExtension(config) {
             subsystem: "extension:openai",
             duration,
             model: response.model,
-            usage: result2.usage
+            usage: result2.usage,
+            request: apiMessages,
+            content
           });
           return result2;
         } catch (error) {
@@ -403,13 +717,13 @@ function createOpenAIExtension(config) {
         }
       },
       description: "Send single message to OpenAI API",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-5: openai::messages
     messages: {
       params: [
-        { name: "messages", type: "list" },
-        { name: "options", type: "dict", defaultValue: {} }
+        p.list("messages"),
+        p.dict("options", void 0, {})
       ],
       fn: async (args, ctx) => {
         const startTime = Date.now();
@@ -417,7 +731,7 @@ function createOpenAIExtension(config) {
           const messages = args[0];
           const options = args[1] ?? {};
           if (messages.length === 0) {
-            throw new RuntimeError4(
+            throw new RuntimeError6(
               "RILL-R004",
               "messages list cannot be empty"
             );
@@ -434,18 +748,18 @@ function createOpenAIExtension(config) {
           for (let i = 0; i < messages.length; i++) {
             const msg = messages[i];
             if (!msg || typeof msg !== "object" || !("role" in msg)) {
-              throw new RuntimeError4(
+              throw new RuntimeError6(
                 "RILL-R004",
                 "message missing required 'role' field"
               );
             }
             const role = msg["role"];
             if (role !== "user" && role !== "assistant" && role !== "tool") {
-              throw new RuntimeError4("RILL-R004", `invalid role '${role}'`);
+              throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
             }
             if (role === "user" || role === "tool") {
               if (!("content" in msg) || typeof msg["content"] !== "string") {
-                throw new RuntimeError4(
+                throw new RuntimeError6(
                   "RILL-R004",
                   `${role} message requires 'content'`
                 );
@@ -458,7 +772,7 @@ function createOpenAIExtension(config) {
               const hasContent = "content" in msg && msg["content"];
               const hasToolCalls = "tool_calls" in msg && msg["tool_calls"];
               if (!hasContent && !hasToolCalls) {
-                throw new RuntimeError4(
+                throw new RuntimeError6(
                   "RILL-R004",
                   "assistant message requires 'content' or 'tool_calls'"
                 );
@@ -473,7 +787,7 @@ function createOpenAIExtension(config) {
           }
           const apiParams = {
             model: factoryModel,
-            max_tokens: maxTokens,
+            max_completion_tokens: maxTokens,
             messages: apiMessages
           };
           if (factoryTemperature !== void 0) {
@@ -507,7 +821,9 @@ function createOpenAIExtension(config) {
             subsystem: "extension:openai",
             duration,
             model: response.model,
-            usage: result2.usage
+            usage: result2.usage,
+            request: apiMessages,
+            content
           });
           return result2;
         } catch (error) {
@@ -527,11 +843,11 @@ function createOpenAIExtension(config) {
         }
       },
       description: "Send multi-turn conversation to OpenAI API",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-6: openai::embed
     embed: {
-      params: [{ name: "text", type: "string" }],
+      params: [p.str("text")],
       fn: async (args, ctx) => {
         const startTime = Date.now();
         try {
@@ -545,7 +861,7 @@ function createOpenAIExtension(config) {
           });
           const embeddingData = response.data[0]?.embedding;
           if (!embeddingData || embeddingData.length === 0) {
-            throw new RuntimeError4(
+            throw new RuntimeError6(
               "RILL-R004",
               "OpenAI: empty embedding returned"
             );
@@ -578,11 +894,11 @@ function createOpenAIExtension(config) {
         }
       },
       description: "Generate embedding vector for text",
-      returnType: "vector"
+      returnType: { type: "vector" }
     },
     // IR-7: openai::embed_batch
     embed_batch: {
-      params: [{ name: "texts", type: "list" }],
+      params: [p.list("texts")],
       fn: async (args, ctx) => {
         const startTime = Date.now();
         try {
@@ -601,7 +917,7 @@ function createOpenAIExtension(config) {
           for (const embeddingItem of response.data) {
             const embeddingData = embeddingItem.embedding;
             if (!embeddingData || embeddingData.length === 0) {
-              throw new RuntimeError4(
+              throw new RuntimeError6(
                 "RILL-R004",
                 "OpenAI: empty embedding returned"
               );
@@ -639,13 +955,13 @@ function createOpenAIExtension(config) {
         }
       },
       description: "Generate embedding vectors for multiple texts",
-      returnType: "list"
+      returnType: { type: "list" }
     },
     // IR-8: openai::tool_loop
     tool_loop: {
       params: [
-        { name: "prompt", type: "string" },
-        { name: "options", type: "dict", defaultValue: {} }
+        p.str("prompt"),
+        p.dict("options", void 0, {})
       ],
       fn: async (args, ctx) => {
         const startTime = Date.now();
@@ -653,79 +969,14 @@ function createOpenAIExtension(config) {
           const prompt = args[0];
           const options = args[1] ?? {};
           if (prompt.trim().length === 0) {
-            throw new RuntimeError4("RILL-R004", "prompt text cannot be empty");
+            throw new RuntimeError6("RILL-R004", "prompt text cannot be empty");
           }
-          if (!("tools" in options) || !Array.isArray(options["tools"])) {
-            throw new RuntimeError4(
+          if (!("tools" in options) || !isDict2(options["tools"])) {
+            throw new RuntimeError6(
               "RILL-R004",
               "tool_loop requires 'tools' option"
             );
           }
-          const toolDescriptors = options["tools"];
-          const toolsDict = {};
-          for (const descriptor of toolDescriptors) {
-            const name = typeof descriptor["name"] === "string" ? descriptor["name"] : null;
-            if (!name) {
-              throw new RuntimeError4(
-                "RILL-R004",
-                "tool descriptor missing name"
-              );
-            }
-            const toolFnValue = descriptor["fn"];
-            if (!toolFnValue) {
-              throw new RuntimeError4(
-                "RILL-R004",
-                `tool '${name}' missing fn property`
-              );
-            }
-            if (!isCallable2(toolFnValue)) {
-              throw new RuntimeError4(
-                "RILL-R004",
-                `tool '${name}' fn must be callable`
-              );
-            }
-            const paramsObj = descriptor["params"];
-            const description = typeof descriptor["description"] === "string" ? descriptor["description"] : "";
-            let enhancedCallable = toolFnValue;
-            if (paramsObj && typeof paramsObj === "object" && !Array.isArray(paramsObj)) {
-              const params = Object.entries(
-                paramsObj
-              ).map(([paramName, paramMeta]) => {
-                const meta = paramMeta;
-                const typeStr = typeof meta["type"] === "string" ? meta["type"] : null;
-                let typeName = null;
-                if (typeStr === "string") typeName = "string";
-                else if (typeStr === "number") typeName = "number";
-                else if (typeStr === "bool" || typeStr === "boolean")
-                  typeName = "bool";
-                else if (typeStr === "list" || typeStr === "array")
-                  typeName = "list";
-                else if (typeStr === "dict" || typeStr === "object")
-                  typeName = "dict";
-                else if (typeStr === "vector") typeName = "vector";
-                const param = {
-                  name: paramName,
-                  typeName,
-                  defaultValue: null,
-                  annotations: {}
-                };
-                if (typeof meta["description"] === "string") {
-                  param.description = meta["description"];
-                }
-                return param;
-              });
-              const baseCallable = toolFnValue;
-              enhancedCallable = {
-                __type: "callable",
-                kind: "application",
-                params,
-                fn: baseCallable.fn,
-                description,
-                isProperty: baseCallable.isProperty ?? false
-              };
-            }
-            toolsDict[name] = enhancedCallable;
-          }
           const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
           const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
           const maxErrors = typeof options["max_errors"] === "number" ? options["max_errors"] : 3;
@@ -741,17 +992,17 @@ function createOpenAIExtension(config) {
             const prependedMessages = options["messages"];
             for (const msg of prependedMessages) {
               if (!msg || typeof msg !== "object" || !("role" in msg)) {
-                throw new RuntimeError4(
+                throw new RuntimeError6(
                   "RILL-R004",
                   "message missing required 'role' field"
                 );
               }
               const role = msg["role"];
               if (role !== "user" && role !== "assistant") {
-                throw new RuntimeError4("RILL-R004", `invalid role '${role}'`);
+                throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
               }
               if (!("content" in msg) || typeof msg["content"] !== "string") {
-                throw new RuntimeError4(
+                throw new RuntimeError6(
                   "RILL-R004",
                   `${role} message requires 'content'`
                 );
@@ -782,7 +1033,7 @@ function createOpenAIExtension(config) {
             callAPI: async (msgs, tools) => {
               const apiParams = {
                 model: factoryModel,
-                max_tokens: maxTokens,
+                max_completion_tokens: maxTokens,
                 messages: msgs,
                 tools,
                 tool_choice: "auto"
@@ -839,6 +1090,21 @@ function createOpenAIExtension(config) {
                 };
               });
             },
+            // Extract assistant message (with tool_calls) from OpenAI response
+            formatAssistantMessage: (response2) => {
+              if (!response2 || typeof response2 !== "object" || !("choices" in response2)) {
+                return null;
+              }
+              const choices = response2.choices;
+              if (!Array.isArray(choices) || choices.length === 0) {
+                return null;
+              }
+              const choice = choices[0];
+              if (!choice || typeof choice !== "object" || !("message" in choice)) {
+                return null;
+              }
+              return choice.message;
+            },
             // Format tool results into OpenAI message format
             formatToolResult: (toolResults) => {
               return toolResults.map((tr) => ({
@@ -850,7 +1116,7 @@ function createOpenAIExtension(config) {
           };
           const loopResult = await executeToolLoop(
             messages,
-            toolsDict,
+            options["tools"],
             maxErrors,
             callbacks,
             (event, data) => {
@@ -908,7 +1174,9 @@ function createOpenAIExtension(config) {
             subsystem: "extension:openai",
             turns: loopResult.turns,
             total_duration: duration,
-            usage: result2.usage
+            usage: result2.usage,
+            request: messages,
+            content
           });
           return result2;
         } catch (error) {
@@ -928,7 +1196,126 @@ function createOpenAIExtension(config) {
         }
       },
       description: "Execute tool-use loop with OpenAI API",
-      returnType: "dict"
+      returnType: { type: "dict" }
+    },
+    // IR-3: openai::generate
+    generate: {
+      params: [
+        p.str("prompt"),
+        p.dict("options")
+      ],
+      fn: async (args, ctx) => {
+        const startTime = Date.now();
+        try {
+          const prompt = args[0];
+          const options = args[1] ?? {};
+          if (!("schema" in options) || options["schema"] === null || options["schema"] === void 0) {
+            throw new RuntimeError6(
+              "RILL-R004",
+              "generate requires 'schema' option"
+            );
+          }
+          const rillSchema = options["schema"];
+          const jsonSchema = buildJsonSchema(rillSchema);
+          const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
+          const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
+          const apiMessages = [];
+          if (system !== void 0) {
+            apiMessages.push({
+              role: "system",
+              content: system
+            });
+          }
+          if ("messages" in options && Array.isArray(options["messages"])) {
+            const prependedMessages = options["messages"];
+            for (const msg of prependedMessages) {
+              if (!msg || typeof msg !== "object" || !("role" in msg)) {
+                throw new RuntimeError6(
+                  "RILL-R004",
+                  "message missing required 'role' field"
+                );
+              }
+              const role = msg["role"];
+              if (role !== "user" && role !== "assistant") {
+                throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
+              }
+              if (!("content" in msg) || typeof msg["content"] !== "string") {
+                throw new RuntimeError6(
+                  "RILL-R004",
+                  `${role} message requires 'content'`
+                );
+              }
+              apiMessages.push({
+                role,
+                content: msg["content"]
+              });
+            }
+          }
+          apiMessages.push({ role: "user", content: prompt });
+          const apiParams = {
+            model: factoryModel,
+            max_completion_tokens: maxTokens,
+            messages: apiMessages,
+            response_format: {
+              type: "json_schema",
+              json_schema: {
+                name: "output",
+                schema: jsonSchema,
+                strict: true
+              }
+            }
+          };
+          if (factoryTemperature !== void 0) {
+            apiParams.temperature = factoryTemperature;
+          }
+          const response = await client.chat.completions.create(apiParams);
+          const raw = response.choices[0]?.message?.content ?? "";
+          let data;
+          try {
+            data = JSON.parse(raw);
+          } catch (parseError) {
+            const detail = parseError instanceof Error ? parseError.message : String(parseError);
+            throw new RuntimeError6(
+              "RILL-R004",
+              `generate: failed to parse response JSON: ${detail}`
+            );
+          }
+          const result2 = {
+            data,
+            raw,
+            model: response.model,
+            usage: {
+              input: response.usage?.prompt_tokens ?? 0,
+              output: response.usage?.completion_tokens ?? 0
+            },
+            stop_reason: response.choices[0]?.finish_reason ?? "unknown",
+            id: response.id
+          };
+          const duration = Date.now() - startTime;
+          emitExtensionEvent(ctx, {
+            event: "openai:generate",
+            subsystem: "extension:openai",
+            duration,
+            model: response.model,
+            usage: result2.usage,
+            request: apiMessages,
+            content: raw
+          });
+          return result2;
+        } catch (error) {
+          const duration = Date.now() - startTime;
+          const rillError = error instanceof RuntimeError6 ? error : mapProviderError("OpenAI", error, detectOpenAIError);
+          emitExtensionEvent(ctx, {
+            event: "openai:error",
+            subsystem: "extension:openai",
+            error: rillError.message,
+            duration
+          });
+          throw rillError;
+        }
+      },
+      description: "Generate structured output from OpenAI API",
+      returnType: { type: "dict" }
     }
   };
   result.dispose = dispose;
@@ -937,7 +1324,19 @@ function createOpenAIExtension(config) {
 
 // src/index.ts
 var VERSION = "0.0.1";
+var configSchema = {
+  api_key: { type: "string", required: true, secret: true },
+  model: { type: "string", required: true },
+  base_url: { type: "string" },
+  temperature: { type: "number" },
+  max_tokens: { type: "number" },
+  timeout: { type: "number" },
+  max_retries: { type: "number" },
+  system: { type: "string" },
+  embed_model: { type: "string" }
+};
 export {
   VERSION,
+  configSchema,
   createOpenAIExtension
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcrsr/rill-ext-openai",
-  "version": "0.8.6",
+  "version": "0.11.0",
   "description": "rill extension for OpenAI API integration",
   "license": "MIT",
   "author": "Andre Bremer",
@@ -17,33 +17,34 @@
     "scripting"
   ],
   "peerDependencies": {
-    "@rcrsr/rill": "^0.8.6"
+    "@rcrsr/rill": "^0.11.0"
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@rcrsr/rill": "^0.11.0",
+    "@types/node": "^25.3.0",
     "dts-bundle-generator": "^9.5.1",
-    "tsup": "^8.5.0",
-    "undici-types": "^7.21.0",
-    "@rcrsr/rill-ext-llm-shared": "^0.0.1",
-    "@rcrsr/rill": "^0.8.6"
+    "tsup": "^8.5.1",
+    "undici-types": "^7.22.0",
+    "@rcrsr/rill-ext-llm-shared": "^0.0.1"
   },
   "files": [
     "dist"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rcrsr/rill.git",
+    "url": "git+https://github.com/rcrsr/rill-ext.git",
     "directory": "packages/ext/llm-openai"
   },
-  "homepage": "https://rill.run/docs/extensions/openai/",
+  "homepage": "https://github.com/rcrsr/rill-ext/tree/main/packages/ext/llm-openai#readme",
   "bugs": {
-    "url": "https://github.com/rcrsr/rill/issues"
+    "url": "https://github.com/rcrsr/rill-ext/issues"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "openai": "^6.18.0"
+    "openai": "^6.25.0",
+    "@rcrsr/rill-ext-param-shared": "0.0.1"
   },
   "scripts": {
     "build": "tsup && dts-bundle-generator --config dts-bundle-generator.config.cjs",