neuralbridge-sdk

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