npm package: @forg3t/sdk
Description: Official TypeScript SDK for Forg3t Protocol
Author: Forg3t Inc.
Latest version: 0.1.6

# @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](https://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

```bash
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:

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

Then run the official onboarding smoke:

```bash
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:

```bash
export FORG3T_ONBOARDING_SMOKE_EMAIL=onboarding-smoke@forg3t.io
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:

```typescript
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:

```bash
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:

```bash
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](https://forg3t.io/dashboard).

```typescript
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

```typescript
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

```typescript
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:

```bash
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:

```typescript
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:

```typescript
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:

```bash
pip install -r examples/python/requirements.txt
```

Example environment for local command mode:

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

Example environment for HTTP mode:

```bash
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:

```bash
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.

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

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

```typescript
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:

```bash
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:

```typescript
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](https://docs.forg3t.io).
To start unlearning your AI models, visit **[Forg3t.io](https://forg3t.io)**.

## License

MIT