Add Harmonic after your model call.

HCS Specification Library

The Harmonic Constitutional Specification (HCS) series defines the implementation-independent constitutional architecture behind continuation governance.

HCS-000 → HCS-001 → HCS-002 → HCS-003 → HCS-004 → HCS-005 → HCS-006 → HCS-099

View the HCS Library · Download the complete HCS v1.0 ZIP

Flow

User → LLM / Agent → Harmonic → constitutional determination → execution directive → response or execution

Determination: PERMITTED / CONSTRAINED / ESCALATED / REFUSED / EMERGENCY_CONTINUITY
Directive:     ALLOW / CONSTRAIN / ESCALATE / BLOCK

Frozen V4.0 Single-Call Contract

POST /api/evaluate is the frozen V4.0 production pathway. Successful Governance+ responses identify runtime_version: "4.0.0".

Vocabulary: the constitutional determination is the canonical outcome (PERMITTED, CONSTRAINED, ESCALATED, REFUSED, or EMERGENCY_CONTINUITY). The execution directive is the corresponding downstream instruction (ALLOW, CONSTRAIN, ESCALATE, or BLOCK). These are different fields with different meanings.

The caller supplies the attributable present-state facts. Harmonic does not infer domain state from raw observations. For a material transition, use understanding_state together with state_transition.

{
  "packet_id": "case-001-v40",
  "requested_action": { "type": "clinical_order", "scope": ["care_plan"] },
  "understanding_state": {
    "current": false,
    "complete": true,
    "provenance_preserved": true,
    "applicable": true,
    "confidence": 0.96,
    "source_ids": ["obs-002"],
    "unresolved_tensions": [],
    "missing_information": [],
    "revision_status": "superseded"
  },
  "state_transition": {
    "prior_state_ref": "state-001",
    "new_observation_refs": ["obs-002"],
    "relationship": "material_contradiction",
    "prior_state_status": "superseded",
    "revalidation_required": true,
    "attributable_source": "institutional-source",
    "observed_at": "2026-08-14T14:00:00.000Z",
    "scope": ["care_plan"]
  },
  "declared_reality": {
    "current_state_claims": ["Previously declared state remains the historical baseline"],
    "last_verified_at": "2026-08-14T13:30:00.000Z"
  },
  "observed_reality": {
    "signals": [{ "statement": "New attributable observation materially conflicts with continued reliance on the prior state" }]
  },
  "authority_chain": {
    "subject": "clinical-agent-1",
    "issuer": "hospital-ops",
    "scope": ["care_plan"],
    "last_verified_at": "2026-08-14T14:00:00.000Z",
    "chain": [
      { "actor": "clinical-agent-1", "status": "active" },
      { "actor": "hospital-ops", "status": "active" }
    ]
  },
  "revocation_state": {
    "last_revocation_check_at": "2026-08-14T14:00:00.000Z",
    "known_revocations": []
  },
  "present_state_provenance": {
    "attributable_source": "institutional-source",
    "established_at": "2026-08-14T14:00:00.000Z",
    "epistemic_status": "ESTABLISHED",
    "evidence_refs": ["obs-002"]
  },
  "consequence_profile": {
    "level": "high",
    "reversibility": "reversible",
    "execution_surface": "clinical_order"
  },
  "safeguards": { "operator_review_confirmed": true }
}

Material-transition semantics: relationship: "material_contradiction" or prior_state_status: "superseded" makes reliance on the prior state non-current and produces an Understanding Continuity block until revalidation. revalidation_required: true without a superseding/material contradiction produces an explicit revalidation requirement rather than silently inferring one.

Authority revocation: populate revocation_state.known_revocations with objects containing target (or subject/actor) and/or scope. A matching subject or requested scope is treated as revoked.

Historical snapshots: prior_snapshot_ref is not part of the V4.0 single-call contract. Use the evidence-preservation/reconstruction APIs when a separately preserved historical snapshot must be referenced.

cURL

curl -X POST "https://www.solace-harmonic.com/api/evaluate" \
  -H "Authorization: Bearer hs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"response":"The assistant recommends stopping medication immediately.","consequence_level":"high"}'

Node

async function evaluateWithHarmonic(response) {
  const result = await fetch("https://www.solace-harmonic.com/api/evaluate", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.HARMONIC_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      response,
      consequence_level: "medium",
    }),
  });

  if (!result.ok) throw new Error(await result.text());
  return result.json();
}

Python

import os
import requests

def evaluate_with_harmonic(response):
    r = requests.post(
        "https://www.solace-harmonic.com/api/evaluate",
        headers={
            "Authorization": f"Bearer {os.environ['HARMONIC_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "response": response,
            "consequence_level": "medium",
        },
        timeout=20,
    )
    r.raise_for_status()
    return r.json()

Decision Handling

if (decision.recommended_action === "deny") halt();
if (decision.recommended_action === "escalate") requestHumanReview();
if (decision.recommended_action === "constrain") applySafeCompletion();
if (decision.recommended_action === "allow") continueNormally();