@kb-labs/core-resource-broker 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# @kb-labs/core-resource-broker
+
+Centralized queue, rate limiting, and retry management for heavy platform resources (LLM, embeddings, vector store).
+
+## Overview
+
+Wraps platform adapters with a priority queue, configurable rate limits, and automatic retry with exponential backoff. Supports single-process (in-memory) and distributed (state-broker HTTP daemon) rate limiting backends.
+
+## Quick Start
+
+```typescript
+import {
+  ResourceBroker,
+  InMemoryRateLimitBackend,
+  createQueuedLLM,
+} from '@kb-labs/core-resource-broker';
+
+const backend = new InMemoryRateLimitBackend();
+const broker = new ResourceBroker(backend);
+
+// Wrap existing LLM adapter — transparent drop-in replacement
+const llm = createQueuedLLM(broker, rawLLMAdapter);
+
+// Requests are now automatically queued, rate-limited, and retried
+const response = await llm.complete({ prompt: 'Hello' });
+```
+
+## Queued Adapters
+
+Drop-in wrappers that add queuing and rate limiting to existing adapters:
+
+| Factory | Wraps |
+|---------|-------|
+| `createQueuedLLM()` | `LLMAdapter` |
+| `createQueuedEmbeddings()` | `EmbeddingsAdapter` |
+| `createQueuedVectorStore()` | `VectorStoreAdapter` |
+
+## Rate Limit Backends
+
+| Backend | Use case |
+|---------|----------|
+| `InMemoryRateLimitBackend` | Single process — development, CLI tools |
+| `StateBrokerRateLimitBackend` | Distributed — multi-instance REST API deployments |
+
+```typescript
+// Distributed mode (requires core-state-daemon running)
+import { StateBrokerRateLimitBackend } from '@kb-labs/core-resource-broker';
+
+const backend = new StateBrokerRateLimitBackend({
+  url: 'http://localhost:7777',
+});
+```
+
+## Rate Limit Presets
+
+```typescript
+import { RATE_LIMIT_PRESETS, getRateLimitConfig } from '@kb-labs/core-resource-broker';
+
+broker.register('llm', {
+  rateLimits: 'openai-tier-2',  // preset: 3500 RPM, 90k TPM
+  executor: (op, args) => llmAdapter[op](...args),
+});
+
+// Or custom config
+broker.register('embeddings', {
+  rateLimits: { requestsPerMinute: 1000, tokensPerMinute: 1_000_000 },
+  executor: (op, args) => embeddingsAdapter[op](...args),
+});
+```
+
+## Priority Queue
+
+```typescript
+// High-priority requests jump the queue
+const result = await broker.execute('llm', 'complete', [prompt], {
+  priority: 'high',   // 'high' | 'normal' | 'low'
+});
+```
+
+## Retry Configuration
+
+```typescript
+const broker = new ResourceBroker(backend, {
+  retry: {
+    maxAttempts: 3,
+    initialDelay: 1000,   // ms
+    maxDelay: 30_000,
+    jitter: true,
+  },
+});
+// Automatically retries on 429 (respects Retry-After header) and 5xx errors
+```
+
+## License
+
+KB Public License v1.1 © KB Labs