Public APIs – Spock GOS

Overview

Spock exposes a simple API for creating engines, managing sessions, and executing DSL scripts. All interactions return explainable DSL traces.

Engine Factory

`createSpockEngine(options)`

Creates a new Spock engine instance.

const engine = createSpockEngine({
  workingFolder: '.spock',      // Theory storage location
  dimensions: 512,               // Vector dimensions
  defaultTheories: ['BasicLogic'], // Theories to preload
  logLevel: 'summary'            // 'silent' | 'summary' | 'full'
});

Engine Methods

`createSession()`	Create a new reasoning session
`loadTheory(name)`	Load a theory from disk
`listTheories()`	List available theories
`getConfig()`	Get current configuration
`shutdown()`	Clean up resources

Session API

`createSessionApi(session)`

Creates a high-level API wrapper around a session.

const session = engine.createSession();
const api = createSessionApi(session);

Session Methods

All methods accept a DSL script and return an ApiResult:

`learn(script)`	Ingest facts and definitions into the session
`ask(script)`	Query for truth values and answers
`prove(script)`	Construct formal proofs with traces
`explain(script)`	Generate explanations for conclusions
`plan(script)`	Generate action sequences for goals
`solve(script)`	Find constraint satisfaction solutions
`summarise(script)`	Create summarised concepts

ApiResult Structure

{
  success: boolean,           // Did execution complete?
  symbols: Map<string, Value>, // All declared symbols
  scores: {
    truth: number,            // Truth degree [0, 1]
    confidence: number        // Confidence level
  },
  trace: DSLTrace,            // Execution trace
  dslOutput: string           // Replayable DSL script
}

Usage Examples

Basic Learning and Asking

// Learn some facts
api.learn(`
  @f1 Socrates Is Human
  @f2 Humans Are Mortal
`);

// Ask a question
const result = api.ask(`
  @query Socrates Is Mortal
  @eval query Evaluate Truth
`);

console.log(result.scores.truth); // ~1.0
console.log(result.dslOutput);    // Can replay this script

Using Theories

// Load and use a theory
api.learn(`
  @usePhysics local UseTheory GravityTheory

  @massLit 10 HasNumericValue 10
  @mass massLit AttachUnit kg

  @gLit 9.8 HasNumericValue 9.8
  @g gLit AttachUnit m_per_s2

  @force mass ComputeForce g
`);

Planning

const plan = api.plan(`
  @usePlan local UseTheory LinearPlanning

  @start RobotAt Home
  @goal CupAt Table

  @myPlan start Plan goal
`);

// plan.dslOutput contains the step sequence

Error Handling

Errors are returned in the ApiResult with success: false:

const result = api.ask(`@invalid syntax here`);

if (!result.success) {
  console.error(result.error.message);
  console.error(result.error.line); // Line number
}

Explainability

Every result includes a DSL trace that can be replayed:

// Get the trace
const trace = result.trace;

// Convert to replayable script
const script = result.dslOutput;

// Re-execute to verify
const verified = api.learn(script);
// Should produce identical results

Spock Public APIs