LayerScale SDK

The official LayerScale SDK provides native access to sessions, streaming data ingestion, and Flash Queries. Use it for real-time streaming workloads where you need persistent sessions and continuous data processing.

For standard chat completions and tool calling, you can use the OpenAI or Anthropic SDKs instead. LayerScale is compatible with both.

Installation

TypeScript

npm install @layerscale/layerscale

Python

pip install layerscale

Create a Session

TypeScript

import { LayerScale } from "@layerscale/layerscale";

const client = new LayerScale("http://localhost:8080", { apiKey: "LS-..." });

const session = await client.sessions.create({
    type: "ohlcv",
    prompt: "You are a financial analyst. Analyze incoming market data.",
    flash: [
        { query: "Is the trend bullish or bearish?", max_tokens: 4 },
        { query: "What is the current support level?", max_tokens: 16 },
    ],
    markPrefix: true,
});

console.log(`Session created: ${session.session_id}`);

Python

from layerscale import LayerScale

client = LayerScale("http://localhost:8080", api_key="LS-...")

session = client.sessions.create(
    type="ohlcv",
    prompt="You are a financial analyst. Analyze incoming market data.",
    flash=[
        {"query": "Is the trend bullish or bearish?", "max_tokens": 4},
        {"query": "What is the current support level?", "max_tokens": 16},
    ],
    mark_prefix=True,
)

print(f"Session created: {session.session_id}")

The type parameter is required and determines the data format for the session. Supported types: ohlcv, iot, spatial, event, vitals.

The markPrefix / mark_prefix flag freezes the system prompt in the cache right after the session is created, so it is not reprocessed on every incoming data update.

Push Streaming Data

Push data points into the session. The endpoint is non-blocking: data is queued and processed in the background.

TypeScript

// Push OHLCV data
await client.sessions.push(session.session_id, [
    { o: 185.5, h: 186.2, l: 185.1, c: 185.8, v: 12500 },
    { o: 185.8, h: 186.5, l: 185.6, c: 186.3, v: 8700 },
]);

// Push IoT sensor data (on an "iot" session)
await client.sessions.push(session.session_id, [
    { sid: "temp-01", val: 72.5, lo: 60.0, hi: 85.0 },
]);

// Push vitals data (on a "vitals" session)
await client.sessions.push(session.session_id, [
    { hr: 72.0, bp_s: 120.0, bp_d: 80.0, spo2: 98.5, temp: 36.8 },
]);

Pass { wait: true } to block until the pushed items are fully processed:

await client.sessions.push(session.session_id, candles, { wait: true });

Python

# Push OHLCV data
client.sessions.push(session.session_id, [
    {"o": 185.5, "h": 186.2, "l": 185.1, "c": 185.8, "v": 12500},
    {"o": 185.8, "h": 186.5, "l": 185.6, "c": 186.3, "v": 8700},
])

# Push IoT sensor data (on an "iot" session)
client.sessions.push(session.session_id, [
    {"sid": "temp-01", "val": 72.5, "lo": 60.0, "hi": 85.0},
])

# Push vitals data (on a "vitals" session)
client.sessions.push(session.session_id, [
    {"hr": 72.0, "bp_s": 120.0, "bp_d": 80.0, "spo2": 98.5, "temp": 36.8},
])

Pass wait=True to block until the pushed items are fully processed:

client.sessions.push(session.session_id, candles, wait=True)

Query the Session

Generate a response based on all the data the session has seen:

TypeScript

// Blocking query
const result = await client.sessions.query(session.session_id, {
    prompt: "What's the trend over the last hour?",
    max_tokens: 200,
});
console.log(result.text);

// Streaming query
for await (const chunk of client.sessions.queryStream(session.session_id, {
    prompt: "Describe the price action.",
    max_tokens: 300,
})) {
    if (!chunk.done) process.stdout.write(chunk.token);
}

Python

# Blocking query
result = client.sessions.query(
    session.session_id,
    prompt="What's the trend over the last hour?",
    max_tokens=200,
)
print(result.text)

# Streaming query
with client.sessions.query_stream(
    session.session_id,
    prompt="Describe the price action.",
    max_tokens=300,
) as stream:
    for chunk in stream:
        if not chunk.done:
            print(chunk.token, end="", flush=True)

Receive Flash Query Results

SSE (Server-Sent Events)

TypeScript

for await (const event of client.sessions.events(session.session_id)) {
    if (event.type === "flash_ready") {
        console.log(`Query ${event.id}: ${event.value} (confidence: ${event.confidence})`);
    }
}

Python

with client.sessions.events(session.session_id) as events:
    for event in events:
        if event.type == "flash_ready":
            print(f"Query {event.id}: {event.value} (confidence: {event.confidence})")

WebSocket

The client supports WebSocket for combined push and event delivery in a single connection:

TypeScript

const socket = client.sessions.stream(session.session_id);

socket.on("connected", (data) => {
    console.log(`Connected: ${data.session_id}`);
});

// Push data
socket.push([{ o: 185.5, h: 186.2, l: 185.1, c: 185.8, v: 12500 }]);

// Listen for flash query results
socket.on("flash_ready", (event) => {
    console.log(`${event.query}: ${event.value}`);
});

socket.on("error", (err) => {
    console.error(`Error: ${err.message}`);
});

Python

from layerscale import WsFlashReady

with client.sessions.stream(session.session_id) as socket:
    socket.push([{"o": 185.5, "h": 186.2, "l": 185.1, "c": 185.8, "v": 12500}])

    for event in socket:
        if isinstance(event, WsFlashReady):
            print(f"{event.data.query}: {event.data.value}")

For async code, use AsyncLayerScale and async with client.sessions.stream(...).

Stream Status and Stats

TypeScript

// Check streaming processor status
const status = await client.sessions.streamStatus(session.session_id);
console.log(`Queue: ${status.streaming.queue_size}/${status.streaming.queue_capacity}`);
console.log(`Processed: ${status.statistics.items_processed} items`);

// Get computed stats for the session's data
const stats = await client.sessions.stats(session.session_id);
console.log(stats);

Python

# Check streaming processor status
status = client.sessions.stream_status(session.session_id)
print(f"Queue: {status.streaming.queue_size}/{status.streaming.queue_capacity}")
print(f"Processed: {status.statistics.items_processed} items")

# Get computed stats for the session's data
stats = client.sessions.stats(session.session_id)
print(stats)

Delete a Session

TypeScript

await client.sessions.delete(session.session_id);

Python

client.sessions.delete(session.session_id)

Full Example

TypeScript

import { LayerScale } from "@layerscale/layerscale";

const client = new LayerScale("http://localhost:8080", { apiKey: "LS-..." });

const session = await client.sessions.create({
    type: "ohlcv",
    prompt: "Monitor ETH/USD for breakout signals.",
    flash: [
        { query: "Is a breakout imminent?", max_tokens: 8 },
        { query: "What's the key resistance level?", max_tokens: 16 },
    ],
    markPrefix: true,
});

// Connect via WebSocket for combined push + events
const socket = client.sessions.stream(session.session_id);

socket.on("flash_ready", (event) => {
    console.log(`[FLASH] ${event.query}: ${event.value} (${event.confidence})`);
});

socket.on("open", () => {
    // Push data from your feed
    setInterval(() => {
        const candle = getLatestCandle();
        socket.push([{
            o: candle.open,
            h: candle.high,
            l: candle.low,
            c: candle.close,
            v: candle.volume,
        }]);
    }, 1000);
});

Python

import asyncio
from layerscale import AsyncLayerScale, WsFlashReady

async def main():
    async with AsyncLayerScale("http://localhost:8080", api_key="LS-...") as client:
        session = await client.sessions.create(
            type="ohlcv",
            prompt="Monitor ETH/USD for breakout signals.",
            flash=[
                {"query": "Is a breakout imminent?", "max_tokens": 8},
                {"query": "What's the key resistance level?", "max_tokens": 16},
            ],
            mark_prefix=True,
        )

        async with client.sessions.stream(session.session_id) as socket:
            async def push_loop():
                while True:
                    candle = get_latest_candle()  # your feed
                    await socket.push([{
                        "o": candle.open,
                        "h": candle.high,
                        "l": candle.low,
                        "c": candle.close,
                        "v": candle.volume,
                    }])
                    await asyncio.sleep(1)

            asyncio.create_task(push_loop())

            async for event in socket:
                if isinstance(event, WsFlashReady):
                    d = event.data
                    print(f"[FLASH] {d.query}: {d.value} ({d.confidence})")

asyncio.run(main())

When to Use Which Client

Use Case	Recommended Client
Chat completions, tool calling	OpenAI SDK or Anthropic SDK
Streaming data ingestion	LayerScale SDK
Flash Queries	LayerScale SDK
Session management	LayerScale SDK
WebSocket connections	LayerScale SDK
Quick prototyping	OpenAI SDK (most familiar to developers)