Host API Reference

import {
  parse,
  execute,
  createRuntimeContext,
  callable,
  AbortError,
  type RillValue,
} from '@rcrsr/rill';

const script = `
  $config.greeting -> prompt() => $response
  $response
`;

const controller = new AbortController();

const ctx = createRuntimeContext({
  variables: {
    config: {
      greeting: 'Say hello in French',
    },
    utils: {
      // Property-style callable (computed property)
      timestamp: callable(() => Date.now(), true),
      // Regular callable
      format: callable((args) => {
        const [template, ...values] = args;
        return String(template).replace(/\{\}/g, () =>
          String(values.shift() ?? '')
        );
      }),
    },
  },

  functions: {
    prompt: {
      params: [{ name: 'text', type: 'string' }],
      fn: async (args, ctx, location) => {
        console.log(`[prompt at line ${location?.line}]`);
        return await callLLM(args[0]);
      },
    },
  },

  callbacks: {
    onLog: (value) => console.log('[log]', value),
  },

  observability: {
    onStepStart: (e) => console.log(`Step ${e.index + 1}...`),
    onStepEnd: (e) => console.log(`Done (${e.durationMs}ms)`),
  },

  timeout: 30000,
  signal: controller.signal,
});

try {
  const ast = parse(script);
  const result = await execute(ast, ctx);
  console.log('Result:', result.value);
  console.log('Variables:', result.variables);
} catch (err) {
  if (err instanceof AbortError) {
    console.log('Cancelled');
  } else {
    throw err;
  }
}

// Parsing
export { parse, ParseError, tokenize, LexerError };

// Execution
export { execute, createRuntimeContext, createStepper };
export type { RuntimeContext, RuntimeOptions, ExecutionResult };
export type { ExecutionStepper, StepResult };

// Callable types
export { callable, isCallable, isScriptCallable, isRuntimeCallable, isApplicationCallable };
export type { RillCallable, ScriptCallable, RuntimeCallable, ApplicationCallable, CallableFn };

// Host function types
export type { HostFunctionDefinition, HostFunctionParam, RillFunctionReturnType };
export { validateHostFunctionArgs };

// Value types
export type { RillValue, RillArgs };

// Introspection
export { getFunctions, getLanguageReference, getDocumentationCoverage };
export type { FunctionMetadata, ParamMetadata, DocumentationCoverageResult };

// Version information
export { VERSION, VERSION_INFO };
export type { VersionInfo };

// Callbacks
export type { RuntimeCallbacks, ObservabilityCallbacks };
export type { StepStartEvent, StepEndEvent, FunctionCallEvent, FunctionReturnEvent };
export type { CaptureEvent, ErrorEvent };

// Errors
export { RillError, RuntimeError, ParseError, AbortError, TimeoutError, AutoExceptionError };
export { RILL_ERROR_CODES };
export type { RillErrorCode };

// Utilities
export { isArgs, isDict, isReservedMethod, RESERVED_DICT_METHODS };
export type { SourceLocation, SourceSpan };

// Control flow (for advanced use)
export { BreakSignal, ReturnSignal };

// Extension contracts
export type { KvExtensionContract, FsExtensionContract, LlmExtensionContract, VectorExtensionContract, SchemaEntry };

type KvExtensionContract = {
  readonly get: HostFunctionDefinition;
  readonly get_or: HostFunctionDefinition;
  readonly set: HostFunctionDefinition;
  readonly merge: HostFunctionDefinition;
  readonly delete: HostFunctionDefinition;
  readonly keys: HostFunctionDefinition;
  readonly has: HostFunctionDefinition;
  readonly clear: HostFunctionDefinition;
  readonly getAll: HostFunctionDefinition;
  readonly schema: HostFunctionDefinition;
  readonly mounts: HostFunctionDefinition;
  readonly dispose?: (() => void | Promise<void>) | undefined;
};

import type { KvExtensionContract } from '@rcrsr/rill';
import { createMyKvBackend } from './my-kv-backend';

// Type-check backend implementation
const backend: KvExtensionContract = createMyKvBackend({ /* config */ });

type FsExtensionContract = {
  readonly read: HostFunctionDefinition;
  readonly write: HostFunctionDefinition;
  readonly append: HostFunctionDefinition;
  readonly list: HostFunctionDefinition;
  readonly find: HostFunctionDefinition;
  readonly exists: HostFunctionDefinition;
  readonly remove: HostFunctionDefinition;
  readonly stat: HostFunctionDefinition;
  readonly mkdir: HostFunctionDefinition;
  readonly copy: HostFunctionDefinition;
  readonly move: HostFunctionDefinition;
  readonly mounts: HostFunctionDefinition;
  readonly dispose?: (() => void | Promise<void>) | undefined;
};

import type { FsExtensionContract } from '@rcrsr/rill';
import { createMyFsBackend } from './my-fs-backend';

// Type-check backend implementation
const backend: FsExtensionContract = createMyFsBackend({ /* config */ });

export interface SchemaEntry {
  type: 'string' | 'number' | 'bool' | 'list' | 'dict';
  default: RillValue;
  description?: string;
}

import type { SchemaEntry } from '@rcrsr/rill';

const schema: Record<string, SchemaEntry> = {
  name: { type: 'string', default: '', description: 'User name' },
  age: { type: 'number', default: 0, description: 'User age in years' },
  active: { type: 'bool', default: true },
};

type LlmExtensionContract = {
  readonly message: HostFunctionDefinition;
  readonly messages: HostFunctionDefinition;
  readonly embed: HostFunctionDefinition;
  readonly embed_batch: HostFunctionDefinition;
  readonly tool_loop: HostFunctionDefinition;
  readonly dispose?: (() => void | Promise<void>) | undefined;
};

import type { LlmExtensionContract } from '@rcrsr/rill';
import { createMyLlmBackend } from './my-llm-backend';

// Type-check backend implementation
const backend: LlmExtensionContract = createMyLlmBackend({ /* config */ });

type VectorExtensionContract = {
  readonly upsert: HostFunctionDefinition;
  readonly upsert_batch: HostFunctionDefinition;
  readonly search: HostFunctionDefinition;
  readonly get: HostFunctionDefinition;
  readonly delete: HostFunctionDefinition;
  readonly delete_batch: HostFunctionDefinition;
  readonly count: HostFunctionDefinition;
  readonly create_collection: HostFunctionDefinition;
  readonly delete_collection: HostFunctionDefinition;
  readonly list_collections: HostFunctionDefinition;
  readonly describe: HostFunctionDefinition;
  readonly dispose?: (() => void | Promise<void>) | undefined;
};

import type { VectorExtensionContract } from '@rcrsr/rill';
import { createMyVectorBackend } from './my-vector-backend';

// Type-check backend implementation
const backend: VectorExtensionContract = createMyVectorBackend({ /* config */ });