LNMP TypeScript SDK

This package provides a unified interface for working with the LNMP (LLM Native Minimal Protocol) in JavaScript and TypeScript.

Installation

npm install @lnmp/lnmp

Requirements.

• Node.js: >= 18.0.0
• TypeScript: >= 5.0.0 (for TypeScript projects)

Usage

0. FID Registry (Field ID Constants)

The SDK includes the official LNMP Field ID registry with 140+ standardized constants:

import { FID, FID_NAMES } from '@lnmp/lnmp';

// Use type-safe constants instead of magic numbers
const userField = { fid: FID.USER_ID, value: 12345 };
const timestampField = { fid: FID.TIMESTAMP, value: Date.now() };

// Reverse lookup for debugging
console.log(FID_NAMES[12]); // "user_id"

// Available categories: Core, Spatial, Embeddings, Sensors, ML/LLM, etc.

Benefits: Type-safe field references, IDE autocomplete, consistent cross-platform.

1. Core & Codec (Parsing/Encoding)

import { Parser, Encoder, RecordBuilder } from '@lnmp/lnmp';

// Parse LNMP text
const text = 'F12=14532;F7=1;F23=[admin,dev]';
const parser = new Parser(text);
const record = parser.parseRecord();

// Create records with RecordBuilder
const newRecord = new RecordBuilder()
  .addField({ fid: 12, value: { type: 'Int', value: 14532 } })
  .addField({ fid: 7, value: { type: 'Bool', value: true } })
  .build();

// Encode to canonical format
const encoder = new Encoder();
const output = encoder.encode(newRecord);
console.log(output); // F7=1\nF12=14532

2. Envelope (Metadata)

Wrap records with operational metadata (timestamp, source, trace ID).

import { Envelope } from '@lnmp/lnmp';

const envelope = Envelope.wrap(record, {
    source: 'sensor-node-01',
    trace_id: 'abc-123',
    labels: { env: 'prod' }
});

// Convert to/from HTTP headers
const headers = Envelope.toHeaders(envelope);
const restoredMetadata = Envelope.fromHeaders(headers);

3. Network (Routing & QoS)

Make intelligent routing decisions and calculate message importance.

import { Network } from '@lnmp/lnmp';

const msg = {
    envelope: envelope,
    kind: 'Event',
    priority: 200,
    ttl_ms: 5000
};

// Calculate importance (0.0 - 1.0)
const score = Network.importance(msg);

// Decide routing (SendToLLM, ProcessLocally, Drop)
const decision = Network.decide(msg);

4. Embedding (Vectors & Quantization)

Handle vector embeddings, delta updates, and quantization.

import { Embedding, QuantScheme } from '@lnmp/lnmp';

const vec1 = [0.1, 0.2, 0.3];
const vec2 = [0.2, 0.3, 0.4];

// Compute delta (bandwidth optimization)
const delta = Embedding.computeDelta(vec1, vec2);
const reconstructed = Embedding.applyDelta(vec1, delta);

// Quantization (compression)
const quantized = Embedding.quantize(vec1, QuantScheme.QInt8); // 4x compression
const restored = Embedding.dequantize(quantized);

5. Spatial (Streaming)

Encode and decode spatial frames for hybrid reality streams.

import { Spatial } from '@lnmp/lnmp';

const frame = {
    header: {
        mode: 'Absolute',
        sequence_id: 1,
        timestamp: BigInt(Date.now()) * 1000000n, // ns
        checksum: 0
    },
    payload: {
        S10: { // SpatialState
            position: { x: 10, y: 20, z: 30 },
            velocity: { vx: 1, vy: 0, vz: 0 },
            orientation: { pitch: 0, yaw: 0, roll: 0 }
        }
    }
};

const bytes = Spatial.encodeFrame(frame);
const decoded = Spatial.decodeFrame(bytes);

6. Sanitization

Clean untrusted input before parsing.

import { Sanitizer } from '@lnmp/lnmp';

const dirty = '  "Hello"   ';
const clean = Sanitizer.sanitize(dirty); // "Hello"

7. LLB (Explain Mode)

Generate human-readable explanations for LNMP records.

import { ExplainEncoder } from '@lnmp/lnmp';

const dict = { 12: "user_id", 7: "is_active" };
const explanation = ExplainEncoder.encode(record, dict);
// Output:
// F7:b=1              # is_active
// F12:i=14532         # user_id

8. SFE (Context Scoring)

Score contexts for RAG and LLM prioritization.

import { ContextScorer } from '@lnmp/lnmp';

const profile = ContextScorer.score(envelope);
console.log(profile.freshness_score); // 0.0 - 1.0
console.log(profile.risk_level);      // Low, Medium, High, Critical

Features

• ✅ FID Registry: 140+ official Field ID constants with type safety
• ✅ Core: Full TypeScript support with strict typing
• ✅ Codec: Parse/Encode LNMP text format (canonical)
• ✅ Envelope: Metadata wrapping & HTTP header interop
• ✅ Network: AI-driven routing & importance scoring
• ✅ Embedding: Vector delta compression & quantization (QInt8, QInt4, Binary)
• ✅ Spatial: Efficient spatial frame streaming
• ✅ LLB: Explain mode for debugging & LLM input
• ✅ SFE: Context scoring & risk assessment
• ✅ WASM: High-performance Rust bindings via WebAssembly

Performance

Benchmarks run on M-series Mac (Single Thread):

Note: Spatial operations are extremely fast due to zero-copy WASM memory access where possible.

Documentation

• API Reference - Detailed API guide for all modules.

• LNMP Protocol Specification

Version

Current version: 0.5.5

Matches Rust implementation patterns from LNMP Protocol v0.5.16 with official FID registry.

License

MIT