@denpex/sdk 0.8.0

package/README.md

@@ -0,0 +1,49 @@
+# @denpex/sdk
+
+TypeScript/JavaScript client for the [Denpex](https://denpex.com) API — diagnose GPU training
+failures from logs, report fix outcomes, and check your plan quota. Zero runtime dependencies,
+Node ≥ 18.
+
+## Install
+
+```bash
+npm install @denpex/sdk
+```
+
+## Quick start
+
+```ts
+import { DenpexClient } from "@denpex/sdk";
+
+const denpex = new DenpexClient({ apiKey: process.env.DENPEX_API_KEY! });
+
+// Diagnose a training log
+const result = await denpex.diagnose(logText, { jobName: "llama3-405b-pretrain" });
+console.log(result.meta?.failureType, result.meta?.confidence);
+console.log(result.fix?.summary);
+console.log(result.fix?.action);
+
+// Close the accuracy flywheel by reporting whether the fix worked
+await denpex.feedback(result.diagnosisId, "worked");
+
+// Check remaining headroom for the key's plan
+const quota = await denpex.quota();
+console.log(quota.quota);
+```
+
+Create an API key at <https://denpex.com/dashboard>. It is sent as the `X-Denpex-Key` header.
+
+## API
+
+| Method | Description |
+|---|---|
+| `new DenpexClient({ apiKey, baseUrl?, timeoutMs? })` | Construct a client. `baseUrl` defaults to `https://api.denpex.com`; the default 320-second timeout covers the server's 290-second deep path. |
+| `diagnose(logs, opts?)` | `POST /api/diagnose` — returns the diagnosis (failure type, confidence, root cause, fix, evidence). |
+| `feedback(diagnosisId, outcome, note?)` | `POST /api/diagnose/feedback` — `outcome` is `"worked"` or `"did_not_work"`. |
+| `quota()` | `GET /api/diagnose/quota` — remaining diagnoses for the key's plan. |
+
+Errors throw `DenpexError` with the HTTP status and server message.
+
+## License
+
+Proprietary. © Denpex. Use of this SDK is governed by your Denpex subscription agreement.

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+export interface DenpexClientOptions {
+    apiKey: string;
+    /** Defaults to the production control plane. */
+    baseUrl?: string;
+    /** Override fetch (tests, custom agents). Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms (AbortController). Default 320s — server deep-path ceiling is 290s. */
+    timeoutMs?: number;
+}
+export interface DiagnoseOptions {
+    jobName?: string;
+    runtimeHours?: number;
+    gpuRate?: number;
+    topologyMap?: Record<string, string[]>;
+    /** Profiler traces, job metadata, and other structured telemetry used for grounding. */
+    telemetry?: Record<string, unknown>;
+    /** Relevant source/config fragments used to test software-stack hypotheses. */
+    codeContext?: Record<string, unknown>;
+    /** Client-side signature matches (e.g. from denpex_lite) so Tier 0 starts from evidence. */
+    signatures?: unknown;
+}
+export interface DiagnoseMeta {
+    failureType?: string;
+    confidence?: number;
+    source?: string;
+    tier?: number;
+    /** Engine build stamp — compare across surfaces to detect a stale deploy. */
+    engineVersion?: string;
+}
+/**
+ * The known response fields. The engine attaches additional sections as it
+ * grows (forensics, advisories, execution plans) — they pass through untyped
+ * rather than being silently dropped, so SDK users always receive everything
+ * the API returned.
+ */
+/**
+ * Which rank failed FIRST, on which node, and the line that proves it.
+ *
+ * On a 512-rank job every rank reports a timeout and exactly one started it, so
+ * this is usually the field a caller actually wants. `node` is parsed directly
+ * off the matched line; `rank` is inferred from the nearest `[rank N]` within a
+ * few lines, so treat the node as the stronger signal of the two.
+ *
+ * `analyzedLines` < `totalLines` means the paste exceeded the window the engine
+ * reads — the verdict covers only what was analysed.
+ */
+export interface DiagnoseInitiator {
+    rank?: number | null;
+    node?: string | null;
+    line?: string | null;
+    lineNumber?: number | null;
+    totalLines?: number | null;
+    analyzedLines?: number | null;
+}
+export interface DiagnoseResponse {
+    fix?: {
+        summary?: string;
+        action?: string;
+        evidence?: unknown[];
+        [k: string]: unknown;
+    };
+    meta?: DiagnoseMeta;
+    initiator?: DiagnoseInitiator | null;
+    engineVersion?: string;
+    remaining?: number;
+    forensicReport?: unknown;
+    advisory?: unknown[];
+    researchRefs?: unknown[];
+    communityRefs?: unknown[];
+    executionPlan?: unknown;
+    [k: string]: unknown;
+}
+export interface QuotaResponse {
+    [k: string]: unknown;
+}
+export type FeedbackOutcome = 'worked' | 'did_not_work';
+export declare class DenpexError extends Error {
+    readonly status: number;
+    /** Machine-readable code when the API provides one (e.g. AUTH_REQUIRED, GPU_LIMIT_EXCEEDED). */
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, 
+    /** Machine-readable code when the API provides one (e.g. AUTH_REQUIRED, GPU_LIMIT_EXCEEDED). */
+    code?: string | undefined);
+}
+export declare class DenpexClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options: DenpexClientOptions);
+    /** Diagnose a training failure from raw logs (20 chars – 256 KB). */
+    diagnose(logs: string, opts?: DiagnoseOptions): Promise<DiagnoseResponse>;
+    /** Report whether a diagnosis worked — this feedback directly improves future priors. */
+    feedback(diagnosisId: string, outcome: FeedbackOutcome, note?: string): Promise<Record<string, unknown>>;
+    /** Remaining diagnosis headroom for this key's plan. */
+    quota(): Promise<QuotaResponse>;
+    private request;
+}
+export { DenpexClient as default };

