@forg3t/sdk 0.1.3 → 0.1.4

package/README.md

@@ -1,63 +1,407 @@
-# @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
-```
-
-## Quick Start
-
-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: 'https://api.forg3t.io',
-  apiKey: 'f3_sk_...',
-});
-
-async function main() {
-  // Get Project Overview
-  const project = await client.getProjectOverview('your-project-id');
-  console.log('Project:', project);
-
-  // Submit an Unlearning Job
-  const job = await client.submitJob('your-project-id', {
-    type: 'unlearning',
-    parameters: {
-      modelId: 'llama-2-7b',
-      datasetId: 'copyrighted-books-subset'
-    }
-  });
-  console.log('Unlearning Job Submitted:', job.id);
-}
-
-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.
-
-## 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
+# @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, but the published npm package and official customer docs still need to catch up before this can be called fully self-serve.
+
+## 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 provisioned customer project.
+The production API hostname is:
+
+```bash
+export FORG3T_API_URL=https://api.forg3t.io
+export FORG3T_API_KEY=fg_...
+export FORG3T_PROJECT_ID=... # optional if default project exists
+```
+
+Then run a clean smoke script from your own workspace:
+
+```typescript
+import { Forg3tClient } from '@forg3t/sdk';
+
+const client = new Forg3tClient({
+  apiUrl: process.env.FORG3T_API_URL,
+  apiKey: process.env.FORG3T_API_KEY,
+  timeoutMs: 30000,
+});
+
+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 request = await client.createUnlearningRequest(projectId, {
+    target: { type: 'phrase', value: 'customer-onboarding-smoke' },
+    scope: {},
+    accessLevel: 'layer_a_only',
+    execution: {
+      target: {
+        provider: 'custom',
+        endpoint: 'https://example.com/inference'
+      }
+    }
+  });
+
+  console.log({
+    requestId: request.id,
+    jobId: request.job?.id,
+    jobType: request.job?.type,
+    jobStatus: request.job?.status
+  });
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+This validates:
+- API authentication
+- project resolution
+- unlearning request creation
+- job contract correctness
+- job lifecycle visibility
+
+### 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.
+
+### 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_API_KEY=fg_...
+export FORG3T_PROJECT_ID=...
+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