@forg3t/sdk

Official TypeScript SDK for the Forg3t Protocol. This SDK allows you to interact with the Forg3t Control Plane to manage projects, submit jobs, verify evidence, and handle webhooks.

Forg3t.io is the platform where you can manage your AI Unlearning operations, track compliance, and visualize evidence. This SDK enables you to integrate these capabilities directly into your applications.

Installation

npm install @forg3t/sdk
# or
yarn add @forg3t/sdk
# or
pnpm add @forg3t/sdk

Production Reality

This package is live and installable. It is not yet a fully self-serve enterprise onboarding product by itself.

Today, the truthful usage pattern is:

1. Forg3t provisions or approves the tenant / project path.
2. The customer receives a real project API key.
3. The SDK connects to a real control-plane URL.
4. Execution then depends on the architecture:
   • API-only / retrieval-based systems use control-plane enforcement and evidence flows.
   • Whitebox model changes require a customer-side whitebox worker path.

There is now also a live bearer-token bootstrap path for first-time tenant creation:

• POST /v1/bootstrap/tenant
• public hostname: https://api.forg3t.io
• auth mode: dashboard bearer token, not project API key

This closes the biggest admin-led onboarding gap. The published npm package now includes the bootstrap flow and request-creation surface, but the overall product is still not fully self-serve enterprise onboarding because tenant lifecycle cleanup, whitebox activation, and some runtime specialization paths remain operator-led.

Execution Modes

Forg3t now has three materially different execution lanes. Keeping them separate is important:

1. Managed black-box lane

   • default baseline path for API-only and retrieval-style first runs
   • request enters via https://api.forg3t.io
   • control-plane managed worker claims the job
   • a private executor service runs the black-box workload
   • this is the path verified by the published SDK cleanroom smoke

2. Customer-scoped generic worker

   • used when a customer wants execution tied to their own project-scoped worker runtime
   • not the same thing as the default managed black-box lane

3. Customer-side whitebox worker

   • required when the customer wants staged model-weight intervention
   • this remains a separate install and acceptance path

Local Development

1. Build: npm run build
2. Typecheck: node ../../node_modules/typescript/bin/tsc -p tsconfig.json --noEmit
3. Examples: examples/whitebox-worker.ts demonstrates customer-infra model editing.
4. Staging smoke: npm run smoke:staging validates request -> job -> terminal status flow.

Customer Onboarding Smoke

Use this as the first real integration gate for a new signed-in customer session. The production API hostname is:

export FORG3T_API_URL=https://api.forg3t.io
export FORG3T_BEARER_TOKEN=eyJ...

Then run the official onboarding smoke:

npm run smoke:customer-onboarding

This validates:

• bearer-token bootstrap
• project resolution
• API key creation
• unlearning request creation
• request detail fetch
• terminal job success
• evidence readiness
• artifact download readiness
• API key revoke
• job contract correctness
• first-customer path through the public API hostname

Cleanroom Release Smoke

For release verification from a clean temporary install:

export [email protected]
export FORG3T_ONBOARDING_SMOKE_PASSWORD=...
export SUPABASE_ANON_KEY=...
npm run smoke:cleanroom

This installs the package into a fresh temporary directory, runs bootstrap, creates a first request, verifies terminal job success plus evidence/artifact readiness, and revokes the temporary API key. It is the release-candidate gate we use before claiming the SDK package is ready to publish.

First-Time Tenant Bootstrap

If you are integrating from a signed-in dashboard or application session, instantiate the SDK with a bearer token and bootstrap the tenant path first:

import { Forg3tClient } from '@forg3t/sdk';

const client = new Forg3tClient({
  apiUrl: 'https://api.forg3t.io',
  bearerToken: process.env.FORG3T_BEARER_TOKEN,
});

