Use Quinelings
in your own code.

Start with Session

Import Session from @quinelings/agent-sdk/v1. It uses QDL 1, the project’s stable program format. QDL describes a calculation’s steps, accepted inputs, declared purpose and body. A Session holds your programs and their execution records in memory.

The package is available as a downloadable archive or a local build; it is not published to npm. The setup guide explains how to build the package and run its example with Node.js 22 or later.

A named input, also called a port, specifies what kind of value the program accepts. For example, a water calculation can accept a list of numbers measured in liters. Supplying new readings leaves the program’s source unchanged. Editing its calculation, constants or body creates different source.

Create a program, then run it

This example adds water readings to a reserve. The intent object is the structured task description: thought declares its purpose, inputs lists the accepted data, and steps connects the calculations. Each step has an ID so later steps can use its result.

import { Session } from '@quinelings/agent-sdk/v1';

const session = new Session();
const liter = {kind: 'number', unit: 'L', min: 0};
const intent = {
  format: 'qdl-intent', version: 1, name: 'Supplied water total',
  thought: {
    observations: [
      {id: 'observedReadings', text: 'Explicitly supplied liter readings.', input: 'readings', path: [], basis: 'open'},
      {id: 'observedReserve', text: 'Explicitly supplied reserve liters; no ambient stored balance.', input: 'reserve', path: [], basis: 'open'}
    ],
    evidence: [], goals: [], decisions: [],
    plans: [{id: 'plan', text: 'Sum the readings, then add the supplied reserve.', tasks: ['task']}],
    tasks: [{id: 'task', text: 'Compute the bounded total from this snapshot.', nodes: ['readings', 'reserve', 'subtotal', 'total'], outputs: ['total']}]
  },
  inputs: [
    {id: 'readings', name: 'readings', type: {kind: 'array', element: liter}},
    {id: 'reserve', name: 'reserve', type: liter}
  ],
  steps: [
    {id: 'subtotal', op: 'sum', inputs: ['readings'], params: {}},
    {id: 'total', op: 'arithmetic', inputs: ['subtotal', 'reserve'], params: {kind: 'add'}}
  ],
  outputs: ['total']
};
const artifact = session.compile(intent);

const first = session.run({
  artifactId: artifact.id, requestId: 'water-a',
  inputs: { readings: [2, 3], reserve: 4 }
}); // outputs: [9]
const second = session.run({
  artifactId: artifact.id, requestId: 'water-b',
  inputs: { readings: [4, 5], reserve: 2 }
}); // outputs: [11]

console.log(first.result.occurrences[0].outputs); // [9]
console.log(second.result.occurrences[0].outputs); // [11]
console.log(session.inspect(artifact.id).source === artifact.source); // true
session.verify(artifact.id); // source-only; no task evaluation

compile validates the description and returns an artifact: the stored program and its source. It does not run the task. The two explicit run calls return totals of 9 and 11 from different supplied inputs.

artifactId identifies the program. requestId identifies a particular invocation. Use a new request ID for a new run. If a response is lost, repeat the exact request with its original ID to retrieve the saved record. Reusing an ID with changed inputs is an error.

What each Session method does

An execution record contains results and a trace of the calculation steps. Read its result status: a delivered record can report a failed calculation. Drawing or animating the body does not run the task, and reproducing a run does not collect new observations from the outside world.

Session storage is in memory. exportSnapshot() returns data that your application can save; Session.fromSnapshot() restores it. Imported historical results are labeled asserted. They become fresh local computation evidence only when evaluated again; importing a result does not establish that it happened.

See the Session reference for method arguments, errors, storage limits and snapshot handling.

Calculations and local simulations

Programs calculate with data you supply. Actions such as walking a route or allocating supplies produce local simulated results. They do not move a character, send a message or change another service. An observation’s declared unit and real-world accuracy remain the caller’s responsibility.

What the mathematical checks establish

Lean is a proof assistant that checks proofs about mathematical models. This project uses it for source reconstruction and selected properties of geometry, color and state changes. Quint explores possible sequences of actions in bounded models to search for broken rules.

JavaScript and browser tests check the implementation. The Lean and Quint models do not prove every part of the JavaScript implementation correct, establish the truth of supplied observations or guarantee how a shape will look.

Read the mathematical models and their limits.

Earlier APIs and experimental features

The default package import exposes the earlier Runtime API. Experimental body construction uses VisualCapsule from /experimental. These have different interfaces from stable Session.