Module lil-engine/src

Provider-agnostic representation of an LLM conversation.

A Program is a list of instructions plus the buffers they reference. Requests, responses and streaming chunks from every supported provider parse into the same shape, so routing, editing and re-emitting are ordinary data transformations rather than per-provider special cases.

Exports follow one naming scheme:

create* builds a new program
parse* / emit* convert between a provider wire format and a program
encode* / decode* convert between a program and its protobuf form
get* reads a single value, find* locates spans, extract* pulls out text
is* / has* are predicates
append*, prepend*, insert*, remove*, replace*, set* return an edited copy, never mutating the input
streaming helpers live under the delta namespace

This package deliberately stops at the protocol: executors, tool loops and HTTP routing belong to @neutrome/lilsdk.

Example

import { delta, extractContentText, parseProviderRequest, setModel } from "@neutrome/lil-engine";

const request = setModel(parseProviderRequest("chat-completions", body), "core/turn-1");
const answer = extractContentText(await ctx.invoke("core/turn-1", request));

Namespaces

delta

Classes

ProgramView: Decoded, structured read model of a Program.

Type Aliases

Attachment: A file, image, audio, video or text payload referenced by a message.
AttachmentKind: Kind of binary or textual payload referenced by a message.
ErrorBlock: A structured error decoded from a program.
ErrorBlockInput: Error details accepted by appendErrorBlock.
Instruction: One instruction: an opcode plus its payload.
InstructionValue: The payload an instruction carries. kind selects the variant.
MessageRole: Role of a message turn.
MessageSpan: Instruction range covering one message, from MSG_START to MSG_END.
Opcode: The numeric value of any Opcode member.
Program: A conversation encoded as instructions plus the buffers they reference.
ProgramAttachment: An attachment together with where it sits in the program.
ProgramMessage: A decoded message turn.
ProgramStreamEvent: A single event decoded from a streaming program.
ProgramThinking: A block of model reasoning attached to a message.
ProgramTool: A tool declared to the model by a program.
ProgramToolCall: A tool call emitted by the model.
ProgramToolResult: The result of a tool call, fed back to the model.
ProviderErrorMeta: Transport details that help interpret a provider error body.
ProviderStyle: A provider wire format supported by this package.
TextMessageRole: Role accepted by the text message builders.
ThinkingSpan: Instruction range covering one thinking block.
ToolCallData: A tool call decoded into its transport-level fields.
ToolCallSpan: Instruction range covering one tool call.
ToolDefinitionSpan: Instruction range covering one tool definition.
ToolInteraction: A completed tool call and its result, recorded as one exchange.
ToolResultSpan: Instruction range covering one tool result.
ValidationIssue: A single rule violation found by validateProgram.
ValidationIssueCode: Machine-readable reason a program failed validation.
ValidationMode: Which rule set to validate against: a complete program or a stream chunk.
ValidationOptions: Options accepted by validateProgram.
ValidationResult: Outcome of validateProgram.

Variables

Opcode: The instruction set every program is built from.

Functions

appendAssistantMessage: Appends an assistant message to a program.
appendAttachment: Appends an attachment to the end of a program.
appendAttachmentToMessage: Adds an attachment to an existing message.
appendErrorBlock: Appends a structured error to a program.
appendInstructions: Appends instructions to the end of a program.
appendTool: Declares a tool the model may call.
appendToolInteraction: Appends a tool call and its result as one exchange.
appendUserMessage: Appends a user message to a program.
cloneInstruction: Deep-copies one instruction, including any JSON payload it carries.
cloneProgram: Deep-copies a program, including its instructions and buffers.
createMessageProgram: Creates a program holding a single text message.
createModelProgram: Creates an empty program targeting a model.
createProgram: Creates a program.
createToolCallProgram: Creates a program holding a single assistant tool call.
createToolResultProgram: Creates a program holding a single tool result turn.
decodeAttachment: Decodes an attachment stored in a program buffer.
decodeProgram: Decodes a program from its protobuf wire form.
emitProviderError: Renders the error carried by a program in a provider's error format.
emitProviderRequest: Renders a program as a provider request body.
emitProviderResponse: Renders a program as a provider response body.
emitProviderStreamChunk: Renders a chunk program in a provider's streaming format.
encodeProgram: Encodes a program to its protobuf wire form.
extractAttachments: Decodes every attachment carried by a program.
extractContentText: Concatenates the visible text of every message in a program.
extractMessageText: Reads the text of a single message.
extractThinkingText: Reads model reasoning text.
extractToolCalls: Decodes every tool call emitted by a program.
findErrorBlocks: Decodes every error block carried by a program.
findMessages: Locates every message in a program.
findOpcodes: Lists the positions of every instruction using an opcode.
findThinkingBlocks: Locates every thinking block in a program.
findToolCalls: Locates every tool call emitted in a program.
findToolDefinitions: Locates every tool definition declared by a program.
findToolResults: Locates every tool result carried by a program.
getAttachmentOpcode: Maps an attachment kind to the opcode that carries it.
getFinishReason: Reads why the model stopped generating.
getFirstErrorBlock: Reads the first error carried by a program.
getLastMessageRole: Reads the role of the last message in a program.
getModel: Reads the model a program targets.
getOpcodeName: Renders an opcode as its symbolic name, for logs and error messages.
getUsage: Reads the provider usage payload attached to a response.
hasOpcode: Reports whether a program carries an opcode.
insertAfter: Inserts instructions after a position.
insertBefore: Inserts instructions before a position.
isAttachmentOpcode: Reports whether an opcode carries an attachment reference.
isStreaming: Reports whether a program asked for a streamed response.
parseProviderError: Parses a provider error body into a program carrying an error block.
parseProviderRequest: Parses a provider request body into a program.
parseProviderResponse: Parses a provider response body into a program.
parseProviderStreamChunk: Parses one streamed provider chunk into a program.
prependSystemPrompt: Puts a system message in front of a program's conversation.
removeInstructions: Removes instructions by position.
removeRange: Removes an inclusive range of instructions.
replaceRange: Replaces an inclusive range of instructions.
setInstruction: Replaces a single instruction.
setModel: Sets the model a program targets, replacing any existing selection.
setStreaming: Turns streaming on or off for a program.
validateProgram: Checks a program against the instruction-set rules.