ISAC-Sim

AI Interface Module Guide

Bridge connecting Symbion simulator and AI frameworks

This guide details how to use the Symbion library's AI interface module (symbion/ai) to integrate the TypeScript simulation environment with various AI frameworks, including Reinforcement Learning (PyTorch, RLlib, Stable-Baselines3), Large Language Models, and other AI systems.

Table of Contents

1. Module Overview

1.1 Purpose and Scenarios

The AI Interface Module provides a framework-agnostic interface for connecting Symbion to AI backends:

  • Interactive Loop: Use step() / reset() methods for iterative AI interactions
  • One-Shot Query: Use query() method for one-shot inference
  • Batch Processing: Use batch() method for parallel processing
  • Streaming: Use stream() method for generative models

1.3 Client Types

Client ClassUse Case
AiInterfaceClientOne-shot AI inference (LLM, Vision)
IterativeAiClientIterative AI loops (step/reset pattern)

2. Core Concepts

Space Type System

Symbion AI interface uses a standardized Space type system for defining input/output formats.

Discrete & Box Spaces

import type { DiscreteSpace, BoxSpace } from 'symbion/ai';

const mcsSpace: DiscreteSpace = {
  kind: 'discrete',
  n: 29
};

const positionSpace: BoxSpace = {
  kind: 'box', 
  shape: [3],
  low: [0, 0, 30],
  high: [1000, 1000, 150]
};

Protocol Layer

The AI interface uses a JSON-based WebSocket protocol.

interface Msg<T> {
  v: 1;                 // Protocol version
  type: MsgType;        // 'hello', 'step', 'action', etc.
  sessionId: string;
  data: T;
}

3. Quick Start

Basic Usage Flow

import { IterativeAiClient } from 'symbion/ai';

// 1. Create Client
const client = new IterativeAiClient({
  host: 'localhost',
  port: 8765,
  inputSpace: obsSpace,
  outputSpace: actSpace
});

// 2. Connect
await client.connect();

// 3. Reset Env
const action = await client.reset(initialObs);

// 4. Step Loop
await client.step(observation, reward, done);

4. Detailed API Description

IterativeAiClient

constructor(config: AiInterfaceConfig, transport?: Transport)

// Config Options
interface AiInterfaceConfig {
  host?: string;         // 'localhost'
  port?: number;         // 8765
  timeoutMs?: number;    // 30000
  autoReconnect?: boolean; // true
}

5. Practical Examples

Basic Training Loop

async function runTraining() {
  const client = new IterativeAiClient({ ... });
  await client.connect();
  
  for (let episode = 0; episode < 100; episode++) {
    let action = await client.reset(initialObs);
    
    while (!done) {
      const { obs, reward, terminated } = env.step(action);
      action = await client.step(obs, reward, terminated);
    }
  }
}
Next: Extras Experimental ModuleView API Reference