forma-sdk — FormaAI for Node.js / TypeScript

The oversight layer for AI agents — Capture · Approve · Kill · Prove · Redact

One line of code. Every LLM call captured, high-stakes actions paused for human approval, kill switch armed, every action HMAC-signed.

Install

npm install forma-sdk

Quickstart

import * as forma from "forma-sdk";

forma.init({
  apiKey:    process.env.FORMA_API_KEY,   // tl_live_...
  agentName: "loan-agent",
  humanSponsor: "[email protected]",
  killSwitch: true,

  // Gate high-value transactions for human approval:
  requireApprovalForTools: ["wire_transfer", "delete_*"],
  requireApprovalWhen: (ctx) => (ctx.toolArgs?.amount ?? 0) > 100_000,

  maxCostUsd: 5.0,
});

// Auto-patches OpenAI — every call captured + HMAC-signed:
const openai = forma.wrapOpenAI(new OpenAI());
await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarise Q3 revenue" }],
});

// Auto-patches Anthropic too:
const anthropic = forma.wrapAnthropic(new Anthropic());

// Verify connection:
const v = await forma.verify();
// { verified: true, capture: "active", killSwitch: "armed", approvals: "configured" }

Compliance mode (one parameter)

forma.init({
  apiKey: process.env.FORMA_API_KEY,
  complianceMode: "eu_ai_act_high_risk",
  // Automatically sets: requireApproval=true, killSwitch=true, approvalTimeout=1800s
});

Available profiles: eu_ai_act_high_risk · eu_ai_act_limited · nist_ai_rmf · hipaa · rbi_ml_guidelines · sox_fintech

Govern custom (non-LLM) tools

const transfer = forma.tool("wire_transfer", async (amount: number, to: string) => {
  return bank.transfer(amount, to);
}, { requireApproval: true, riskLevel: "CRITICAL" });

// Blocks until a human approves in the FormaAI inbox (fail-closed):
await transfer(250_000, "acct-77");

API

| Function | Description | |---|---| | forma.init(config) | Initialize — call once at startup | | forma.wrapOpenAI(client) | Patch OpenAI client — every call captured | | forma.wrapAnthropic(client) | Patch Anthropic client — every call captured | | forma.tool(name, fn, config?) | Govern a custom function (kill + approval + signed trace) | | forma.register(name, fn, config?) | Register a named agent | | forma.verify() | Check connectivity + feature status | | forma.status() | SDK version + state | | forma.kill(reason?) | Trigger kill switch programmatically |

Config

forma.init({
  apiKey:                    "tl_live_...",   // or FORMA_API_KEY env var
  agentName:                 "my-agent",
  humanSponsor:              "[email protected]",
  killSwitch:                true,
  requireApproval:           false,           // gate every call
  requireApprovalForTools:   ["wire_transfer", "delete_*"],
  requireApprovalForModels:  ["o1", "o3"],
  requireApprovalForKeywords:["terminate", "wire"],
  requireApprovalWhen:       (ctx) => ctx.toolArgs?.amount > 50_000,
  approvalMessage:           "Sign-off required",
  approvalTimeout:           3600,            // seconds (default 1h)
  maxCostUsd:                10.0,            // hard spend cap
  riskLevel:                 "HIGH",          // LOW | MEDIUM | HIGH | CRITICAL
  complianceMode:            "eu_ai_act_high_risk",
  redact:                    ["sk_live_...", "my-db-password"],
});

Links

• Dashboard: https://formaai.in
• Docs: https://formaai.in/developer-guide
• Python SDK: pip install forma-sdk (import trustlayer as tl)
• GitHub: https://github.com/amit5115/PROVN