async function main() {
  const bootstrap = await client.bootstrapTenant({
    tenantName: 'Northstar Bank',
    projectName: 'Retail Banking Assistant',
    integrationType: 'custom',
    integrationName: 'Primary Banking Integration',
  });

  console.log({
    created: bootstrap.created,
    tenantId: bootstrap.tenant.id,
    projectId: bootstrap.bootstrap.project.id,
    apiKeyPrefix: bootstrap.bootstrap.apiKey.keyPrefix,
    plaintextKeyReturned: Boolean(bootstrap.bootstrap.apiKey.plaintextKey),
  });
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Notes:

• First bootstrap returns the plaintext API key once.
• Repeating bootstrap with the same bearer token is idempotent and reuses the tenant resources.
• This flow is live on the control plane today.

First-Time Bootstrap + First Request

If you want the full SDK example in one run:

export FORG3T_API_URL=https://api.forg3t.io
export FORG3T_BEARER_TOKEN=eyJ...
npm run example:bootstrap

This example:

1. bootstraps the tenant
2. creates a temporary project API key
3. submits the first request
4. fetches request detail
5. revokes the temporary API key

Repo Maintainer Smoke

If you are working inside the Forg3t SDK repo itself, you can also run the bundled smoke script:

export FORG3T_API_URL=https://api.forg3t.io
export FORG3T_BEARER_TOKEN=eyJ...
npm run smoke:customer-onboarding

Known Limitations

• Node Runtime: Whitebox worker and Python runner examples target Node.js + Python environments.
• Onchain Verification: Onchain anchoring is not required for whitebox execution flow and can be integrated later.

Initialize the client with your project's API key. You can generate API keys from your Forg3t Dashboard.

import { Forg3tClient } from '@forg3t/sdk';

const client = new Forg3tClient({
  apiUrl: process.env.FORG3T_API_URL,
  apiKey: process.env.FORG3T_API_KEY,
});

async function main() {
  const me = await client.getCurrentUser();
  const projectId = process.env.FORG3T_PROJECT_ID || me.defaultProjectId;

  if (!projectId) {
    throw new Error('Set FORG3T_PROJECT_ID or configure a default project first.');
  }

  const project = await client.getProjectOverview(projectId);
  console.log('Project:', project.name);
}

main().catch(console.error);

Features

• AI Unlearning Operations: Submit and track unlearning jobs programmatically.
• Verification Evidence: Retrieve cryptographic proofs and PDF reports for audit trails.
• Project Management: View project details and stats.
• API Key Management: Create, rotate, and revoke API keys programmatically.
• Webhooks: Manage and replay webhook deliveries for real-time integration.

Evidence Retrieval

const evidence = await client.getEvidence(jobId);
// If API returns readiness shape:
if ('evidenceReady' in evidence && !evidence.evidenceReady) {
  // retry later
}

const evidenceJson = await client.getEvidenceJson(jobId);
const evidencePdf = await client.getEvidencePdf(jobId, { saveToPath: './evidence.pdf' });

Whitebox Worker (Customer Infra)

For real model-weight modifications, run a customer-side worker that claims MODEL_UNLEARN jobs and executes your training backend adapter in your own infrastructure.

1) Submit a MODEL_UNLEARN job

import { Forg3tClient, buildModelUnlearningPayload } from '@forg3t/sdk';

const client = new Forg3tClient({ apiUrl: process.env.FORG3T_API_URL, apiKey: process.env.FORG3T_API_KEY });

const { claim, config } = buildModelUnlearningPayload({
  claim: {
    claim_type: 'DOCUMENT',
    claim_payload: 'customer-record-123',
    scope: 'project',
    assertion: 'must_not_be_recalled'
  },
  model: {
    uri: '/models/llama-7b.safetensors',
    format: 'safetensors'
  },
  target: {
    text: 'customer-record-123'
  },
  plan: {
    method: 'gradient_surgery',
    hyperparameters: { lr: 0.0005, max_steps: 400 }
  }
});

await client.createJob('your-project-id', 'MODEL_UNLEARN', claim, config);

For targeted whitebox localization, provide either:

• config.parameters.target.tokenIds (preferred), or
• tokenizer URI in config.target_config.tokenizer.uri / config.parameters.tokenizer.uri.

SDK preflight now enforces this for MODEL_UNLEARN submission. To bypass temporarily (not recommended), set:

export FORG3T_ALLOW_MODEL_UNLEARN_WITHOUT_LOCALIZATION_INPUT=true

If you use createUnlearningRequest(...) with accessLevel: 'layer_a_and_b', include execution.model.uri so Control Plane can generate an executable MODEL_UNLEARN job:

await client.createUnlearningRequest('your-project-id', {
  target: { type: 'document_id', value: 'customer-record-123' },
  scope: { integrationIds: [] },
  accessLevel: 'layer_a_and_b',
  execution: {
    model: { uri: '/models/llama-7b.safetensors', format: 'safetensors' },
    plan: { method: 'suppression', hyperparameters: { suppression_factor: 0.85, max_edits: 2048 } }
  }
});

