sinc-prompt

Validator and converter for the sinc-prompt format — a structured LLM prompt specification based on the Nyquist-Shannon sampling theorem.

A raw prompt is 1 sample of a 6-band signal. Nyquist requires 6 samples. Sending a raw prompt = 6:1 undersampling = guaranteed aliasing (hallucination). sinc-prompt enforces the 6-band structure that eliminates this.

Formula

x(t) = Σ x(nT) · sinc((t - nT) / T)

The 6 Bands

| Band | Index | Weight | Purpose | |------|-------|--------|---------| | PERSONA | 0 | 7.0% | Who should answer | | CONTEXT | 1 | 6.3% | Situation and facts | | DATA | 2 | 3.8% | Specific inputs | | CONSTRAINTS | 3 | 42.7% | Rules to follow | | FORMAT | 4 | 26.3% | Output structure | | TASK | 5 | 2.8% | The objective |

Weights derived from MATLAB simulation (275 observations, p<0.001).

Install

npm install sinc-prompt

Quick Start

import { validate, parse, format, computeSNR, nyquistCompleteness, scatter, toJSON } from 'sinc-prompt';

// Validate a sinc-prompt object
const result = validate(myPromptJSON);
if (!result.valid) {
  console.error(result.errors);
}

// Parse from JSON string
const sinc = parse(jsonString);

// Format into readable prompt
const prompt = format(sinc);
console.log(prompt);
// [PERSONA]
// You are a senior engineer...
//
// [CONTEXT]
// The system uses PostgreSQL 15...
// ...

// Compute signal-to-noise ratio
const snr = computeSNR(sinc);
console.log(`SNR: ${snr.snr}`);  // 0.0 - 1.0

// Check Nyquist completeness
const completeness = nyquistCompleteness(sinc);
console.log(`Completeness: ${completeness}`);  // 0.0 - 1.0

// Scatter a raw prompt into 6 bands (heuristic, no LLM)
const scattered = scatter("You are an expert. Fix the login bug. Must not break existing tests.");
console.log(JSON.stringify(toJSON(scattered), null, 2));

// Export back to JSON
const json = toJSON(sinc);

API Reference

validate(json: unknown): ValidationResult

Validates a sinc-prompt JSON object against the schema. Checks for all 6 mandatory bands, correct indices, no duplicates, and non-empty content.

Returns { valid: boolean, errors: string[] }.

parse(input: string | object): SincPrompt

Parses a sinc-prompt JSON string or object into a typed SincPrompt. Throws if validation fails.

format(sinc: SincPrompt): string

Formats a SincPrompt into a human-readable prompt string with [BAND]\ncontent blocks in canonical order.

computeSNR(sinc: SincPrompt): SNRResult

Computes the signal-to-noise ratio using filler-word analysis weighted by band importance.

Returns { snr: number, zones: Record<BandName, number>, signal: Record<BandName, number>, noise: Record<BandName, number> }.

nyquistCompleteness(sinc: SincPrompt): number

Returns a weighted completeness score (0.0 - 1.0) using MATLAB-derived importance weights. Full content (>=20 chars) gets full weight; minimal content gets half.

scatter(rawPrompt: string): SincPrompt

Decomposes an unstructured prompt string into the 6 sinc bands using keyword heuristics. No LLM call required. Empty bands get [TODO: specify <band>] placeholders.

toJSON(sinc: SincPrompt): Record<string, unknown>

Exports a SincPrompt back to a plain object conforming to the sinc-prompt-v1 JSON schema.

Types

interface SincFragment {
  n: number;    // Band index (0-5)
  t: string;    // Band label
  x: string;    // Band content
}

interface SincPrompt {
  formula: string;
  T: string;
  fragments: SincFragment[];
}

interface ValidationResult {
  valid: boolean;
  errors: string[];
}

type BandName = 'PERSONA' | 'CONTEXT' | 'DATA' | 'CONSTRAINTS' | 'FORMAT' | 'TASK';

JSON Schema

The embedded JSON Schema (draft-07) is available as an export:

import { SINC_PROMPT_SCHEMA } from 'sinc-prompt';

Schema ID: https://tokencalc.pro/schema/sinc-prompt-v1.json

Spec & Paper

• Specification: tokencalc.pro/spec
• Repository: github.com/mdalexandre/sinc-prompt-js

Zero Dependencies

This package has zero runtime dependencies. Pure TypeScript compiled to ES2020.

License

MIT