A Starlark module for interacting with OpenAI and OpenAI-compatible API services. Generate text with chat completions and create images with DALL-E / GPT Image 1, directly from your Starlark scripts.
Within the Star* ecosystem β "starpkg = support for necessary LOCAL
operations + simple abstractions over common ONLINE services, for ease of
use" β llm is an online-service abstraction. It wraps a remote SaaS API
behind three small script-facing builtins, so a script reaches a chat or image
model without juggling HTTP, auth headers, retries, or response shapes.
- Chat completions β
chatfor OpenAI GPT and reasoning models, with multi-turn conversations and multimodal inputs (text + images). - Image generation β
drawfor DALL-E 2/3 and GPT Image 1. - Message builder β
messageassembles a conversation message (text and/or image) forchat. - Many providers β the OpenAI API, Azure OpenAI Service, the Anthropic
Claude API, and any OpenAI-compatible endpoint, selected by
openai_provider. - Streaming β real-time responses with an optional per-chunk callback.
- Robust calls β customizable retry behavior, graceful error handling
(
retry,allow_error), and custom/provider-specific parameters viakwargs.
It is an L4 domain module: it depends downward on starpkg/base (the
module/config system), 1set/starlet (the Machine + dataconv), and
transitively 1set/starlight + go.starlark.net. Nothing in the ecosystem
depends on it.
For the complete per-builtin reference β signatures, parameters, returns, errors, examples β and the configuration accessors, see docs/API.md.
go get github.com/starpkg/llmWire the module into a Starlet interpreter, then load("llm", β¦) from a script.
The Go layer provides the historical NewModule() (empty config) and
NewModuleWithConfig(serviceProvider, endpointURL, apiKey, gptModel, dalleModel, apiVersion)
(preset config) constructors. For a host that runs untrusted scripts, use
NewModuleWithHostPolicy to bind credentials and the endpoint while keeping
model selection in Starlark:
mod := llm.NewModuleWithHostPolicy(llm.HostPolicy{
Provider: "openai",
EndpointURL: "https://api.openai.com/v1",
APIKey: os.Getenv("OPENAI_API_KEY"),
FileRoot: "/srv/llm-images", // empty disables image_file
})package main
import (
"fmt"
"os"
"github.com/1set/starlet"
"github.com/starpkg/llm"
)
func main() {
apiKey := os.Getenv("OPENAI_API_KEY")
mod := llm.NewModuleWithConfig("openai", "", apiKey, "gpt-4o", "dall-e-3", "")
interpreter := starlet.New(
starlet.WithModuleLoader("llm", mod.LoadModule()),
)
script := `
load("llm", "chat", "draw")
# Generate text using GPT
response = chat(text="Explain quantum computing in simple terms.", max_tokens=100)
print("GPT response:", response)
# Generate an image using DALL-E
image_url = draw(prompt="A cute robot explaining quantum computing", size="1024x1024")
print("Image URL:", image_url)
`
if err := interpreter.ExecScript("example.star", script); err != nil {
fmt.Println("Error:", err)
}
}Hold a multi-turn conversation, building messages with message:
load("llm", "message", "chat")
messages = [
message(role="user", text="Hello, who are you?"),
message(role="assistant", text="I'm an AI assistant. How can I help you today?"),
message(role="user", text="Can you explain what an LLM is?"),
]
print(chat(messages=messages, max_tokens=200))Top-level builtins (load("llm", β¦)):
message(role?, text?, image?, image_file?, image_url?)β build a conversation message object forchat.chat(text?, image?, image_file?, image_url?, messages?, model?, n?, max_tokens?, max_completion_tokens?, temperature?, top_p?, frequency_penalty?, presence_penalty?, stop?, response_format?, reasoning_effort?, retry?, full_response?, allow_error?, stream?, stream_callback?, kwargs?)β send a chat completion request (blocking or streaming).draw(prompt, model?, n?, quality?, size?, style?, response_format?, background?, moderation?, output_format?, output_compression?, retry?, full_response?, allow_error?)β generate an image with DALL-E or GPT Image 1.
See docs/API.md for the full signatures, return values, errors, and examples of every builtin above.
The module's options (openai_provider, openai_endpoint_url,
openai_api_key, openai_gpt_model, openai_dalle_model, api_version,
legacy_mode, request_timeout) are configured via environment variables
(LLM_*) or per-option get_<key> / set_<key> accessor builtins, and serve as
defaults for chat / draw. openai_api_key is secret β it exposes only
set_openai_api_key, never a getter. request_timeout (default 120s) bounds
each request (a total deadline for blocking chat/draw; a connect +
first-response bound for streaming, so long streams aren't truncated). See the
Configuration section of docs/API.md for the full
option table, defaults, accessors, and the legacy_mode behavior.
Trust model β NewModule() and NewModuleWithConfig retain the historical
self-configuring behavior: a script can choose its provider/endpoint/key, and
image_file can read any host-readable file (bounded to 64 MiB). For untrusted
scripts, NewModuleWithHostPolicy makes the provider, endpoint, and key
host-only, rejects cross-origin redirects, and confines image_file to
FileRoot (an empty root disables it). See Safety / trust model.
This package is licensed under the MIT License β see the LICENSE file for details.