Geppetto JavaScript API Reference

Reference for the native `require("geppetto")` API exposed through goja.

Sections

Terminology & Glossary
📖 Documentation
Navigation
58 sectionsv0.1
📄 Geppetto JavaScript API Reference — glaze help geppetto-js-api-reference
geppetto-js-api-reference

Geppetto JavaScript API Reference

Reference for the native `require("geppetto")` API exposed through goja.

Topicgeppettojavascriptgojaapi-reference

This page documents the current hard-cut JavaScript API in pkg/js/modules/geppetto.

Execution Harness

Run scripts with:

go run ./cmd/examples/geppetto-js-lab --script <path-to-script.js>

Top-Level Namespaces

  • turns
  • engines
  • profiles
  • runner
  • middlewares
  • schemas
  • events
  • tools

engines

Current constructors:

  • echo({ reply? })
  • fromFunction(fn)
  • fromConfig(options)
  • fromResolvedProfile(resolvedProfile)
  • fromProfile({ registrySlug?, profileSlug? })

Recommended meaning:

  • use fromConfig(...) when the script already knows the provider/model/settings
  • use fromProfile(...) or fromResolvedProfile(...) when the script wants Geppetto to resolve engine settings from an engine profile registry

fromProfile(...) and fromResolvedProfile(...) build the engine only. They do not apply prompts, tool policy, or middleware policy.

When the source profile has inference_settings.model_info, the returned engine object includes engine.modelInfo with the same shape exposed by profiles.resolve(...). fromConfig(...) also accepts an optional modelInfo object for scripts that construct engines without profile resolution.

Example:

const resolved = gp.profiles.resolve({ profileSlug: "assistant" });
console.log(resolved.modelInfo?.reasoning);
console.log(resolved.modelInfo?.contextWindow);
console.log(resolved.modelInfo?.cost?.input);

const engine = gp.engines.fromResolvedProfile(resolved);
console.log(engine.modelInfo?.maxOutputTokens);

profiles

The profiles namespace is now really an engine profiles namespace, even though the JS name is still profiles.

Available functions:

  • listRegistries()
  • getRegistry(registrySlug?)
  • listProfiles(registrySlug?)
  • getProfile(profileSlug, registrySlug?)
  • resolve({ registrySlug?, profileSlug? })
  • connectStack(sources)
  • disconnectStack()
  • getConnectedSources()

resolve(...) returns:

  • registrySlug
  • profileSlug
  • inferenceSettings
  • modelInfo when the resolved InferenceSettings contains model_info
  • metadata

modelInfo is a convenience projection of inferenceSettings.model_info using JavaScript-friendly field names such as contextWindow, qualityHighWatermark, maxOutputTokens, and cost.cacheRead.

It no longer returns:

  • effectiveRuntime
  • runtimeKey
  • runtimeFingerprint

runner

runner is now purely app/runtime-oriented.

Available functions:

  • resolveRuntime(input?)
  • prepare(options)
  • run(options, runOptions?)
  • start(options, runOptions?)

runner.resolveRuntime(...) accepts only direct runtime input such as:

  • systemPrompt
  • middlewares
  • toolNames
  • runtimeKey
  • runtimeFingerprint
  • profileVersion
  • metadata

It no longer accepts profile.

If you need engine profiles, resolve them separately:

const resolved = gp.profiles.resolve({ profileSlug: "assistant" });
const engine = gp.engines.fromResolvedProfile(resolved);
const runtime = gp.runner.resolveRuntime({
  systemPrompt: "App-owned prompt",
  runtimeKey: "assistant",
});

createBuilder / createSession

Builder/session construction is now lower-level again.

Supported builder inputs:

  • engine
  • middlewares
  • tools
  • toolLoop
  • toolHooks

Removed from the builder path:

  • resolvedProfile
  • useResolvedProfile(...)

If you want profile-derived engine settings, build the engine first with gp.engines.fromProfile(...) or gp.engines.fromResolvedProfile(...), then pass the engine into the builder or runner.

Files

Relevant implementation files: