Voice AI

Build an AI Assembly Language Tutor with WebAssembly and Telnyx Inference

Teaching assembly language has a tooling problem. Most university courses use the LC-3 — a 16-bit instruction set architecture with 16 opcodes and 8 registers, simple enough to teach in a semester, complex enough to demonstrate how a CPU actually works. The standard simulator is a desktop application last updated years ago. Students write code, assemble it, step through execution, and when they get stuck — why did the zero flag set? why is R2 holding the wrong value? — they're on their own.

This walkthrough builds a browser-based LC-3 assembly tutor that solves both problems. The VM runs entirely client-side via C compiled to WebAssembly, so every instruction executes at near-native speed with zero latency. An AI tutor powered by Telnyx Inference sees the full machine state and answers contextual questions about what's happening at each step.

The canonical code example lives in the Telnyx code examples repo:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-assembly-tutor-c

Live demo: https://ai-assembly-tutor-v2-9a6d593b-1.telnyxcompute.com/

What This Example Builds

A three-panel browser application for interactive assembly language learning:

PanelWhat it shows
Left — Code EditorWrite LC-3 assembly, click Assemble, load example programs
Center — VM State8 registers (R0–R7) in hex/decimal, condition flags (N/Z/P), memory viewer centered on PC, output console
Right — AI TutorChat interface with quick-ask buttons, contextual explanations from DeepSeek-V4.1-Flash

The application has two modes of execution:

  • Step — Execute one instruction. The UI updates registers, flags, and memory after each step so students can trace exactly what the machine does.
  • Run — Execute instructions continuously (~100 per frame) until HALT. Useful for programs where step-by-step is tedious.

Five example programs are included: Hello World, Add Numbers, Countdown (loop with branch), Fibonacci, and Calculator (I/O with TRAP routines).

Why This Matters

The LC-3 AI Assembly Tutor exercises two Telnyx products in a real educational workflow — AI Inference for the tutor and Edge Compute for the entire hosting stack. The architecture demonstrates a pattern that extends beyond assembly language: a compute-intensive client (WASM), a knowledge API (LLM inference), and a thin backend that connects them.

Developers and educators use this pattern for:

  • Interactive assembly courses — Replace desktop simulators with a browser tool that includes an AI teaching assistant
  • Computer architecture labs — Give students a VM they can step through with explanations at every instruction
  • Self-paced learning — A tutor available 24/7 that never gets tired of explaining why the P flag set after an ADD
  • Code review tools — The same pattern (code context + AI explanation) applies to any language
  • WASM-powered educational tools — Compile existing C/C++ tools to run in the browser

Products Used

telnyx_products: [AI Inference, Edge Compute]

Telnyx AI Inference provides the intelligence — DeepSeek-V4.1-Flash answers student questions with full VM context (registers, flags, current instruction, source code). Telnyx Edge Compute hosts the entire application — a single TypeScript file that embeds all frontend assets and serves the AI tutor API endpoint.

Architecture

  Browser (Client-Side)
  ┌─────────────────────────────────────────────┐
  │  Code Editor → Two-Pass Assembler (JS)       │
  │                    ↓                         │
  │  LC-3 VM (C → WASM, 379 lines)              │
  │  ├─ 16 opcodes, 8 registers, N/Z/P flags    │
  │  ├─ 65,536-word memory, programs at x3000    │
  │  └─ TRAP routines (GETC, OUT, PUTS, HALT)   │
  │                    ↓                         │
  │  VM State Panel (registers, flags, memory)   │
  │                                              │
  │  AI Tutor Panel ─────────────────────────────┤
  │  │ POST /api/explain                         │
  └──┴───────────────────────────────────────────┘
           ↓
  ┌──────────────────────────────────────────────┐
  │  Telnyx Edge Compute (edge/index.ts)         │
  │  ├─ Serves all static assets (embedded)      │
  │  ├─ Rate limiting (20 req/min per IP)        │
  │  └─ Calls Telnyx Inference API               │
  └──────────────────────────────────────────────┘
           ↓
  ┌──────────────────────────────────────────────┐
  │  Telnyx Inference API                        │
  │  POST /v2/ai/openai/chat/completions         │
  │  Model: deepseek-ai/DeepSeek-V4.1-Flash     │
  │  Temperature: 0.3 (precise explanations)     │
  │  Max tokens: 4096                            │
  └──────────────────────────────────────────────┘

The LC-3 Virtual Machine

The VM is 379 lines of C compiled to WebAssembly via Emscripten. It implements the complete LC-3 instruction set:

OpcodeMnemonicPurpose
0BRBranch (conditional on N/Z/P flags)
1ADDAdd (register or 5-bit immediate)
2LDLoad (PC-relative addressing)
3STStore (PC-relative)
4JSR/JSRRJump to subroutine
5ANDBitwise AND (register or 5-bit immediate)
6LDRLoad register (base + 6-bit offset)
7STRStore register (base + offset)
9NOTBitwise NOT
10LDILoad indirect (double dereference)
11STIStore indirect
12JMP/RETJump or return from subroutine
14LEALoad effective address (not memory contents)
15TRAPSystem call (GETC, OUT, PUTS, IN, PUTSP, HALT)

The C code exports functions through Emscripten for JavaScript to call:

EXPORT void vm_init(void);                        // Reset VM
EXPORT void vm_load_program(uint16_t *p, int n);  // Load binary at x3000
EXPORT int vm_step(void);                         // Execute 1 instruction, return opcode
EXPORT uint16_t vm_get_register(int r);           // Read R0-R7, PC (8), COND (9)
EXPORT uint16_t vm_get_memory(uint16_t addr);     // Read a memory word
EXPORT int vm_is_halted(void);                    // Check if HALT was executed
EXPORT const char* vm_get_output(void);           // Get buffered TRAP output
EXPORT void vm_clear_output(void);                // Clear output buffer
EXPORT void vm_queue_input(char c);               // Queue input for GETC/IN

The JavaScript WASM bridge calls these via cwrap:

export async function loadVM() {
  Module = await LC3Module();
  vmInit = Module.cwrap('vm_init', null, []);
  vmStep = Module.cwrap('vm_step', 'number', []);
  vmGetRegister = Module.cwrap('vm_get_register', 'number', ['number']);
  vmGetMemory = Module.cwrap('vm_get_memory', 'number', ['number']);
  vmIsHalted = Module.cwrap('vm_is_halted', 'number', []);
  vmGetOutput = Module.cwrap('vm_get_output', 'string', []);
  vmClearOutput = Module.cwrap('vm_clear_output', null, []);
}

The Two-Pass Assembler

The assembler is 388 lines of JavaScript running entirely client-side. It compiles LC-3 assembly source to a Uint16Array binary.

Pass 1 scans for labels and builds a symbol table:

// If the first token isn't an opcode or directive, it's a label
if (!(first in OPCODES) && !first.startsWith('.')) {
  symbols[tokens[0].toUpperCase()] = addr;  // Label → address
}

Pass 2 encodes instructions, resolving label references into PC-relative offsets:

case 1:  // ADD
  instr = (opcode << 12) | (dr << 9) | (sr1 << 6);
  if (immediate_flag) {
    instr |= (1 << 5) | fitBits(imm5, 5);  // Immediate mode
  } else {
    instr |= sr2;                            // Register mode
  }

Supported directives: .ORIG (set origin address), .END (end of program), .FILL (store literal), .BLKW (allocate block), .STRINGZ (null-terminated string).

The AI Tutor

When a student asks a question, the frontend builds a context object containing the full VM state:

const context = {
  registers: { R0: 0x3003, R1: 0x0000, /* ... */ },
  pc: 'x3002',
  flags: { N: false, Z: false, P: true },
  halted: false,
  currentInstruction: 'PUTS',
  lastOpcode: 'LEA',
  code: '.ORIG x3000\n  LEA R0, HELLO\n  PUTS\n  HALT\n...'
};

The Edge backend formats this into a user message and sends it to Telnyx Inference:

const payload = {
  model: 'deepseek-ai/DeepSeek-V4.1-Flash',
  messages: [
    { role: 'system', content: SYSTEM_PROMPT },
    { role: 'user', content: userMessage }
  ],
  max_tokens: 4096,
  temperature: 0.3
};

The system prompt encodes deep LC-3 domain knowledge — all 16 opcodes, addressing modes, condition flag behavior, TRAP routines, and common student misconceptions (like the difference between LEA and LD, or how BR checks flags set by the previous instruction).

The Edge Compute Backend

The entire backend is a single TypeScript file (edge/index.ts, 743 lines). It embeds all frontend assets as string constants:

