briefcase-wasm 2.0.8

WebAssembly bindings for Briefcase AI
Documentation

Briefcase AI WebAssembly

WebAssembly bindings for Briefcase AI - A high-performance SDK for AI observability, replay, and decision tracking.

npm version CI

Features

  • AI Decision Tracking - Capture inputs, outputs, and context for every AI decision
  • High Performance - Rust core compiled to WebAssembly for maximum speed
  • Browser Compatible - Works in modern browsers and Node.js environments
  • Type Safe - Full TypeScript definitions included
  • Zero Dependencies - Self-contained WebAssembly module

Installation

npm install briefcase-wasm

Quick Start

Browser

<!DOCTYPE html>
<html>
<head>
    <script type="module">
        import init, { DecisionSnapshot, Input, Output, SqliteBackend } from './node_modules/briefcase-wasm/briefcase_wasm.js';

        async function run() {
            // Initialize the WASM module
            await init();

            // Create a decision snapshot
            const decision = new DecisionSnapshot('ai_function');

            // Add input and output
            decision.add_input(new Input('user_query', 'Hello world', 'string'));
            decision.add_output(new Output('response', 'Hello back!', 'string').with_confidence(0.95));

            // Save to storage
            const storage = SqliteBackend.in_memory();
            const decisionId = storage.save_decision(decision);

            console.log('Saved decision:', decisionId);
        }

        run();
    </script>
</head>
<body>
    <h1>Briefcase AI WebAssembly Demo</h1>
</body>
</html>

Node.js

import init, { DecisionSnapshot, Input, Output, SqliteBackend } from 'briefcase-wasm';

async function main() {
    // Initialize the WASM module
    await init();

    // Create a decision snapshot
    const decision = new DecisionSnapshot('ai_function');

    // Add input and output
    decision.add_input(new Input('user_query', 'Hello world', 'string'));
    decision.add_output(new Output('response', 'Hello back!', 'string').with_confidence(0.95));

    // Save to storage
    const storage = SqliteBackend.in_memory();
    const decisionId = storage.save_decision(decision);

    console.log('Saved decision:', decisionId);
}

main().catch(console.error);

TypeScript

import init, { DecisionSnapshot, Input, Output, SqliteBackend } from 'briefcase-wasm';

async function trackAIDecision(userInput: string, aiResponse: string): Promise<string> {
    await init();

    const decision = new DecisionSnapshot('ai_chat')
        .add_input(new Input('user_message', userInput, 'string'))
        .add_output(new Output('ai_response', aiResponse, 'string').with_confidence(0.95))
        .with_execution_time(150.5)
        .add_tag('model', 'gpt-4')
        .add_tag('version', '1.0');

    const storage = SqliteBackend.file('chat_history.db');
    return storage.save_decision(decision);
}

API Reference

DecisionSnapshot

The main class for tracking AI decisions:

class DecisionSnapshot {
    constructor(functionName: string);

    add_input(input: Input): DecisionSnapshot;
    add_output(output: Output): DecisionSnapshot;
    with_module(moduleName: string): DecisionSnapshot;
    with_execution_time(timeMs: number): DecisionSnapshot;
    add_tag(key: string, value: string): DecisionSnapshot;
}

Input/Output

Data structures for function inputs and outputs:

class Input {
    constructor(name: string, value: any, dataType: string);
}

class Output {
    constructor(name: string, value: any, dataType: string);
    with_confidence(confidence: number): Output;
}

Storage Backends

SqliteBackend

class SqliteBackend {
    static in_memory(): SqliteBackend;
    static file(path: string): SqliteBackend;

    save_decision(decision: DecisionSnapshot): string;
    load_decision(id: string): DecisionSnapshot | null;
}

Model Parameters

Track model configuration for reproducibility:

import { ModelParameters } from 'briefcase-wasm';

const params = new ModelParameters('gpt-4')
    .with_provider('openai')
    .with_version('1.0')
    .with_parameter('temperature', 0.7)
    .with_parameter('max_tokens', 1000);

decision.with_model_parameters(params);

Execution Context

Capture environment for deterministic replay:

import { ExecutionContext } from 'briefcase-wasm';

const context = new ExecutionContext()
    .with_runtime_version('Node 18.0.0')
    .with_dependency('openai', '4.0.0')
    .with_random_seed(42)
    .with_env_var('MODEL_ENDPOINT', 'https://api.openai.com');

decision.with_context(context);

Use Cases

  • Browser-based AI Apps - Track decisions in client-side applications
  • Node.js Services - High-performance decision tracking for backend services
  • Edge Computing - Lightweight observability at the edge
  • Development Tools - Debug and analyze AI model behavior
  • A/B Testing - Compare model variants in production

Performance

  • Fast Initialization - WASM module loads in ~10ms
  • Low Memory Usage - Optimized for resource-constrained environments
  • High Throughput - Process thousands of decisions per second
  • Small Bundle Size - ~77KB compressed package

Browser Compatibility

  • Chrome 57+
  • Firefox 52+
  • Safari 11+
  • Edge 16+

Requires WebAssembly support and ES modules.

Node.js Compatibility

  • Node.js 14+
  • ES modules support required

TypeScript Support

Full TypeScript definitions are included. No additional @types package needed.

Contributing

This package is part of the Briefcase AI Core project.

  1. Fork the repository
  2. Make your changes in crates/wasm/
  3. Run tests: wasm-pack test --node
  4. Submit a pull request

Support

License

GPL-3.0 License - see LICENSE file for details.

Related Packages

Briefcase AI - Making AI decisions transparent, reproducible, and observable.