package/dist/client.js

@@ -0,0 +1,98 @@
+"use strict";
+// @denpex/sdk — TypeScript client for the Denpex public API.
+//
+// Rewritten 2026-07-20: the previous file was a stub for /v1/{tenant}/incidents
+// routes that do not exist in the api-worker. This client targets the REAL
+// production surface (matching worker/api-worker-optimized.ts):
+//
+//   POST /api/diagnose            { logs, jobName?, ... } -> diagnosis
+//   POST /api/diagnose/feedback   { diagnosisId, outcome } -> closes the accuracy flywheel
+//   GET  /api/diagnose/quota      remaining headroom for the key's plan
+//
+// Auth: an API key from https://denpex.com/dashboard, sent as `X-Denpex-Key`
+// (`dpx_`/`dpk_`-prefixed keys may also be sent as a Bearer token).
+//
+// Zero dependencies. Requires global fetch (Node >= 18 or any browser/worker).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.DenpexClient = exports.DenpexError = void 0;
+class DenpexError extends Error {
+    constructor(message, status, 
+    /** Machine-readable code when the API provides one (e.g. AUTH_REQUIRED, GPU_LIMIT_EXCEEDED). */
+    code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'DenpexError';
+    }
+}
+exports.DenpexError = DenpexError;
+const MIN_LOG_CHARS = 20;
+const MAX_LOG_CHARS = 256000;
+class DenpexClient {
+    constructor(options) {
+        if (!options?.apiKey)
+            throw new Error('DenpexClient: apiKey is required (create one at https://denpex.com/dashboard)');
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? 'https://api.denpex.com').replace(/\/+$/, '');
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? 320000;
+        if (!this.fetchImpl)
+            throw new Error('DenpexClient: global fetch not found — Node >= 18 required, or pass fetchImpl');
+    }
+    /** Diagnose a training failure from raw logs (20 chars – 256 KB). */
+    async diagnose(logs, opts = {}) {
+        if (typeof logs !== 'string' || logs.length < MIN_LOG_CHARS) {
+            throw new DenpexError(`logs must be at least ${MIN_LOG_CHARS} characters`, 400);
+        }
+        if (logs.length > MAX_LOG_CHARS) {
+            throw new DenpexError(`logs too large (max ${MAX_LOG_CHARS} chars) — send the failing excerpt`, 400);
+        }
+        return this.request('POST', '/api/diagnose', { logs, ...opts });
+    }
+    /** Report whether a diagnosis worked — this feedback directly improves future priors. */
+    async feedback(diagnosisId, outcome, note) {
+        if (!diagnosisId)
+            throw new DenpexError('diagnosisId required', 400);
+        return this.request('POST', '/api/diagnose/feedback', { diagnosisId, outcome, ...(note ? { note } : {}) });
+    }
+    /** Remaining diagnosis headroom for this key's plan. */
+    async quota() {
+        return this.request('GET', '/api/diagnose/quota');
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    'X-Denpex-Key': this.apiKey,
+                    Accept: 'application/json',
+                    ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: controller.signal,
+            });
+            let json = {};
+            try {
+                json = (await res.json());
+            }
+            catch { /* non-JSON error body */ }
+            if (!res.ok) {
+                const message = typeof json.error === 'string' ? json.error : `Denpex API error (status ${res.status})`;
+                throw new DenpexError(message, res.status, typeof json.code === 'string' ? json.code : undefined);
+            }
+            return json;
+        }
+        catch (e) {
+            if (e.name === 'AbortError')
+                throw new DenpexError(`request timed out after ${this.timeoutMs}ms`, 408);
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.DenpexClient = DenpexClient;
+exports.default = DenpexClient;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@denpex/sdk",
+  "version": "0.8.0",
+  "description": "TypeScript client for the Denpex API — diagnose GPU training failures from logs (POST /api/diagnose), report fix outcomes, check quota. Zero dependencies, Node >= 18.",
+  "keywords": [
+    "denpex",
+    "gpu",
+    "ml-training",
+    "distributed-training",
+    "diagnosis",
+    "nccl",
+    "cuda",
+    "observability",
+    "sdk"
+  ],
+  "homepage": "https://denpex.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MisaMisaAI/Denpex.git",
+    "directory": "denpex-sdk-ts"
+  },
+  "bugs": {
+    "url": "https://denpex.com/contact"
+  },
+  "license": "Proprietary",
+  "main": "dist/client.js",
+  "types": "dist/client.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test tests/client.test.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.23.1"
+  }
+}