Skip to content
starpkgPublic

About

πŸ€– Starlark module for interacting with OpenAI and OpenAI-compatible API services

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

20 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ€– llm β€” Starlark module for AI and LLM services

godoc license codecov binary footprint

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.

Overview

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 β€” chat for OpenAI GPT and reasoning models, with multi-turn conversations and multimodal inputs (text + images).
  • Image generation β€” draw for DALL-E 2/3 and GPT Image 1.
  • Message builder β€” message assembles a conversation message (text and/or image) for chat.
  • 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 via kwargs.

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.

Installation

go get github.com/starpkg/llm

Quick Start

Wire 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))

Starlark API at a glance

Top-level builtins (load("llm", …)):

  • message(role?, text?, image?, image_file?, image_url?) β€” build a conversation message object for chat.
  • 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.

Configuration

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.

License

This package is licensed under the MIT License β€” see the LICENSE file for details.

About

πŸ€– Starlark module for interacting with OpenAI and OpenAI-compatible API services

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages