Comments

Author: vigoo

exec/wit/golem-exec.wit

@@ -3,10 +3,13 @@ package golem:[email protected];
 interface types {
   /// Supported language types and optional version
   record language {
+    /// The language to use
     kind: language-kind,
+    /// Optionally further narrow down the language version
     version: option<string>,
   }
 
+  /// Supported languages
   enum language-kind {
     javascript,
     python,
@@ -21,54 +24,75 @@ interface types {
 
   /// Code or data file
   record file {
+    /// File name
     name: string,
+    /// Raw file contents
     content: list<u8>,
-    encoding: option<encoding>, // defaults to utf8
+    /// Encoding of `content`, defaults to `utf8`
+    encoding: option<encoding>,
   }
 
   /// Resource limits
   record limits {
+    /// Limit the execution time, in milliseconds
     time-ms: option<u64>,
+    /// Limit the memory usage, in bytes
     memory-bytes: option<u64>,
+    /// Limit the maximum file size, in bytes
     file-size-bytes: option<u64>,
+    /// Limit the number of spawned processes
     max-processes: option<u32>,
   }
 
   /// Execution outcome per stage
   record stage-result {
+    /// Standard output
     stdout: string,
+    /// Standard error output
     stderr: string,
+    /// Exit code of the process, if any
     exit-code: option<s32>,
+    /// Signal that caused the process to terminate, if any
     signal: option<string>,
   }
 
   /// Complete execution result
   record exec-result {
+    /// Result of the compilation stage, if any
     compile: option<stage-result>,
+    /// Result of the execution stage
     run: stage-result,
+    /// Execution time in milliseconds
     time-ms: option<u64>,
+    /// Consumed memory in bytes
     memory-bytes: option<u64>,
   }
 
   /// Execution error types
   variant error {
+    /// The chosen langauge is not supported
     unsupported-language,
+    /// Compilation failed
     compilation-failed(stage-result),
+    /// Execution failed
     runtime-failed(stage-result),
+    /// Timed out
     timeout,
+    /// Resource limits exceeded
     resource-exceeded,
+    /// Internal execution error
     internal(string),
   }
 
   /// Options for controlling the script runner environment
-  /// - `stdin` is optional input to provide to the program.
-  /// - `args` are command line arguments passed to the program.
-  /// - `env` is a list of environment variables to set for the execution.
-  /// - `limits` are optional resource limits for the execution.
   record run-options {
+    /// optional input to provide to the program.
     stdin: option<string>,
+    /// command line arguments passed to the program
     args: option<list<string>>,
+    /// a list of environment variables to set for the execution
     env: option<list<tuple<string, string>>>,
+    /// optional resource limits for the execution
     limits: option<limits>
   }
 }

llm/wit/golem-llm.wit

@@ -3,31 +3,51 @@ package golem:[email protected];
 interface llm {
   // --- Roles, Error Codes, Finish Reasons ---
 
+  /// Roles of the conversation
   enum role {
+    /// Instructions provided by the user
     user,
+    /// Messages generated by the model
     assistant,
+    /// Messages describing the system's rules
     system,
+    /// Messages describing tool calls
     tool,
   }
 
+  /// Possible error cases for LLM calls
   enum error-code {
+    /// Invalid request parameters
     invalid-request,
+    /// Authentication failed
     authentication-failed,
+    /// Rate limit exceeded
     rate-limit-exceeded,
+    /// Internal error
     internal-error,
+    /// Unsupported operation
     unsupported,
+    /// Unknown error
     unknown,
   }
 
+  /// Reasons for finishing a conversation
   enum finish-reason {
+    /// The conversation finished
     stop,
+    /// Conversation finished because of reaching the maximum length
     length,
+    /// Conversation finished with request for calling tools
     tool-calls,
+    /// Conversation finished because of content filtering
     content-filter,
+    /// Conversation finished with an error
     error,
+    /// Other reason
     other,
   }
 
+  /// Image detail levels
   enum image-detail {
     low,
     high,
@@ -36,153 +56,237 @@ interface llm {
 
   // --- Message Content ---
 
+  /// Points to an image by an URL and an optional image detail level
   record image-url {
+    /// The URL of the image
     url: string,
+    /// Level of detail of the image
     detail: option<image-detail>,
   }
 
+  /// Contains an inline image
   record image-source {
+    /// Raw image data
     data: list<u8>,
+    /// MIME type of the image
     mime-type: string,
+    /// Level of detail of the image
     detail: option<image-detail>,
   }
 
+  /// Contains an image, either a remote or an inlined one
   variant image-reference {
+    /// A remote image
     url(image-url),
+    /// An inlined image
     inline(image-source),
   }
 
+  /// One part of the conversation
   variant content-part {
+    /// Text content
     text(string),
+    /// Image content
     image(image-reference),
   }
 
+  /// A message in the conversation
   record message {
+    /// Role of this message
     role: role,
+    /// Name of the sender
     name: option<string>,
+    /// Content of the message
     content: list<content-part>,
   }
 
   // --- Tooling ---
 
+  /// Describes a tool callable by the LLM
   record tool-definition {
+    /// Name of the tool
     name: string,
+    /// Description of the tool
     description: option<string>,
+    /// Schema of the tool's parameters - usually a JSON schema
     parameters-schema: string,
   }
 
+  /// Describes a tool call request
   record tool-call {
+    /// Call identifier
     id: string,
+    /// Name of the tool
     name: string,
+    /// Arguments of the tool call
     arguments-json: string,
   }
 
+  /// Describes a successful tool call
   record tool-success {
+    /// Call identifier
     id: string,
+    /// Name of the tool
     name: string,
+    /// Result of the tool call in JSON
     result-json: string,
+    /// Execution time of the tool call in milliseconds
     execution-time-ms: option<u32>,
   }
 
+  /// Describes a failed tool call
   record tool-failure {
+    /// Call identifier
     id: string,
+    /// Name of the tool
     name: string,
+    /// Error message of the tool call
     error-message: string,
+    /// Error code of the tool call
     error-code: option<string>,
   }
 
+  /// Result of a tool call
   variant tool-result {
+    /// The tool call succeeded
     success(tool-success),
+    /// The tool call failed
     error(tool-failure),
   }
 
   // --- Configuration ---
 
+  /// Simple key-value pair
   record kv {
     key: string,
     value: string,
   }
 
+  /// LLM configuration
   record config {
+    /// The model to use
     model: string,
+    /// Temperature
     temperature: option<f32>,
+    /// Maximum number of tokens
     max-tokens: option<u32>,
+    /// A sequence where the model stops generating tokens
     stop-sequences: option<list<string>>,
+    /// List of available tools
     tools: list<tool-definition>,
+    /// Tool choice policy
     tool-choice: option<string>,
+    /// Additional LLM provider specific key-value pairs
     provider-options: list<kv>,
   }
 
   // --- Usage / Metadata ---
 
+  /// Token usage statistics
   record usage {
+    /// Number of input tokens used
     input-tokens: option<u32>,
+    /// Number of output tokens generated
     output-tokens: option<u32>,
+    /// Total number of tokens used
     total-tokens: option<u32>,
   }
 
+  /// Metadata about an LLM response
   record response-metadata {
+    /// Reason for finishing the conversation
     finish-reason: option<finish-reason>,
+    /// Usage statistics
     usage: option<usage>,
+    /// Provider-specific ID
     provider-id: option<string>,
+    /// Timestamp
     timestamp: option<string>,
+    /// Provider-specific additional metadata in JSON
     provider-metadata-json: option<string>,
   }
 
+  /// Response from an LLM
   record complete-response {
+    /// Response ID
     id: string,
+    /// Result contents
     content: list<content-part>,
+    /// Tool call requests
     tool-calls: list<tool-call>,
+    /// Response metadata
     metadata: response-metadata,
   }
 
   // --- Error Handling ---
 
+  /// LLM error
   record error {
+    /// Error code
     code: error-code,
+    /// Error message
     message: string,
+    /// More details in JSON, in a provider-specific format
     provider-error-json: option<string>,
   }
 
   // --- Chat Response Variants ---
 
+  /// One resulting event in an LLM conversation
   variant chat-event {
+    /// A response in the conversation
     message(complete-response),
+    /// A request for calling one or more tools
     tool-request(list<tool-call>),
+    /// An error in the conversation
     error(error),
   }
 
   // --- Streaming ---
 
+  /// Changes in a streaming conversation
   record stream-delta {
+    /// New content parts
     content: option<list<content-part>>,
+    /// New tool calls
     tool-calls: option<list<tool-call>>,
   }
 
+  /// Event in a streaming conversation
   variant stream-event {
+    /// New incoming response content or tool call requests
     delta(stream-delta),
+    /// Converstation finished
     finish(response-metadata),
+    /// Conversation failed
     error(error),
   }
 
+  /// Represents an ongoing streaming LLM conversation
   resource chat-stream {
+    /// Polls for the next chunk of stream events
     get-next: func() -> option<list<stream-event>>;
+    /// Blocks until the next chunk of stream events is available
     blocking-get-next: func() -> list<stream-event>;
   }
 
   // --- Core Functions ---
 
+  /// Make a single call to the LLM. Continue the conversation with `continue` if needed.
   send: func(
     messages: list<message>,
     config: config
   ) -> chat-event;
 
+  /// Continues a previous conversation initiated by `send` or a previous `continue`, by sending the updated
+  /// set of messages, and possible set of tool call results.
   continue: func(
     messages: list<message>,
     tool-results: list<tuple<tool-call, tool-result>>,
     config: config
   ) -> chat-event;
 
+  /// Makes a single call to the LLM and gets back a streaming API to receive the response in chunks.
   %stream: func(
     messages: list<message>,
     config: config