@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.1

package/lib/build/llm.d.ts

@@ -0,0 +1,166 @@
+/**
+ * LLM Integration Types
+ *
+ * Provides types for interacting with Language Models through the Serious Gaming SDK.
+ * Model selection and endpoint configuration is handled by the platform.
+ */
+/**
+ * A content block inside an LLM message or response.
+ *
+ * - `text` — plain text content
+ * - `toolUse` — a structured intent emitted by the assistant; the caller is
+ *   expected to run the tool in its own code and feed the result back via a
+ *   `toolResult` block
+ * - `toolResult` — the result of a tool run, sent back in a `user` message so
+ *   the model can continue the conversation
+ *
+ * The SDK relays tool intent and results across the wire; it never executes
+ * tools itself.
+ */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'toolUse';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'toolResult';
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+};
+/**
+ * A message in a conversation with an LLM.
+ *
+ * `content` may be a plain string (the common case) or an array of content
+ * blocks when the message carries tool-use intents or tool results.
+ */
+export interface LLMMessage {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+/**
+ * JSON Schema for requesting structured responses from the LLM
+ * Follows the JSON Schema specification
+ */
+export interface JSONSchema {
+    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    description?: string;
+    items?: JSONSchema;
+    enum?: unknown[];
+    default?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * LLM capability tier for a generateText call.
+ *
+ * - `quick`    — fast, low-cost model (default)
+ * - `standard` — balanced model for typical generation tasks
+ * - `expert`   — most capable model for complex reasoning and analysis
+ *
+ * Which model each tier maps to is configured at the platform level.
+ * If a tier is not configured, it falls back toward `quick`.
+ */
+export type LLMTier = 'quick' | 'standard' | 'expert';
+/**
+ * A tool the model may invoke. The model never executes anything itself —
+ * when it emits a `toolUse` content block, the caller runs the tool in its
+ * own code and feeds the result back via a `toolResult` block on the next
+ * turn.
+ *
+ * `name` must match `^[a-zA-Z0-9_-]{1,64}$`; the LLM client validates this
+ * at the boundary and throws before making a request.
+ */
+export interface LLMTool {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+/**
+ * Options for generating text with an LLM
+ */
+export interface LLMGenerateOptions {
+    /**
+     * A simple prompt for text generation
+     * Use this for straightforward requests
+     */
+    prompt?: string;
+    /**
+     * A conversation history for multi-turn interactions
+     * Specify either `prompt` or `messages`, not both
+     */
+    messages?: LLMMessage[];
+    /**
+     * Optional system prompt to guide the LLM's behavior
+     * Provides context and instructions for how the LLM should respond
+     */
+    systemPrompt?: string;
+    /**
+     * JSON Schema for structured output
+     * When provided, the LLM will return a response that validates against this schema
+     */
+    jsonSchema?: JSONSchema;
+    /**
+     * The capability tier to use for this call.
+     * Defaults to `'quick'` if not specified.
+     */
+    tier?: LLMTier;
+    /**
+     * Tools the model may invoke. When set and the model decides to call a
+     * tool, the response's `stopReason` will be `'toolUse'` and at least one
+     * `toolUse` content block will be present. The caller runs the tool and
+     * feeds the result back as a `toolResult` block on the next call.
+     */
+    tools?: LLMTool[];
+}
+/**
+ * Why the LLM stopped generating.
+ *
+ * - `endTurn`   — the model finished a normal response
+ * - `toolUse`   — the model emitted one or more tool-use blocks and expects
+ *                 tool results back on the next call
+ * - `maxTokens` — the model hit a token limit before finishing
+ * - `refusal`   — the model refused to respond; callers should branch
+ *                 separately (rewrite the prompt, escalate, etc.)
+ */
+export type LLMStopReason = 'endTurn' | 'toolUse' | 'maxTokens' | 'refusal';
+/**
+ * Token usage reported by the LLM provider for one generation call.
+ */
+export interface LLMUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/**
+ * Response from the LLM.
+ *
+ * `content` is an array of content blocks so a single response can carry
+ * text and one or more tool-use intents. Simple callers that just want the
+ * text can use {@link getText}.
+ *
+ * `usage` is present when the provider reports token counts for the call.
+ */
+export interface LLMResponse {
+    content: ContentBlock[];
+    stopReason: LLMStopReason;
+    usage?: LLMUsage;
+}
+/**
+ * Helper for the common case where a caller just wants the assistant's
+ * text. Returns the concatenation of every `text` block in the response;
+ * `toolUse` blocks are skipped.
+ */
+export declare function getText(response: LLMResponse): string;
+/**
+ * Function for generating text with an LLM
+ * The actual endpoint and model are determined by the platform
+ *
+ * Can be called with a simple string prompt or a full options object:
+ * - generateText("Generate some text")
+ * - generateText({ prompt: "text", systemPrompt: "instructions" })
+ */
+export type LLMGenerateFunction = (options: LLMGenerateOptions | string) => Promise<LLMResponse>;

package/lib/build/llm.js

@@ -0,0 +1,17 @@
+/**
+ * LLM Integration Types
+ *
+ * Provides types for interacting with Language Models through the Serious Gaming SDK.
+ * Model selection and endpoint configuration is handled by the platform.
+ */
+/**
+ * Helper for the common case where a caller just wants the assistant's
+ * text. Returns the concatenation of every `text` block in the response;
+ * `toolUse` blocks are skipped.
+ */
+export function getText(response) {
+    return response.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+}