const ASSETS: Record<string, { content: string | Buffer; type: string }> = {};
ASSETS['/'] = { type: 'text/html; charset=utf-8', content: `<!DOCTYPE html>...` };
ASSETS['/style.css'] = { type: 'text/css; charset=utf-8', content: `...` };
// JavaScript modules, WASM glue...

const WASM_B64 = 'AGFzbQEAAAABFgV...';  // WASM binary as base64
const WASM_BUF = Buffer.from(WASM_B64, 'base64');

The HTTP server routes requests to static assets, the WASM binary, or the AI endpoint:

const server = http.createServer(async (req, res) => {
  if (url === '/api/explain' && req.method === 'POST') {
    // Rate limit → parse body → build context → call Inference → return response
  }
  if (url === '/wasm/lc3.wasm') {
    // Serve WASM binary from buffer
  }
  if (ASSETS[url]) {
    // Serve embedded static asset
  }
});

Deploy with one command:

cd edge
npm install
telnyx-edge ship

Try the Live Demo

Open the live demo in any modern browser:

https://ai-assembly-tutor-v2-9a6d593b-1.telnyxcompute.com/

  1. Click an example program (start with Hello World)
  2. Click Assemble to compile the source
  3. Click Step to execute one instruction at a time
  4. Watch registers, flags, and memory update in the center panel
  5. Click "What does this do?" or type a question to ask the AI tutor

Run It Locally

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-assembly-tutor-c

Build the WASM VM (requires Emscripten):

bash build.sh
# Outputs: web/wasm/lc3.js + web/wasm/lc3.wasm

Serve the frontend locally:

cd web
python3 -m http.server 8080
# Open http://localhost:8080

Deploy the Edge backend:

cd ../edge
cp .env.example .env  # Add your TELNYX_API_KEY
npm install
telnyx-edge ship

Going to Production

This example is a working demo. For production deployment:

  • Conversation memory — Add conversation history to the AI tutor so students can have multi-turn discussions ("Why did the flag change?" → "What would happen if I used BRn instead?")
  • Breakpoints — Let students set breakpoints and run until a specific address, instead of stepping instruction by instruction through long programs
  • Code sharing — URL-encode programs so students can share links to their code with the AI's state
  • Persistent sessions — Store student progress and conversation history server-side
  • Model selection — Test different models for accuracy on LC-3 specifics; DeepSeek-V4.1-Flash is fast and accurate, but larger models may give more detailed explanations for complex programs
  • Rate limiting — The demo's in-memory rate limiter works for a single instance; production needs Redis or a distributed counter
  • Error recovery — If inference fails, show a friendly message instead of a broken chat panel

Frequently Asked Questions

Do I need a Telnyx account to try the demo? No. The live demo at https://ai-assembly-tutor-v2-9a6d593b-1.telnyxcompute.com/ is publicly accessible. You only need a Telnyx account and API key if you want to deploy your own instance.

Why is the VM written in C instead of JavaScript? Performance and portability. The LC-3 VM is a tight loop (fetch-decode-execute) that benefits from WASM's near-native speed. C also makes the implementation closer to how a real CPU works, which is educational in itself. And the same C code could compile to native for a command-line simulator.

How does the AI tutor know what's happening in the VM? Every question sends the full VM state — all register values, the PC, condition flags, the instruction about to execute, the last opcode, and the student's source code — to the inference endpoint. The system prompt encodes the complete LC-3 ISA, so the model can interpret the state and give precise explanations.

Can I use a different AI model? Yes. Change the INFERENCE_MODEL constant in edge/index.ts to any model available on Telnyx AI Inference. DeepSeek-V4.1-Flash was chosen for its speed and accuracy on code-related questions. See the available models list.

Is the assembler complete? It handles all 16 LC-3 opcodes, all addressing modes, and the standard directives (.ORIG, .END, .FILL, .BLKW, .STRINGZ). It does not handle macros, includes, or the full TRAP aliases — you can write TRAP x25 but also HALT directly.

What browsers are supported? Any browser with WebAssembly support — Chrome, Firefox, Safari, Edge. The WASM module loads asynchronously and the UI renders once it's ready.

Why temperature 0.3? Assembly language explanations need to be precise. "R2 gets the sum of R0 and R1" is correct. "R2 probably has something from the addition" is not helpful for a student debugging their program. Low temperature reduces variance in factual statements.

Ready to build with low-latency voice AI?

Join developers building the future of real-time conversations