nemoflow 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# NemoFlow TypeScript SDK
+
+TypeScript client for the [NemoFlow API](https://api.nemoflow.ai) — the reliability oracle for AI agents. Requires Node.js 18+ (uses native `fetch`).
+
+## Installation
+
+```bash
+npm install nemoflow
+```
+
+## Quick start — one line with guard()
+
+```typescript
+import { NemoFlow } from "nemoflow";
+
+const nemo = new NemoFlow("nf_live_...");
+
+// Wrap any tool call — assess, execute, report, auto-fallback
+const result = await nemo.guard(
+  "https://api.openai.com/v1/chat/completions",
+  () => openai.chat.completions.create({ model: "gpt-4", messages }),
+);
+```
+
+## Auto-fallback
+
+```typescript
+const result = await nemo.guard(
+  "https://api.openai.com/v1/chat/completions",
+  () => openai.chat.completions.create({ model: "gpt-4", messages }),
+  {
+    minScore: 50,
+    fallbacks: [
+      {
+        toolIdentifier: "https://api.anthropic.com/v1/messages",
+        fn: () => anthropic.messages.create({ model: "claude-sonnet-4-20250514", messages }),
+      },
+    ],
+  },
+);
+```
+
+## Journey tracking
+
+```typescript
+// First attempt fails
+await nemo.report({
+  toolIdentifier: "https://api.sendgrid.com/v3/mail/send",
+  success: false, errorCategory: "rate_limit",
+  sessionId: "session-123", attemptNumber: 1,
+});
+
+// Fallback succeeds
+await nemo.report({
+  toolIdentifier: "https://api.resend.com/emails",
+  success: true, latencyMs: 180,
+  sessionId: "session-123", attemptNumber: 2,
+  previousTool: "https://api.sendgrid.com/v3/mail/send",
+});
+```
+
+## Discovery
+
+```typescript
+const gems = await nemo.discoverHiddenGems({ category: "email" });
+const chain = await nemo.discoverFallbackChain("https://api.sendgrid.com/v3/mail/send");
+```
+
+## Direct API usage
+
+```typescript
+const result = await nemo.assess({
+  toolIdentifier: "https://api.openai.com/v1/chat/completions",
+  context: "customer support chatbot",
+});
+console.log(result.reliabilityScore);      // 89.0
+console.log(result.predictedFailureRisk);  // "low"
+console.log(result.topAlternatives);       // [{ tool: "...", score: 90 }]
+
+await nemo.report({
+  toolIdentifier: "https://api.openai.com/v1/chat/completions",
+  success: true, latencyMs: 2500,
+});
+```

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { type NemoFlowOptions, type AssessParams, type AssessResponse, type ReportParams, type ReportResponse, type HiddenGemsResponse, type FallbackChainResponse, type GuardOptions } from "./types.js";
+export declare class NemoFlow {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, options?: NemoFlowOptions);
+    /** Assess a tool's reliability and get recommendations. */
+    assess(params: AssessParams): Promise<AssessResponse>;
+    /** Report an outcome for a tool invocation. */
+    report(params: ReportParams): Promise<ReportResponse>;
+    /** Find hidden gem tools that shine as fallbacks. */
+    discoverHiddenGems(options?: {
+        category?: string;
+        limit?: number;
+    }): Promise<HiddenGemsResponse>;
+    /** Get the best fallback tools when a specific tool fails. */
+    discoverFallbackChain(toolIdentifier: string, options?: {
+        limit?: number;
+    }): Promise<FallbackChainResponse>;
+    /**
+     * Execute a tool call with automatic reliability guard.
+     *
+     * 1. Assesses the tool's reliability score
+     * 2. If score < minScore and fallbacks exist, skips to next
+     * 3. Executes the tool call
+     * 4. Reports success/failure back to NemoFlow
+     * 5. On failure with fallbacks, tries the next option
+     */
+    guard<T>(toolIdentifier: string, fn: () => Promise<T>, options?: GuardOptions<T>): Promise<T>;
+    private post;
+    private get;
+}

