NeuralBridge SDK — TypeScript

Agent stability SDK for TypeScript/Node.js. Self-healing, auto-failover, circuit-breaker for LLM API calls across multiple providers.

🧠 One SDK to route, heal, and optimize across OpenAI, Anthropic, DeepSeek, Google, DashScope (Alibaba), Groq, NVIDIA, and Agnes.

Features

• 🛡️ Self-Healing — Automatic retry → degrade → failover when providers fail
• 🔀 Multi-Provider Routing — Route to the best provider based on health, latency, or cost
• ⚡ Circuit Breaker — Stop calling failing providers, auto-recover when they're healthy
• 🚦 Rate Limiting — Token-bucket per provider to prevent 429 errors
• 🧱 Bulkhead — Limit concurrency per provider to prevent resource exhaustion
• 🔍 Diagnoser — Classify errors (rate limit, auth, timeout, server error, etc.)
• 🧠 Flywheel Learner — Learn from past failures to avoid repeating them
• 📦 Checkpoints — Agent workflow state persistence for crash recovery
• 🔌 Streaming — Real-time SSE streaming support
• 🩺 nb-doctor CLI — Diagnose errors and check provider status

Installation

npm install neuralbridge-sdk

Requires Node.js 18+.

Quick Start

Top-level convenience (auto-detect providers from env):

import { Chat } from 'neuralbridge-sdk';

// Auto-detects OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. from environment
const response = await Chat('What is the meaning of life?');
console.log(response);

Client API (full control):

import { NeuralBridge } from 'neuralbridge-sdk';

const nb = new NeuralBridge({
  providers: ['openai', 'anthropic', 'deepseek'],
  strategy: 'cost', // 'cost' | 'latency' | 'quality'
});

const res = await nb.chat('Write a haiku about AI');
console.log(res.text);
// → "Silicon dreams wake..."

// Check costs
console.log(nb.status().costs);

Multi-turn conversations:

import { NeuralBridge } from 'neuralbridge-sdk';

const nb = new NeuralBridge({ providers: ['openai'] });

const res1 = await nb.chat('Hello! My name is Alice.');
console.log(res1.text);

const res2 = await nb.chatWithMessages([
  { role: 'user', content: 'Hello! My name is Alice.' },
  { role: 'assistant', content: res1.text },
  { role: 'user', content: 'What is my name?' },
]);
console.log(res2.text); // → "Your name is Alice."

Specific provider:

const res = await nb.chatFromProvider('anthropic', 'Explain quantum computing');

Low-level engine:

import { createEngine } from 'neuralbridge-sdk';

const engine = createEngine({
  providers: ['openai'],
  apiKeys: { openai: process.env.OPENAI_API_KEY },
});

const result = await engine.callSync('Hello!');
console.log(result.content, result.provider, result.latencyMs, result.healLevel);

Streaming:

import { streamCall, Provider, PROVIDER_PRESETS } from 'neuralbridge-sdk';

const provider = new Provider({
  ...PROVIDER_PRESETS.openai,
  apiKey: process.env.OPENAI_API_KEY,
  priority: 1,
  enabled: true,
});

for await (const chunk of streamCall(provider, [
  { role: 'user', content: 'Count from 1 to 5' }
], { model: 'gpt-4o' })) {
  process.stdout.write(chunk.content);
  if (chunk.done) break;
}

Checkpoints (agent workflow persistence):

import { AgentSession } from 'neuralbridge-sdk';

const session = new AgentSession('my-workflow', './.checkpoints');

// Save progress
session.checkpoint(1, { prompt: 'Step 1 done' });

// Later, restore
const restored = session.restore();
if (restored) {
  console.log(`Resuming from step ${restored.stepIndex}`);
}

Error diagnosis:

import { Diagnoser, FaultCategory } from 'neuralbridge-sdk';

const diagnoser = new Diagnoser();
const diagnosis = diagnoser.diagnose('401 Invalid API Key');
console.log(diagnosis.category);        // FaultCategory.AUTH_ERROR
console.log(diagnosis.shouldRetry);     // false
console.log(diagnosis.skipToFailover);  // true

CLI

# Check provider API keys
npx nb-doctor auth

# Show engine status
npx nb-doctor status

# Diagnose an error
npx nb-doctor diagnose "429 Too Many Requests"

Architecture

The NeuralBridge SDK implements the MAPE-K adaptive loop (Monitor → Analyze → Plan → Execute → Knowledge):

┌─────────────────────────────────────────────────────┐
│                   MAPE-K Loop                        │
│                                                      │
│  Monitor ──→ Analyze ──→ Plan ──→ Execute ──→ Know  │
│    ↓            ↓           ↓          ↓         ↓   │
│  Collect     Diagnose    Choose      Make      Learn │
│  metrics     fault      provider    API call   from  │
│  /health     category   + model     + retry/   out-  │
│  signals                          failover   come    │
└─────────────────────────────────────────────────────┘

Three-layer boundary enforcement:

| Layer | Component | Responsibility | |-------|-----------|---------------| | L1 | Diagnoser | Identify fault, output label — NO action | | HA | CB / RL / BH | Read labels + metrics, modify availability — NO diagnosis | | L4 | Flywheel | Receive data, persist, output strategy — NEVER directly route |

API Reference

| Export | Description | |--------|-------------| | NeuralBridge | High-level client with routing + cost tracking | | SelfHealingEngine | Core MAPE-K orchestrator | | createEngine() | Factory function for SelfHealingEngine | | Chat() | Top-level one-liner (auto-detect providers) | | ChatAsync() | Promise-based Chat variant | | ChatWithTimeout() | Chat with timeout | | Provider | Per-provider HTTP client with CB/RL/BH | | CircuitBreaker | Per-provider circuit breaker | | RateLimiter | Token bucket rate limiter | | Bulkhead | Concurrency limiter | | Diagnoser | Error classification | | FlywheelLearner | Auto-learning from failures | | AgentSession | Checkpointed agent workflow | | CostTracker | Track API costs | | streamCall() | Async generator for streaming | | MapeKTrace | Per-call MAPE-K phase trace |

Supported Providers

| Provider | Env Variable | Default Models | |----------|-------------|----------------| | OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo, o1, o1-mini, o3-mini | | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-20250514, claude-haiku-4-20250514, claude-3-5-sonnet-20241022 | | DeepSeek | DEEPSEEK_API_KEY | deepseek-chat, deepseek-reasoner | | Google | GOOGLE_API_KEY | gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash | | DashScope | DASHSCOPE_API_KEY | qwen-max, qwen-plus, qwen-turbo, qwen-long | | Groq | GROQ_API_KEY | mixtral-8x7b-32768, llama-3.3-70b-versatile, gemma2-9b-it | | NVIDIA | NVIDIA_API_KEY | meta/llama-3.1-405b-instruct, mistralai/mistral-7b-instruct | | Agnes | AGNES_API_KEY | agnes-v1, agnes-v1-mini |

Open Core & Licensing

NeuralBridge follows an Open Core model:

| Tier | Price | Features | |------|-------|----------| | Free 🆓 | Apache 2.0 | Core engine, 2 providers, L1 retry, circuit breaker, rate limiter, bulkhead, basic flywheel, diagnoser | | Trial 🔑 | 7-day free | All Pro features unlocked for evaluation | | Pro 🔒 | $99/year | Unlimited providers, L3 heal, Flywheel persistence, Checkpoint, Telemetry export | | Professional 💼 | $499/month | Everything in Pro + Custom diagnoser, Team dashboard, Priority support | | Enterprise 🏢 | $1,499/month | Everything in Professional + Audit log, On-prem deploy, SLA 99.9% |

Activate Pro:

# Via env var (auto-detected on import)
export NEURALBRIDGE_LICENSE_KEY=NB-PRO-XXXX-XXXX

# Via CLI
npx nb-doctor pro activate NB-PRO-XXXX-XXXX

# Check status
npx nb-doctor pro status

// Programmatic activation
import { license } from 'neuralbridge-sdk';
await license.activate('NB-PRO-XXXX-XXXX');

// Check features
if (license.isPro) {
  // Pro features available
}
console.log(license.getPlan()); // { plan: 'pro', key: 'NB-PRO-...', activated: true }

The core SDK (this package) remains Apache 2.0 — free to use, modify, and distribute. Pro features like unlimited providers, advanced flywheel persistence, and L3 healing require a license key.

Links

• GitHub
• Pricing
• Python SDK
• Go SDK
• Documentation
• npm
• Issues