npm package: @lnmp/lnmp
Description: LNMP Protocol - Meta package providing unified access to all LNMP modules
Author: LNMP Team
Latest version: 0.5.6

# LNMP TypeScript SDK

[![npm version](https://badge.fury.io/js/@lnmp%2Flnmp.svg)](https://www.npmjs.com/package/@lnmp/lnmp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/lnmplang/lnmp-sdk-js/actions/workflows/ci.yml/badge.svg)](https://github.com/lnmplang/lnmp-sdk-js/actions/workflows/ci.yml)
[![npm downloads](https://img.shields.io/npm/dm/@lnmp/lnmp.svg)](https://www.npmjs.com/package/@lnmp/lnmp)
[![Node.js Version](https://img.shields.io/node/v/@lnmp/lnmp.svg)](https://nodejs.org)


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

## Installation

```bash
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:

```typescript
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)

```typescript
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).

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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):

| Module | Operation | Speed (ops/sec) |
|--------|-----------|-----------------|
| **Core** | Parse Record | ~284,000 |
| **Core** | Encode Record | ~253,000 |
| **Spatial** | Decode Frame | ~920,000 |
| **Spatial** | Encode Frame | ~491,000 |
| **SFE** | Context Score | ~341,000 |
| **Embedding** | Quantize (1536d) | ~23,000 |
| **Embedding** | Delta (1536d) | ~5,000 |

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

## Documentation

- [**API Reference**](./API.md) - Detailed API guide for all modules.

- [LNMP Protocol Specification](https://github.com/lnmplang/lnmp-protocol)


## Version

Current version: **0.5.5**

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

## License

MIT