AI integration overview
What AI integration does, how the open-source SDK fits with the chart, and how to get started.
AI integration is built on the Lumen Charts automation API, which can serve ordinary JavaScript, custom workflows or an AI assistant. Your application chooses the model provider, transport, storage and commercial access policy.
The SDK is open source under the Apache License 2.0 (source on GitHub), and every Lumen Charts build includes the chart-side runtime it drives. There is no separate add-on to buy.
Quickstart
Open a session for a chart, add your own command and hand the tools to your model:
import { createAutomationTools, defineCommand, field } from '@lumencharts/chart-automation/sdk';
// Inside the widget's ready callback.
const sdk = await widget.activeChart().openAutomation({
policy: { effects: ['read', 'mutation'] },
});
await sdk.drawings.apply({
operations: [{ action: 'create', type: 'horizontal_line', points: [{ price: 182.5 }] }],
});
sdk.extensions.register(defineCommand({
name: 'acme.lastClose',
effect: 'read',
description: 'Return the latest loaded close.',
input: {},
output: { close: field.nullable(field.number()) },
async execute(_input, context) {
const { rows } = await context.execute('data.read', { seriesId: 'main', from: 0, to: Date.now(), limit: 10_000 });
return { close: (rows.at(-1) as { close?: number } | undefined)?.close ?? null };
},
}));
const tools = createAutomationTools(sdk); // name, description, parameters, execute(toolCallId, input)
const system = sdk.instructions(); // guidance from registered commands
// When the view is removed (removing the chart also closes the session):
sdk.close();openAutomation loads the optional automation asset, installs the native drawing, study and settings commands and wires an exact-chart PNG capture. Every request argument is optional; pass one when work must stay fenced to the chart state a caller saw earlier, as model tools do.
Product boundaries
| Part | Responsibility | Loading |
|---|---|---|
| Core chart runtime | Charts, datafeed integration, native editing, persistence and Undo | Widget startup |
| Automation runtime | Native command adapters and the session behind openAutomation, included in every build | First openAutomation() or widget.loadAutomation() |
| Automation SDK (open source) | Sessions, typed command facade, data/capture ports, policies, extensions, model tools and remote sessions | Opt-in application import from npm |
| Optional Pine | Compile and execute scripts and display their outputs | Separate Pine configuration and assets |
| Host application | Model calls, prompts, uploads, accounts, remote storage and entitlements | Supplied by the integrator |
The core does not bundle the automation implementation. Loaded-bar reads and local screenshots are native capabilities; createNativeChartAutomation uses them without loading the automation runtime. Native persistence and ordinary Undo also work without it.
Pine executes a script over market data and produces calculated outputs. Automation orchestrates chart operations and accesses data or images through explicit ports. It does not implicitly compile Pine, generate scripts or connect to an AI service. Hosts can compose these capabilities.
Access and prerequisites
Install the SDK from npm. It ships as one package built to ESM with type declarations: @lumencharts/chart-automation, with the entry points /sdk, /sdk/testing, /contracts and ..
npm install @lumencharts/chart-automationlumen_charting_library.d.ts names SDK types only through this package, so install it before type-checking against the chart. Update the SDK and the chart runtime together. openAutomation itself needs no SDK import; the SDK supplies defineCommand, field, model tools and remote sessions.
The surface has two supported tiers:
| Tier | What it covers | Stability |
|---|---|---|
| Stable | chart.openAutomation() and @lumencharts/chart-automation/sdk: sessions, defineCommand, field, createAutomationTools, remote sessions and the domain types they name. @lumencharts/chart-automation/sdk/testing for unit tests. | Supported for integrators. |
| Advanced | createChartAutomation, createNativeChartAutomation, installNativeAutomationCommands and the native owner factories (createDrawingDocument, createStudyDocument, widget.createWorkspaceCommands). The package root exports the drawing, study, settings and workspace contracts and validators these owners use. | Supported, but you own each owner's lifetime, persistence and Undo. |
Product-specific adapters, prompts and model tools belong in your application; none ship in this package.
The automation runtime is a separate file so charts that never use automation never download it. It needs no extra licence: every edition includes it. See installation and hosting.
Integration path
- Read and capture the chart: local data and capture.
- Change the chart and connect a model: native commands and model tools.
- Add your own commands, data and persistence: host adapters and extensions.
- Run the model on a server: server-side models.
Use sdk.capabilities() to discover installed, permitted operations. Unavailable command families reject with unsupported; a method existing in the TypeScript facade does not mean its native owner is installed.