AI Interface

Bridge connecting Symbion simulator with Python AI frameworks (PyTorch, RLlib, Stable-Baselines3). Provides Gymnasium-compatible environment interface for reinforcement learning.

import { ai } from 'symbion'

Sub-modules

Client Interface

ai.client

Main client classes for connecting Symbion with AI backends

Classes (3)

AiInterfaceClient

classv1.0.0

Base client for one-shot AI inference (query/batch/stream).

Constructor

new AiInterfaceClient(config: AiInterfaceConfig, transport?: Transport)

config: AiInterfaceConfig— Configuration options

transport: Transport— Optional transport layer

Methods

query(input: Input): Promise<Output>▶

batch(inputs: Input[]): Promise<Output[]>▶

ai.client

IterativeAiClient

classv1.0.0

Main client class for iterative AI interactions (step/reset pattern). Connects to AI servers (e.g., Python scripts using PyTorch/RLlib) via WebSocket.

Constructor

new IterativeAiClient(config: AiInterfaceConfig, transport?: Transport)

config: AiInterfaceConfig— Configuration including host, port, spaces, and timeouts

transport: Transport— Optional transport layer (defaults to BrowserWebSocketTransport)

Properties

isConnected(readonly) boolean Current connection status

Methods

connect(): Promise<void>▶

disconnect(): void▶

step(input: Input, feedback: number, done: boolean, info?: Record<string, unknown>): Promise<Output>▶

reset(initialInput: Input, info?: Record<string, unknown>): Promise<Output>▶

onEvent(callback: (event: AiClientEvent) => void): void▶

Example

import { IterativeAiClient } from 'symbion/ai';

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

await client.connect();
const action = await client.reset(initialObs);

ai.client

FakeAgentServer

classv1.0.0

Mock AI Agent server for unit testing.

Constructor

new FakeAgentServer(transport: Transport)

Methods

setActionStrategy(fn: (obs: any) => any): void▶

ai.client

Types (1)

AiInterfaceConfig

interface

Configuration options for AiClient

`host?`	`string`	Server host (default 'localhost')
`port?`	`number`	Server port (default 8765)
`inputSpace`	`Space`	Space definition for inputs sent to AI
`outputSpace`	`Space`	Space definition for outputs received from AI
`timeoutMs?`	`number`	Request timeout in ms
`autoReconnect?`	`boolean`	Enable auto-reconnect

ai.client

Helpers

ai.helpers

Utility functions for observation processing and action mapping

Functions (6)

defaultUavObservation

v1.0.0

(state: UavState) => Record<string, number[]>

Extract standard UAV observation (position, velocity, acceleration, comms metrics) from state.

Returns

Record<string, number[]>Raw observation dictionary

ai.helpers

minimalUavObservation

v1.0.0

(state: UavState) => Record<string, number[]>

Extract minimal UAV observation (position, velocity only).

Returns

Record<string, number[]>Minimal observation dictionary

ai.helpers

normalizeObservation

v1.0.0

(obs: Record<string, any>, space: Space) => Record<string, any>

Normalize observation values to [-1, 1] or [0, 1] based on space bounds, useful for Neural Networks.

Returns

Record<string, any>Normalized observation

ai.helpers

clampAction

v1.0.0

(action: any, space: Space) => any

Clamp output action values to valid range defined by the space.

Returns

anyClamped action

ai.helpers

defaultUavActionMapper

v1.0.0

(action: Record<string, unknown>) => ControlCommand

Map AI output action dict to UAV control command (thrust, yaw, MCS, power).

Returns

ControlCommandPhysical control command

ai.helpers

findOptimalMcs

v1.0.0

(snrDb: number, blerTarget?: number) => number

Calculate optimal MCS index for a given SNR and BLER target.

Parameters

Name	Type	Description
`snrDb`	`number`	Signal-to-Noise Ratio in dB
`blerTarget?`	`number`	Target Block Error Rate (default 0.1)

Returns

numberOptimal MCS index (0-28)

ai.helpers

Protocol Handler

ai.protocol

Low-level WebSocket protocol for TypeScript-Python communication

Functions (1)

createMessage

v1.0.0

<T>(type: MsgType, data: T, sessionId: string) => Msg<T>

Create a protocol message with correct format and metadata.

Parameters

Name	Type	Description
`type`	`MsgType`	Message type (hello, step, action, etc.)
`data`	`T`	Message payload
`sessionId`	`string`	Session identifier

Returns

Msg<T>Formatted protocol message

ai.protocol

Classes (1)

ProtocolHandler

classv1.0.0

Handles message serialization, deserialization, and request-response matching.

Constructor

new ProtocolHandler(sessionId: string, timeoutMs?: number)

Methods

createMessage(type: string, data: any): Msg▶

registerRequest<T>(requestId: string): Promise<T>▶

handleMessage(msg: Msg<unknown>): void▶

ai.protocol

Types (1)

Msg<T>

interface

Protocol message wrapper

`v`	`1`	Protocol version
`type`	`MsgType`	Message type
`sessionId`	`string`	Session identifier
`requestId?`	`string`	Request ID for response matching
`data`	`T`	Message payload

ai.protocol

Transport Layer

ai.transport

WebSocket and InMemory transport implementations

Classes (2)

BrowserWebSocketTransport

classv1.0.0

WebSocket transport using browser native WebSocket API.

Constructor

new BrowserWebSocketTransport(url: string)

url: string— WebSocket server URL

Methods

connect(): Promise<void>▶

send(data: string): void▶

ai.transport

InMemoryTransport

classv1.0.0

In-memory transport for unit testing without network.

Methods

static createPair(): [InMemoryTransport, InMemoryTransport]▶

ai.transport

Types (1)

Transport

interface

Transport interface that all implementations must follow

`connect`	`() => Promise<void>`	Connect method
`send`	`(data: string) => void`	Send method
`close`	`() => void`	Close method
`onMessage`	`(callback: (data: string) => void) => void`	Message callback setter

ai.transport

Space Types

ai.spaces

Gymnasium-compatible space definitions (Box, Discrete, Dict)

Functions (1)

validateSpace

v1.0.0

(space: Space) => boolean

Validate that a space definition is well-formed.

Returns

booleanTrue if space is valid

ai.spaces

Types (5)

Space

type

Union of all space types

type Space = BoxSpace | DiscreteSpace | MultiDiscreteSpace | DictSpace | TupleSpace;

ai.spaces

BoxSpace

interface

Continuous multi-dimensional space with bounds

`kind`	`'box'`	Space type
`shape`	`number[]`	Shape dimensions
`low`	`number \| number[]`	Lower bound
`high`	`number \| number[]`	Upper bound
`dtype?`	`string`	Data type (float32, etc.)

ai.spaces

DiscreteSpace

interface

Discrete space with N items

`kind`	`'discrete'`	Space type
`n`	`number`	Number of discrete options
`labels?`	`string[]`	Optional labels for each option

ai.spaces

DictSpace

interface

Dictionary of spaces.

`kind`	`'dict'`	Space type
`spaces`	`Record<string, Space>`	Map of keys to sub-spaces

ai.spaces

MultiDiscreteSpace

interface

Multiple discrete dimensions

`kind`	`'multiDiscrete'`	Space type
`nvec`	`number[]`	Number of discrete options per dimension
`labels?`	`string[][]`	Optional labels for each option

ai.spaces

View AI Interface Module Guide