paratext-envelope

Cognitive metadata middleware for agent-to-agent communication.

When AI agents talk to each other, they lose all the metadata about how something was said -- confidence, cognitive register, intent. Paratext Envelope generates a JSON metadata sidecar that travels alongside agent messages, telling the receiving agent what the sending agent's language reveals about its reasoning.

Install

npm install paratext-envelope

Requires an Anthropic API key. The package uses Claude's multilingual capabilities to generate cognitive routing metadata.

Quick Start

import { generateEnvelope } from 'paratext-envelope';

const envelope = await generateEnvelope(
  "The infrastructure costs will exceed projections by 15%, but the team feels confident they can absorb it through Q3 optimization."
);

console.log(envelope.message_meta.dominant_register); // "precision"
console.log(envelope.message_meta.overall_confidence); // 0.91
console.log(envelope.clauses[0].register.selected);    // "precision"
console.log(envelope.clauses[1].register.selected);    // "relational"

What It Does

The pipeline segments text into cognitive clauses, routes each clause through 6 languages in parallel (German/precision, Spanish/embodiment, French/nuance, Japanese/relational, Portuguese/warmth, English/baseline), and scores which language each thought most naturally lives in. Those scores become the metadata.

The envelope format:

{
  "paratext_version": "0.1",
  "content": "original text",
  "clauses": [{
    "text": "clause text",
    "register": {
      "selected": "precision",
      "source_language": "de",
      "confidence": 0.91,
      "perplexity_differential": 5.4
    },
    "cognitive_mode": "analytical",
    "intent": "assertion",
    "weight": 0.91
  }],
  "message_meta": {
    "overall_confidence": 0.85,
    "dominant_register": "precision",
    "register_distribution": { "precision": 0.36, "embodiment": 0.33 },
    "cognitive_coherence": 0.67
  }
}

Why

Two agents given the same research findings produce measurably different briefings when one has the paratext envelope. Specifically:

• "likely 25-30%" became "18-30%" -- the agent with metadata widened uncertainty ranges to match actual confidence scores
• "broken integration" became "systematic failure to integrate" -- the agent matched the precision register instead of dramatizing
• Isolated risk tiers became compound risk scenarios -- register shifts signaled where the source moved from data to gut feeling

Options

const envelope = await generateEnvelope(text, {
  model: 'claude-sonnet-4-5-20250929',  // default
  onProgress: (step, detail) => {
    console.log(step, detail);
  },
});

Summarize

import { generateEnvelope, summarizeEnvelope } from 'paratext-envelope';

const envelope = await generateEnvelope(text);
const summary = summarizeEnvelope(envelope);
// Returns a compact version with just register, confidence, mode, intent per clause

CLI

npx paratext "Your text here"
npx paratext --json "Your text here"
npx paratext --file input.txt
npx paratext --output result.json "Your text here"

API Server

The package includes an Express server for HTTP access:

node node_modules/paratext-envelope/src/server.mjs

# POST http://localhost:3000/envelope
curl -X POST http://localhost:3000/envelope \
  -H "Content-Type: application/json" \
  -d '{"text": "Your text here"}'

# GET http://localhost:3000/health

Environment

Set ANTHROPIC_API_KEY in your environment or .env file.

License

MIT