new builtin: generateObject (#1143)

Added a new generateObject LLM API and builder node for generating structured JSON objects from prompts and schemas, with backend validation and example usage in recipes.

New Features

- Added generateObject API endpoint and handler for LLM-backed JSON object generation.
- Introduced generateObject builder node and client support.
- Added schema validation using Ajv on the backend.
- Provided example usage in seeder/json.tsx and updated counter recipe for JSON mode.

Author: anotherjesse

deno.lock

@@ -229,6 +229,16 @@ export interface BuiltInLLMState<T> {
   error: unknown;
 }
 
+export interface BuiltInGenerateObjectParams {
+  model?: string;
+  prompt?: string;
+  schema?: JSONSchema;
+  system?: string;
+  cache?: boolean;
+  maxTokens?: number;
+  metadata?: Record<string, string | undefined | object>;
+}
+
 export interface BuiltInCompileAndRunParams<T> {
   files: Record<string, string>;
   main: string;
@@ -340,6 +350,10 @@ export type LLMFunction = <T = string>(
   params: Opaque<BuiltInLLMParams>,
 ) => OpaqueRef<BuiltInLLMState<T>>;
 
+export type GenerateObjectFunction = <T = any>(
+  params: Opaque<BuiltInGenerateObjectParams>,
+) => OpaqueRef<BuiltInLLMState<T>>;
+
 export type FetchDataFunction = <T>(
   params: Opaque<{
     url: string;
@@ -404,6 +418,7 @@ export declare const render: RenderFunction;
 export declare const str: StrFunction;
 export declare const ifElse: IfElseFunction;
 export declare const llm: LLMFunction;
+export declare const generateObject: GenerateObjectFunction;
 export declare const fetchData: FetchDataFunction;
 export declare const streamData: StreamDataFunction;
 export declare const compileAndRun: CompileAndRunFunction;

packages/api/index.ts

@@ -1,4 +1,11 @@
-import { LLMContent, LLMMessage, LLMRequest, LLMResponse } from "./types.ts";
+import { 
+  LLMContent, 
+  LLMMessage, 
+  LLMRequest, 
+  LLMResponse,
+  LLMGenerateObjectRequest,
+  LLMGenerateObjectResponse
+} from "./types.ts";
 
 type PartialCallback = (text: string) => void;
 
@@ -14,6 +21,26 @@ export const setLLMUrl = (toolshedUrl: string) => {
 };
 
 export class LLMClient {
+  async generateObject(
+    request: LLMGenerateObjectRequest,
+  ): Promise<LLMGenerateObjectResponse> {
+    const response = await fetch(llmApiUrl + "/generateObject", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `HTTP error! status: ${response.status}, body: ${errorText}`,
+      );
+    }
+
+    const data = await response.json();
+    return data;
+  }
+
   /**
    * Sends a request to the LLM service.
    *

packages/llm/src/client.ts

@@ -6,6 +6,7 @@ export const DEFAULT_MODEL_NAME: ModelName =
 // NOTE(ja): This should be an array of models, the first model will be tried, if it
 // fails, the second model will be tried, etc.
 export const DEFAULT_IFRAME_MODELS: ModelName = "openai:gpt-4.1-nano";
+export const DEFAULT_GENERATE_OBJECT_MODELS: ModelName = "openai:gpt-4.1-nano";
 
 export type LLMResponse = {
   content: string;
@@ -37,6 +38,21 @@ export interface LLMRequest {
   metadata?: LLMRequestMetadata;
 }
 
+export interface LLMGenerateObjectRequest {
+  schema: Record<string, unknown>;
+  prompt: string;
+  model?: ModelName;
+  system?: string;
+  cache?: boolean;
+  maxTokens?: number;
+  metadata?: LLMRequestMetadata;
+}
+
+export interface LLMGenerateObjectResponse {
+  object: Record<string, unknown>;
+  id?: string;
+}
+
 function isArrayOf<T>(
   callback: (data: any) => boolean,
   input: any,

packages/llm/src/types.ts

@@ -48,13 +48,30 @@ export interface BuiltInLLMState<T> {
   error: unknown;
 }
 
+export interface BuiltInGenerateObjectParams {
+  model?: string;
+  prompt?: string;
+  schema?: JSONSchema;
+  system?: string;
+  cache?: boolean;
+  maxTokens?: number;
+  metadata?: Record<string, string | undefined | object>;
+}
+
 export const llm = createNodeFactory({
   type: "ref",
   implementation: "llm",
 }) as <T = string>(
   params: Opaque<BuiltInLLMParams>,
 ) => OpaqueRef<BuiltInLLMState<T>>;
 
+export const generateObject = createNodeFactory({
+  type: "ref",
+  implementation: "generateObject",
+}) as <T = any>(
+  params: Opaque<BuiltInGenerateObjectParams>,
+) => OpaqueRef<BuiltInLLMState<T>>;
+
 export const fetchData = createNodeFactory({
   type: "ref",
   implementation: "fetchData",

packages/runner/src/builder/built-in.ts

@@ -25,6 +25,7 @@ import { byRef, compute, derive, handler, lift, render } from "./module.ts";
 import {
   compileAndRun,
   fetchData,
+  generateObject,
   ifElse,
   llm,
   navigateTo,
@@ -91,6 +92,7 @@ export const createBuilder = (
     str,
     ifElse,
     llm,
+    generateObject,
     fetchData,
     streamData,
     compileAndRun,

packages/runner/src/builder/factory.ts

@@ -9,6 +9,7 @@ import type {
   CreateCellFunction,
   DeriveFunction,
   FetchDataFunction,
+  GenerateObjectFunction,
   GetRecipeEnvironmentFunction,
   HandlerFunction,
   IfElseFunction,
@@ -270,6 +271,7 @@ export interface BuilderFunctionsAndConstants {
   str: StrFunction;
   ifElse: IfElseFunction;
   llm: LLMFunction;
+  generateObject: GenerateObjectFunction;
   fetchData: FetchDataFunction;
   streamData: StreamDataFunction;
   compileAndRun: CompileAndRunFunction;

packages/runner/src/builder/types.ts

@@ -2,10 +2,12 @@ import { raw } from "../module.ts";
 import { map } from "./map.ts";
 import { fetchData } from "./fetch-data.ts";
 import { streamData } from "./stream-data.ts";
-import { llm } from "./llm.ts";
+import { llm, generateObject } from "./llm.ts";
 import { ifElse } from "./if-else.ts";
 import type { IRuntime } from "../runtime.ts";
 import { compileAndRun } from "./compile-and-run.ts";
+import type { DocImpl } from "../doc.ts";
+import type { BuiltInGenerateObjectParams } from "@commontools/api";
 
 /**
  * Register all built-in modules with a runtime's module registry
@@ -19,4 +21,10 @@ export function registerBuiltins(runtime: IRuntime) {
   moduleRegistry.addModuleByRef("llm", raw(llm));
   moduleRegistry.addModuleByRef("ifElse", raw(ifElse));
   moduleRegistry.addModuleByRef("compileAndRun", raw(compileAndRun));
+  moduleRegistry.addModuleByRef("generateObject", raw<BuiltInGenerateObjectParams, {
+    pending: DocImpl<boolean>;
+    result: DocImpl<Record<string, unknown> | undefined>;
+    partial: DocImpl<string | undefined>;
+    requestHash: DocImpl<string | undefined>;
+  }>(generateObject));
 }