ptl3tools

Photic Token Language v3 — deterministic visual encoding for text and code.

Compiles any text or code into a single spatial matrix (a PTL-3 frame): a square canvas divided into four semantic quadrants with four concentric depth rings. Every sentence maps to a geometric primitive at a specific (quadrant, ring) coordinate.

Same input always produces identical output — guaranteed deterministic.

npm install ptl3tools

Quick start

import { compile, toCompact, toJSON } from 'ptl3tools';

// Compile text
const frame = compile('The API server went down at 3am. The on-call engineer restarted it within 20 minutes.');

// Human-readable compact format
console.log(toCompact(frame, 'incident.english'));
// PTL3:3.0 [incident.english]
//   TECH.2.waveform    ∿  "The API server went down at 3am"              -0.80
//   RELA.3.smooth      ⌇  "The on-call engineer restarted within 20min"  +0.40
// ---
// gv:-0.200 ga:0.040

// Full JSON document for storage or training
const doc = toJSON(frame, { name: 'incident.english', text: 'The API...' });

API

compile(text, canvasSize?)

Compiles any text or code into a PTL-3 frame. Auto-detects input type (natural language, code, HTML, CSS).

import { compile } from 'ptl3tools';

const frame = compile('Your text or code here');
// Returns a frame object with:
// {
//   elements: Array<Element>,  — one per sentence/block
//   rings:    Array<Ring>,
//   cx, cy, maxR, canvasSize,
//   global_valence: number,
//   global_arousal: number,
//   codeMode: boolean,
//   inputType: 'text' | 'code' | 'html' | 'css',
// }

Element fields:

| Field | Type | Description | |-------|------|-------------| | id | number | Zero-indexed element ID | | sentence | string | Source text for this element | | quadrant | string | TECHNICAL, SOMATIC, RELATIONAL, or MACRO | | ring | number | 1–4 (Foundational → Metric) | | geometry | string | Geometric primitive name | | angle | number | Angle in degrees from canvas center | | x, y | number | Absolute canvas position | | valence | number | Sentiment score (−3.0 to +3.0) | | arousal | number | Urgency/intensity (0.0 to 1.0) | | color | string | Hex color for this quadrant |

demodulate(frame)

For code-mode frames, reconstructs a code scaffold from the PTL-3 structure.

import { compile, demodulate } from 'ptl3tools';

const frame    = compile('function chessPiece() {}\nimport { board } from "./board"');
const scaffold = demodulate(frame);
// Returns a code skeleton with TODO placeholders for each structural block

toCompact(frame, name?)

Serializes a frame to the PTL-3 compact text format — human-readable and LLM-parseable.

import { compile, toCompact } from 'ptl3tools';

const frame   = compile('Training run completed. Validation loss is still high.');
const compact = toCompact(frame, 'training-status.english');
// PTL3:3.0 [training-status.english]
//   TECH.4.progress    ◐  "Training run completed"            +0.50
//   TECH.2.waveform    ∿  "Validation loss is still high"     -0.60
// ---
// gv:-0.050 ga:0.000

fromCompact(text)

Parses a compact text frame back into a frame descriptor.

import { fromCompact } from 'ptl3tools';

const frame = fromCompact(`PTL3:3.0 [status.english]
  TECH.2.waveform  ∿  "Build failed"  -0.80
---
gv:-0.80 ga:0.000`);

toJSON(frame, options?)

Builds a full .ptl3.json document for storage, sharing, or model training.

import { compile, toJSON } from 'ptl3tools';

const frame = compile(text);
const doc   = toJSON(frame, {
  name:         'chess.py',        // PTL document name
  text:         originalText,      // source text (optional)
  trainingMode: false,             // true = strip source text
});
// Returns the standard PTL-3 JSON schema

fromJSON(doc, canvasSize?)

Reconstructs a renderable frame from a .ptl3.json document.

import { fromJSON } from 'ptl3tools';

const frame = fromJSON(ptl3JsonDocument);

toTensor(doc)

Converts a PTL document to a 18-dimensional feature matrix for model training.

import { compile, toJSON, toTensor } from 'ptl3tools';

const frame  = compile(text);
const doc    = toJSON(frame, { name: 'doc.english', trainingMode: true });
const tensor = toTensor(doc);
// → Array<Array<number>>, shape: [n_elements, 18]
// Dimensions: [q_oh×4, ring_oh×4, x_norm, y_norm, sin_angle, cos_angle, geom_oh×4, valence, arousal]  (18 total)

parseName(fullName)

Parses a PTL document name into its components.

import { parseName } from 'ptl3tools';

parseName('agatha-christie.book.1');
// → { name: 'agatha-christie', exts: ['book', '1'], domain: 'document',
//     lang: 'prose', sequence: 1, parent: 'agatha-christie.book', ... }

sentimentRegistry

Pluggable multi-language sentiment engine. Ships with English (AFINN-111 + domain extensions).

import { sentimentRegistry } from 'ptl3tools';

// Register French sentiment
sentimentRegistry.register('fr', new Map([
  ['bien', 2], ['mal', -2], ['amour', 3], ['haine', -3],
]));

// Now French text is scored correctly when compiled

Quadrant system

| Quadrant | Position | Color | Domain | |----------|----------|-------|--------| | Technical | NE | #4A90D9 | Code, algorithms, computation | | Somatic | NW | #27AE60 | Body, environment, physical state | | Relational | SW | #E74C3C | People, emotion, interpersonal | | Macro | SE | #95A5A6 | Purpose, society, big-picture |

Ring system

| Ring | Name | Semantic role | |------|------|---------------| | R1 | Foundational | Base state, initial conditions | | R2 | Friction | Problems, errors, conflict | | R3 | Pivot | Decisions, solutions, change | | R4 | Metric | Outcomes, measurements, status |

Compact format symbols

| | R1 | R2 | R3 | R4 | |---|---|---|---|---| | Technical | ● | ∿ | → | ◐ | | Somatic | ⌒ | — | ~ | ◑ | | Relational | ─ | ✕ | ⌇ | ⊣ | | Macro | □ | ■ | ◎ | ⊛ |

LLM integration

The compact format is designed to be emitted and parsed by language models natively.

// System prompt for an LLM emitter
const EMITTER_PROMPT = `You are a PTL-3 encoder. Output responses as PTL-3 compact format.
QUAD: TECH=code/systems  SOMA=body/environment  RELA=people/emotion  MACR=purpose/society
RING: 1=foundation  2=friction  3=pivot  4=metric
FORMAT: PTL3:3.0 [name]\n  QUAD.RING.geom  SYMBOL  "sentence"  VALENCE\n---\ngv:X ga:Y`;

Attestation

Verify on attest →
Collaborated with claude-sonnet-4-6 via Claude Code.