DeepClause logo DeepClause
Home / Docs / SDK API Reference

SDK API

Type-shaped reference for the current SDK surface.

This page follows the exported TypeScript surface from deepclause-sdk. It is meant to be reference-first: constructor shape, primary methods, option objects, tool registration contracts, and emitted event fields.

Start with createDeepClause See runnable examples
Package Surface

Primary exports

import { createDeepClause } from 'deepclause-sdk';
import type {
  CreateOptions,
  RunOptions,
  CompileOptions,
  CompileResult,
  DMLEvent,
  ToolDefinition,
  ToolPolicy,
} from 'deepclause-sdk';

import {
  compileToDML,
  validateWithProlog,
  analyzeDML,
} from 'deepclause-sdk/compiler';
Two import layers Use the main package entry point for runtime execution and type imports. Use deepclause-sdk/compiler when you want compiler helpers directly.
Constructor

createDeepClause(options)

const dc = await createDeepClause({
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  streaming: true,
  trace: false,
});
Field Type Meaning
model string Required. Model identifier such as gpt-4o or gemini-2.5-flash.
apiKey string? Provider credential for model-backed runs.
provider 'openai' | 'anthropic' | 'google' | 'openrouter' Optional explicit provider. Otherwise inferred from the model.
temperature number? Sampling temperature for task and prompt calls.
maxTokens number? Maximum output token budget for model responses.
baseUrl string? Optional custom endpoint, useful for compatible transports.
trace boolean? Enables execution trace data in the final finished event.
streaming boolean? Enables streamed LLM text for task() and prompt().
debug boolean? Emits extra debug information about prompts and tool calls.
providerOptions Record<string, Record<string, any>>? Provider-specific SDK options such as reasoning or thinking configuration.
compaction CompactionOptions? Default memory compaction settings for task and prompt execution.
Methods

The DeepClauseSDK interface

Method Return type Purpose
runDML(code, options?) AsyncGenerator<DMLEvent> Execute DML code and stream events as the run progresses.
compile(source, options?) Promise<CompileResult> Compile Markdown or a Markdown file path into DML and metadata.
registerTool(name, tool) void Register a runtime tool callable through exec().
setToolPolicy(policy) void Apply a whitelist or blacklist policy to registered tools.
clearToolPolicy() void Remove the current tool policy and allow all registered tools.
getToolPolicy() ToolPolicy | null Inspect the currently active tool policy.
getTools() string[] List registered tool names.
provideInput(input) void Resume a run waiting for input_required when you are not using onUserInput.
getMemory() MemoryMessage[] Inspect current conversation memory as role/content pairs.
dispose() Promise<void> Release runtime resources when the SDK instance is no longer needed.
runDML Options

RunOptions

for await (const event of dc.runDML(code, {
  args: ['topic'],
  params: { limit: 5 },
  workspacePath: process.cwd(),
  gasLimit: 2000,
  onUserInput: async (prompt) => 'continue',
  signal: abortController.signal,
  initialMessages: [
    { role: 'user', content: 'Use repo conventions.' },
  ],
})) {
  console.log(event.type);
}
Field Meaning
args Positional values passed to agent_main.
params Named values available through param() and string interpolation.
workspacePath Working directory for file and shell-aware runtime behavior.
gasLimit Maximum execution steps for the run.
onUserInput Callback for interactive input_required events.
signal Abort signal for cancellation.
initialMessages Seeded user or assistant turns added to memory before execution.
compaction Per-run override for compaction bindings and policies.
compile Options

CompileOptions and result shape

Compile options

  • model, provider, temperature, and baseUrl tune the compiler model call.
  • maxAttempts caps retry attempts during compilation.
  • verbose enables richer compilation logs.
  • tools lets you describe additional tools to the compiler.
  • audit toggles the LLM-backed security review layer.

Compile result

  • dml: compiled program text.
  • tools: detected external tool dependencies.
  • explanation: brief summary of the generated program.
  • valid, errors, and analysis: validation and audit surface.
Tools and Policy

ToolDefinition and ToolPolicy

dc.registerTool('weather_lookup', {
  description: 'Return weather data for a city',
  parameters: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
    },
    required: ['city'],
  },
  execute: async ({ city }) => ({ city, condition: 'sunny' }),
});

dc.setToolPolicy({
  mode: 'whitelist',
  tools: ['weather_*', 'file_read'],
});
Type Fields
ToolDefinition description, parameters as JSON Schema, and async execute(args).
JsonSchema type: 'object', properties, and optional required keys.
ToolPolicy mode is whitelist or blacklist; tools supports wildcard patterns like file_*.
Events

DMLEvent stream

Event type Important fields When it appears
output content From output() or yield().
log content From log() and runtime log surfaces.
stream content, done Incremental model text when streaming is enabled.
answer content Final committed answer from answer().
input_required prompt When DML requests user input and no inline callback has satisfied it yet.
tool_call toolName, toolArgs, toolState, toolResult, toolPid, toolBackend, toolExitCode, toolSummary, toolError Lifecycle events around external tool execution.
usage usage Token accounting for a model call.
memory_compaction compactionScope, compactionTrigger, compactionAction, beforeTokens, afterTokens, compactionError Whenever a configured compaction binding is evaluated.
error content Runtime or provider failure conditions.
finished trace? Terminal event when execution ends.
Compaction

Compaction type surface

  • CompactionScope: session, loop, or run.
  • CompactionTrigger: before_user_message, before_model_call, before_task, or after_task.
  • CompactionAction: applied, skipped, or failed.
  • CompactorDefinition supports inline or file-backed DML, model overrides, tool inheritance, gas limits, and policy overrides.
  • CompactorBinding attaches one compactor to a runtime scope and trigger pair.