pulseroute

Real-time API intelligence layer for AI agents. PulseRoute tracks live p50/p95 latency, cost, and success rates across LLM providers and search/scraping APIs, then routes your agent to the best option at call time.

Install

npm install pulseroute

Quickstart

Pattern 1 — Basic recommendation

import { PulseRoute } from 'pulseroute';

const pr = new PulseRoute({ apiKey: 'YOUR_KEY' });

const rec = await pr.recommend({ task: 'web_search' });
console.log(rec.best_provider); // "Tavily"
console.log(rec.confidence);    // 0.94
console.log(rec.reasoning);     // "Tavily chosen: p50 289ms, $0.003/call, 99.1% success"

Pattern 2 — With constraints

const rec = await pr.recommend({
  task: 'web_search',
  constraints: {
    latency_ms: { max: 300 },
    cost_per_call: { max: 0.002 },
  },
  preferences: { prioritize_reliability: true },
});

console.log(rec.best_provider);       // fastest + cheapest that fits
console.log(rec.fallback_options);    // ranked alternatives if primary fails

Pattern 3 — The .use() pattern (recommended for agents)

The key innovation: recommend + auto-report back in one call. PulseRoute learns from every outcome automatically.

const { provider, done } = await pr.use({ task: 'web_search' });

// Use the recommended provider in your agent
const result = await mySearchFunction(provider, query);

// Report the outcome — PulseRoute learns from this
done({ success: true, latency_ms: 180, cost: 0.001 });

That's it. Two lines to get live-optimized routing and feed telemetry back into the system.

Task aliases

All common aliases are normalized automatically:

| You send | Normalized to | |---|---| | search, websearch, web | web_search | | llm, completion, chat | llm_completion | | scrape, crawl | scraping |

Offline resilience

PulseRoute never blocks your agent. If the API is unreachable, .recommend() returns your configured fallbackProvider with data_source: "offline". The .use() pattern's done() callback silently drops the report rather than throwing.

const pr = new PulseRoute({
  apiKey: 'YOUR_KEY',
  fallbackProvider: 'tavily',  // used if PulseRoute is unreachable
  timeoutMs: 2000,             // abort after 2s (default: 3s)
});

Caching

Recommendations for the same task + constraints are cached for 30 seconds to avoid redundant API calls in tight agent loops. Cached responses include from_cache: true.

API reference

new PulseRoute(config?)

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Your PulseRoute API key | | baseUrl | string | https://pulse-route-core.replit.app/api | Override for self-hosted | | fallbackProvider | string | "unknown" | Returned when API is unreachable | | timeoutMs | number | 3000 | Request timeout in milliseconds |

pr.recommend(opts)

Returns a Recommendation with best_provider, confidence, expected_latency_ms, expected_cost, success_rate, fallback_options, and reasoning.

pr.report(opts)

Fire-and-forget telemetry report. Never throws.

pr.use(opts)

Returns { provider, done }. Call done({ success, latency_ms, cost? }) after your API call completes.

License

MIT