For accessLevel: 'layer_a_only', provide explicit Layer A target config (execution.target). This now creates a first-class BLACKBOX_SUPPRESS job instead of overloading the retrieval contract:

await client.createUnlearningRequest('your-project-id', {
  target: { type: 'concept', value: 'customer-record-123' },
  scope: { integrationIds: [] },
  accessLevel: 'layer_a_only',
  execution: {
    target: {
      provider: 'openai',
      model: 'gpt-4o-mini'
    }
  }
});

2) Run worker + adapter in your infra

Use the example worker at:

• examples/whitebox-worker.ts
• examples/python/weight_surgery_runner.py

Ops installers:

• packages/worker/scripts/install-whitebox-gcp.sh (one-command GCP rollout)
• packages/worker/scripts/install-whitebox-airgapped.sh (one-command offline bundle/install)

The worker now supports native adapter modes:

• local_command: run local Python/CLI training jobs inside customer infra.
• http: call your internal training gateway (Kubernetes/SageMaker/Slurm bridge).

Install Python deps for the example:

pip install -r examples/python/requirements.txt

Example environment for local command mode:

export FORG3T_ADAPTER_MODE=local_command
export FORG3T_PYTHON_BIN=python3
export FORG3T_DEPLOYMENT_PROFILE=customer_online

Example environment for HTTP mode:

export FORG3T_ADAPTER_MODE=http
export FORG3T_UNLEARNING_URL=https://ml-internal.example.com/unlearn
export FORG3T_EVALUATION_URL=https://ml-internal.example.com/evaluate
export FORG3T_ADAPTER_BEARER_TOKEN=...
export FORG3T_DEPLOYMENT_PROFILE=cloud_managed

Example environment for air-gapped customer deployments:

export FORG3T_ADAPTER_MODE=local_command
export FORG3T_DEPLOYMENT_PROFILE=customer_airgapped
# optional: allow private DNS hostnames used by local control-plane
export FORG3T_AIRGAPPED_ALLOWED_HOSTS=cp.internal,forg3t-cp.lan

3) Enforce unlearning quality gates

WhiteboxWorker supports policy-based quality gates before completing a job:

• Presets:
  • strict: evaluator required, localization required, PASS only.
  • balanced: evaluator optional, localization optional, PASS/REVIEW allowed.

import { resolveWhiteboxQualityGatePolicy } from '@forg3t/sdk';

const strictPolicy = resolveWhiteboxQualityGatePolicy('strict');
const balancedPolicy = resolveWhiteboxQualityGatePolicy('balanced');

import { WhiteboxWorker } from '@forg3t/sdk';

const worker = new WhiteboxWorker(client, adapter, {
  projectId: process.env.FORG3T_PROJECT_ID!,
  qualityGatePolicy: {
    requireEvaluation: true,
    maxLeakScore: 0.03,
    allowedVerdicts: ['PASS'],
    minChangedTensorCount: 1,
    minChangedParamCount: 1,
    requireModelHashTransition: true,
    requireLocalization: true,
    minLocalizationTokenCoverage: 0.5,
    minLocalizedParamCount: 1,
    minLocalizationConfidence: 0.6
  },
  qualityGateOnFailure: 'fail_job'
});

Per-job override support:

• Include quality_gate_preset in plan.hyperparameters (strict or balanced) when creating MODEL_UNLEARN requests/jobs.
• Optional quality_gate_policy object can further override preset thresholds.

4) Operational hardening (lease-token protected lifecycle)

Worker SDK now propagates claimId lease tokens on heartbeat/complete/fail, and control-plane can enforce strict token checks:

export REQUIRE_JOB_CLAIM_TOKEN=1

With this enabled, stale or foreign workers cannot ack jobs they did not claim.

5) Privacy defaults (no raw claim payload in result telemetry)

WhiteboxWorker now defaults to resultClaimMode: 'hash' so raw claim_payload is not written back to control-plane results:

const worker = new WhiteboxWorker(client, adapter, {
  projectId: process.env.FORG3T_PROJECT_ID!,
  resultClaimMode: 'hash' // default: stores sha256 + payload length
});

Modes:

• hash (default): sends claim_payload_sha256 + length.
• omit: omits payload and hash, keeps only claim metadata.
• raw: sends full claim payload (only use if explicitly required).

Documentation

For comprehensive guides and API references, visit docs.forg3t.io. To start unlearning your AI models, visit Forg3t.io.

License

MIT