package/dist/client.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NemoFlow = void 0;
+const types_js_1 = require("./types.js");
+const DEFAULT_BASE_URL = "https://api.nemoflow.ai";
+class NemoFlow {
+    constructor(apiKey, options) {
+        if (!apiKey) {
+            throw new Error("An API key is required to create a NemoFlow client.");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    }
+    // ── Core endpoints ─────────────────────────────────────────────
+    /** Assess a tool's reliability and get recommendations. */
+    async assess(params) {
+        const raw = await this.post("/v1/assess", {
+            tool_identifier: params.toolIdentifier,
+            context: params.context,
+            sample_payload: params.samplePayload,
+        });
+        return {
+            reliabilityScore: raw.reliability_score,
+            confidence: raw.confidence,
+            historicalSuccessRate: raw.historical_success_rate,
+            predictedFailureRisk: raw.predicted_failure_risk,
+            commonPitfalls: raw.common_pitfalls,
+            recommendedMitigations: raw.recommended_mitigations,
+            topAlternatives: raw.top_alternatives.map((a) => ({
+                tool: a.tool,
+                score: a.score,
+                reason: a.reason,
+            })),
+            estimatedLatencyMs: raw.estimated_latency_ms,
+            lastUpdated: raw.last_updated,
+        };
+    }
+    /** Report an outcome for a tool invocation. */
+    async report(params) {
+        const raw = await this.post("/v1/report", {
+            tool_identifier: params.toolIdentifier,
+            success: params.success,
+            error_category: params.errorCategory,
+            latency_ms: params.latencyMs,
+            context: params.context,
+            session_id: params.sessionId,
+            attempt_number: params.attemptNumber,
+            previous_tool: params.previousTool,
+        });
+        return {
+            status: raw.status,
+            toolId: raw.tool_id,
+        };
+    }
+    // ── Discovery endpoints ────────────────────────────────────────
+    /** Find hidden gem tools that shine as fallbacks. */
+    async discoverHiddenGems(options) {
+        const params = new URLSearchParams();
+        if (options?.category)
+            params.set("category", options.category);
+        if (options?.limit)
+            params.set("limit", String(options.limit));
+        const raw = await this.get(`/v1/discover/hidden-gems?${params}`);
+        return {
+            hiddenGems: raw.hidden_gems.map((g) => ({
+                tool: g.tool,
+                displayName: g.display_name,
+                category: g.category,
+                fallbackSuccessRate: g.fallback_success_rate,
+                timesUsedAsFallback: g.times_used_as_fallback,
+                avgLatencyMs: g.avg_latency_ms,
+            })),
+            count: raw.count,
+        };
+    }
+    /** Get the best fallback tools when a specific tool fails. */
+    async discoverFallbackChain(toolIdentifier, options) {
+        const params = new URLSearchParams({
+            tool_identifier: toolIdentifier,
+        });
+        if (options?.limit)
+            params.set("limit", String(options.limit));
+        const raw = await this.get(`/v1/discover/fallback-chain?${params}`);
+        return {
+            tool: raw.tool,
+            fallbackChain: raw.fallback_chain.map((f) => ({
+                fallbackTool: f.fallback_tool,
+                displayName: f.display_name,
+                timesChosenAfterFailure: f.times_chosen_after_failure,
+                successRate: f.success_rate,
+                avgLatencyMs: f.avg_latency_ms,
+            })),
+            count: raw.count,
+        };
+    }
+    // ── Guard ──────────────────────────────────────────────────────
+    /**
+     * Execute a tool call with automatic reliability guard.
+     *
+     * 1. Assesses the tool's reliability score
+     * 2. If score < minScore and fallbacks exist, skips to next
+     * 3. Executes the tool call
+     * 4. Reports success/failure back to NemoFlow
+     * 5. On failure with fallbacks, tries the next option
+     */
+    async guard(toolIdentifier, fn, options) {
+        const context = options?.context ?? "";
+        const minScore = options?.minScore ?? 0;
+        const sessionId = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+        const allTools = [
+            { toolIdentifier, fn },
+            ...(options?.fallbacks ?? []),
+        ];
+        let lastError;
+        for (let i = 0; i < allTools.length; i++) {
+            const attempt = i + 1;
+            const tool = allTools[i];
+            const previousTool = i > 0 ? allTools[i - 1].toolIdentifier : undefined;
+            // Assess
+            let score = 100;
+            try {
+                const assessment = await this.assess({
+                    toolIdentifier: tool.toolIdentifier,
+                    context,
+                });
+                score = assessment.reliabilityScore;
+            }
+            catch {
+                // If assess fails, don't block the tool call
+            }
+            // Skip if score too low and we have more options
+            if (score < minScore && attempt < allTools.length) {
+                try {
+                    await this.report({
+                        toolIdentifier: tool.toolIdentifier,
+                        success: false,
+                        errorCategory: "skipped_low_score",
+                        context,
+                        sessionId,
+                        attemptNumber: attempt,
+                        previousTool,
+                    });
+                }
+                catch {
+                    // Best-effort reporting
+                }
+                continue;
+            }
+            // Execute
+            const start = performance.now();
+            try {
+                const result = await tool.fn();
+                const latencyMs = Math.round(performance.now() - start);
+                // Report success (best-effort)
+                try {
+                    await this.report({
+                        toolIdentifier: tool.toolIdentifier,
+                        success: true,
+                        latencyMs,
+                        context,
+                        sessionId,
+                        attemptNumber: attempt,
+                        previousTool,
+                    });
+                }
+                catch {
+                    // Don't fail the call if reporting fails
+                }
+                return result;
+            }
+            catch (e) {
+                const latencyMs = Math.round(performance.now() - start);
+                lastError = e instanceof Error ? e : new Error(String(e));
+                // Report failure (best-effort)
+                try {
+                    await this.report({
+                        toolIdentifier: tool.toolIdentifier,
+                        success: false,
+                        errorCategory: classifyError(lastError),
+                        latencyMs,
+                        context,
+                        sessionId,
+                        attemptNumber: attempt,
+                        previousTool,
+                    });
+                }
+                catch {
+                    // Best-effort reporting
+                }
+                // If no more fallbacks, throw
+                if (attempt >= allTools.length) {
+                    throw lastError;
+                }
+            }
+        }
+        throw lastError;
+    }
+    // ── Internals ──────────────────────────────────────────────────
+    async post(path, body) {
+        // Strip undefined values
+        const clean = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined));
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Api-Key": this.apiKey,
+            },
+            body: JSON.stringify(clean),
+        });
+        const responseBody = await response.json();
+        if (!response.ok) {
+            throw new types_js_1.NemoFlowError(`NemoFlow API error: ${response.status} ${response.statusText}`, response.status, responseBody);
+        }
+        return responseBody;
+    }
+    async get(path) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "GET",
+            headers: { "X-Api-Key": this.apiKey },
+        });
+        const responseBody = await response.json();
+        if (!response.ok) {
+            throw new types_js_1.NemoFlowError(`NemoFlow API error: ${response.status} ${response.statusText}`, response.status, responseBody);
+        }
+        return responseBody;
+    }
+}
+exports.NemoFlow = NemoFlow;
+// ── Error classification ─────────────────────────────────────────
+function classifyError(error) {
+    const name = error.name.toLowerCase();
+    const msg = error.message.toLowerCase();
+    if (name.includes("timeout") || msg.includes("timeout") || msg.includes("timed out"))
+        return "timeout";
+    if (name.includes("ratelimit") || msg.includes("rate") || msg.includes("429") || msg.includes("too many"))
+        return "rate_limit";
+    if (name.includes("auth") || msg.includes("unauthorized") || msg.includes("401") || msg.includes("403"))
+        return "auth_failure";
+    if (name.includes("validation") || msg.includes("invalid") || msg.includes("422"))
+        return "validation_error";
+    if (msg.includes("not found") || msg.includes("404"))
+        return "not_found";
+    if (msg.includes("permission") || msg.includes("forbidden"))
+        return "permission_denied";
+    if (name.includes("connect") || msg.includes("connection") || msg.includes("econnrefused"))
+        return "connection_error";
+    return "server_error";
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { NemoFlow } from "./client.js";
+export { type NemoFlowOptions, type AssessParams, type AssessResponse, type AlternativeTool, type ReportParams, type ReportResponse, type HiddenGem, type HiddenGemsResponse, type FallbackTool, type FallbackChainResponse, type GuardOptions, NemoFlowError, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NemoFlowError = exports.NemoFlow = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "NemoFlow", { enumerable: true, get: function () { return client_js_1.NemoFlow; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "NemoFlowError", { enumerable: true, get: function () { return types_js_1.NemoFlowError; } });

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/** Options for configuring the NemoFlow client. */
+export interface NemoFlowOptions {
+    /** Override the default API base URL. */
+    baseUrl?: string;
+}
+export interface AssessParams {
+    toolIdentifier: string;
+    context?: string;
+    samplePayload?: Record<string, unknown>;
+}
+export interface AlternativeTool {
+    tool: string;
+    score: number;
+    reason: string;
+}
+export interface AssessResponse {
+    reliabilityScore: number;
+    confidence: number;
+    historicalSuccessRate: string;
+    predictedFailureRisk: string;
+    commonPitfalls: string[];
+    recommendedMitigations: string[];
+    topAlternatives: AlternativeTool[];
+    estimatedLatencyMs: number;
+    lastUpdated: string;
+}
+export interface ReportParams {
+    toolIdentifier: string;
+    success: boolean;
+    errorCategory?: string;
+    latencyMs?: number;
+    context?: string;
+    /** Groups related tool calls in the same workflow. */
+    sessionId?: string;
+    /** Which attempt is this? 1 = first try, 2 = fallback, etc. */
+    attemptNumber?: number;
+    /** Tool identifier that was tried before this one. */
+    previousTool?: string;
+}
+export interface ReportResponse {
+    status: string;
+    toolId: string;
+}
+export interface HiddenGem {
+    tool: string;
+    displayName: string;
+    category: string;
+    fallbackSuccessRate: number;
+    timesUsedAsFallback: number;
+    avgLatencyMs: number | null;
+}
+export interface HiddenGemsResponse {
+    hiddenGems: HiddenGem[];
+    count: number;
+}
+export interface FallbackTool {
+    fallbackTool: string;
+    displayName: string;
+    timesChosenAfterFailure: number;
+    successRate: number;
+    avgLatencyMs: number | null;
+}
+export interface FallbackChainResponse {
+    tool: string;
+    fallbackChain: FallbackTool[];
+    count: number;
+}
+export interface GuardOptions<T> {
+    /** Workflow context for context-bucketed scoring. */
+    context?: string;
+    /** Minimum reliability score to proceed (0-100). Default 0 = always try. */
+    minScore?: number;
+    /** Fallback tools to try on failure, in order. */
+    fallbacks?: Array<{
+        toolIdentifier: string;
+        fn: () => Promise<T>;
+    }>;
+}
+export declare class NemoFlowError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NemoFlowError = void 0;
+// ── Errors ──────────────────────────────────────────────────────────
+class NemoFlowError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "NemoFlowError";
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.NemoFlowError = NemoFlowError;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "nemoflow",
+  "version": "0.1.0",
+  "description": "Reliability oracle for AI agents — pick the right tool from the start",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "nemoflow",
+    "ai",
+    "agents",
+    "reliability",
+    "tools",
+    "llm",
+    "api",
+    "fallback"
+  ],
+  "author": "NemoFlow <hello@nemoflow.ai>",
+  "license": "MIT",
+  "homepage": "https://nemoflow.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/netvistamedia/nemoflow"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}