@blankstate/sdk

TypeScript client for the Blankstate API. Zero runtime dependencies beyond fetch.

Measure interactions against behavioral protocols — get a score, per-metamarker resonance, signal analysis, and fidelity assessment. The engine runs server-side; this package handles auth, request formatting, and typed responses.

Install

npm install @blankstate/sdk

Requires Node.js >= 20. Uses native fetch — no polyfills needed.

Quick Start

import { Blankstate } from '@blankstate/sdk';

const bks = new Blankstate({ token: process.env.BLANKSTATE_API_TOKEN! });

const result = await bks.sense('proto-xxx:1.0', 'The agent resolved the issue promptly.');

console.log(result.score);         // 0.82
console.log(result.resonance);     // { "Solution-Oriented": 0.96, "Empathy": 0.41 }
console.log(result.fidelity);      // { index: 0.74, sufficient: true }
console.log(result.ics.consumed);  // 2

API

new Blankstate(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | token | string | — | API token (required) | | apiUrl | string | https://api.blankstate.ai | API base URL |

Sense

Measure content against a protocol. The measurement engine version is set by the protocol definition — not by the caller.

const result = await bks.sense(protocolId, content, {
  language: 'en',                    // default: 'en'
  profile: 'detailed',               // 'raw' | 'detailed' | 'discovery'
  depth: 'full',                     // 'measure' | 'full' (includes entities + evidence)
});

// result.score           — overall alignment (0.0–1.0)
// result.resonance       — per-metamarker scores
// result.signal          — spread, coherence, dominant mode (v1.5 protocols)
// result.actant_flow     — entity influence direction (v1.5 protocols)
// result.temporal        — temporal trend analysis (v1.5 protocols)
// result.fidelity        — signal quality assessment
// result.ics             — ICS consumed, pool balance

Measure against multiple protocols in parallel:

const results = await bks.senseMultiple(
  ['proto-aaa:1.0', 'proto-bbb:2.0'],
  content,
);
// returns Map<protocolId, SenseResponse>

Fidelity Check — 0 ICS

Pre-check whether content has enough signal for measurement before spending ICS:

const check = await bks.fidelityCheck('proto-xxx:1.0', content);

check.fidelity.sufficient;    // true | false
check.fidelity.index;         // 0.74
check.estimated_ics;          // { min: 1, max: 3, typical: 2 }

Status and Usage

const status = await bks.status();
// status.authenticated
// status.sgm_versions      — { "1.0": "stable", "1.5": "preview" }
// status.ics.remaining
// status.ics.member        — member-level cap if set

const usage = await bks.usage();
// usage.ics_used, usage.ics_remaining, usage.ics_total

const estimate = await bks.usageEstimate(contentLength, 'text');
// estimate.estimated_ics, estimate.will_exceed_quota

Protocols

// List protocols in your account
const protocols = await bks.protocols();
// [{ id, name, versions, sgm_version, taxonomy }]

// Get a protocol's full definition
const def = await bks.protocol('proto-xxx:1.0');
// def.id, def.name, def.version, def.sgm_version
// def.metamarkers  — [{ label, description, importance }]
// def.taxonomy, def.supported_modalities

Health

const ok = await bks.healthy(); // true | false — 0 ICS, no auth required

Error Handling

import { BlankstateAPIError } from '@blankstate/sdk';

try {
  await bks.sense(protocolId, content);
} catch (err) {
  if (err instanceof BlankstateAPIError) {
    console.log(err.status);          // HTTP status code
    console.log(err.message);         // Error description

    if (err.isAuthError())   { /* 401/403 — check your token */ }
    if (err.isQuotaError())  { /* 429 — ICS quota exceeded */ }
    if (err.isServerError()) { /* 5xx — retryable */ }
  }
}

Concepts

| Term | Description | |------|-------------| | Protocol | A behavioral sensor — defines metamarkers that characterize an interaction pattern | | Metamarker | A named behavioral signal (e.g., "Empathy", "Escalation Risk") | | Resonance | Activation strength of each metamarker (0.0–1.0) | | Score | Aggregate alignment between content and the protocol | | Fidelity | Signal quality — whether content has enough substance for reliable measurement | | ICS | Interaction Computed Signal — billing unit per measurement | | SGM | Blankstate measurement engine — v1.0 (stable), v1.5 (extended signal analysis) |

Requirements

• Node.js >= 20.0.0
• API token from atlas.blankstate.ai

Issues

github.com/blankstate-ai/blankstate-node/issues

License

MIT — blankstate.ai