@sw4rm/js-sdk 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # SW4RM JavaScript SDK
 
-Reference JavaScript SDK for the SW4RM Agentic Protocol. This is one of three SDKs in this repository (Python, Rust, JavaScript). 🚧 Under development: initial implementation includes a basic RegistryClient and core utilities.
+Reference JavaScript SDK for the SW4RM Agentic Protocol. This is one of five SDKs in this repository (Python, Rust, JavaScript, Elixir, Common Lisp). 🚧 Under development: initial implementation includes a basic RegistryClient and core utilities.
 
 ## Install
 
@@ -66,6 +66,7 @@ await client.deregisterAgent('my-agent', 'Done');
 
 - ✅ Base gRPC client infrastructure
 - ✅ RegistryClient (agent registration, heartbeat, deregistration)
+- ✅ LLM clients (Groq, Anthropic, Mock) with adaptive rate limiting
 - ✅ TypeScript type definitions
 - ✅ Unit tests
 - ⏳ Additional service clients (planned)
@@ -145,15 +146,191 @@ await persist.load();
 persist.startAutosave();
 ```
 
+## LLM Client
+
+The SDK includes a provider-agnostic LLM client abstraction. Agents can query
+language models through a unified interface without coupling to a specific vendor.
+
+### Import
+
+```ts
+import {
+  createLlmClient,
+  GroqClient,
+  AnthropicClient,
+  MockLlmClient,
+} from '@sw4rm/js-sdk';
+```
+
+### Factory
+
+The `createLlmClient` factory selects a provider based on explicit options or
+environment variables. When nothing is specified it defaults to the mock client,
+so tests never hit a real API.
+
+```ts
+// Auto-detect from LLM_CLIENT_TYPE env var (default: "mock")
+const client = createLlmClient();
+
+// Explicit provider
+const groq = createLlmClient({ clientType: 'groq' });
+const claude = createLlmClient({
+  clientType: 'anthropic',
+  model: 'claude-sonnet-4-20250514',
+});
+
+// Override API key and timeout
+const custom = createLlmClient({
+  clientType: 'groq',
+  apiKey: 'gsk_...',
+  timeoutMs: 60_000,
+});
+```
+
+### Credential resolution
+
+Each provider resolves its API key in this order:
+
+1. `apiKey` constructor / factory parameter
+2. Environment variable (`GROQ_API_KEY` or `ANTHROPIC_API_KEY`)
+3. Dotfile in the home directory (`~/.groq` or `~/.anthropic`, plain text, one line)
+
+If none of these are set the constructor throws `LlmAuthenticationError`.
+
+### Basic query
+
+```ts
+import { createLlmClient } from '@sw4rm/js-sdk';
+
+const client = createLlmClient({ clientType: 'groq' });
+
+const response = await client.query(
+  'Analyze this task and suggest next steps.',
+  {
+    systemPrompt: 'You are a helpful task-analysis agent.',
+    maxTokens: 2048,
+    temperature: 0.7,
+  },
+);
+
+console.log(response.content);       // generated text
+console.log(response.model);         // e.g. "llama-3.3-70b-versatile"
+console.log(response.usage);         // { input_tokens, output_tokens }
+```
+
+### Streaming
+
+`streamQuery` returns an `AsyncGenerator<string>` that yields text chunks as
+they arrive over SSE.
+
+```ts
+const client = createLlmClient({ clientType: 'anthropic' });
+
+for await (const chunk of client.streamQuery('Write a status report.', {
+  systemPrompt: 'You are a concise technical writer.',
+})) {
+  process.stdout.write(chunk);
+}
+```
+
+### Mock client for testing
+
+`MockLlmClient` never makes network calls. It records every query so tests
+can assert on prompts, token counts, and call order.
+
+```ts
+import { MockLlmClient } from '@sw4rm/js-sdk';
+
+const mock = new MockLlmClient({
+  responses: ['First canned answer', 'Second canned answer'],
+});
+
+const r1 = await mock.query('Hello');
+console.log(r1.content);     // "First canned answer"
+console.log(mock.callCount); // 1
+
+// Custom generator
+const mock2 = new MockLlmClient({
+  responseGenerator: (prompt) => `Echo: ${prompt}`,
+});
+```
+
+### Rate limiting
+
+All LLM clients share a process-wide token-bucket rate limiter. It is enabled
+by default and adapts automatically:
+
+- On **HTTP 429** the budget is reduced by a configurable factor (default 0.7x).
+- After a cooldown period and enough consecutive successes the budget recovers.
+- Callers block in `acquire()` until tokens are available; a timeout prevents
+  indefinite waits.
+
+No application code is needed -- rate limiting is built into every `query` and
+`streamQuery` call.
+
+### Error hierarchy
+
+All LLM errors extend `LlmError`:
+
+| Class | Trigger |
+|---|---|
+| `LlmAuthenticationError` | Invalid / missing API key, billing errors |
+| `LlmRateLimitError` | HTTP 429 from the provider |
+| `LlmTimeoutError` | Request exceeded timeout |
+| `LlmContextLengthError` | Prompt exceeds model context window |
+
+```ts
+import { LlmRateLimitError } from '@sw4rm/js-sdk';
+
+try {
+  await client.query('...');
+} catch (err) {
+  if (err instanceof LlmRateLimitError) {
+    // The rate limiter already reduced its budget; retry after a delay
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `LLM_CLIENT_TYPE` | `mock` | Provider for the factory: `groq`, `anthropic`, or `mock` |
+| `LLM_DEFAULT_MODEL` | per-provider | Override the default model for any provider |
+| `GROQ_API_KEY` | -- | Groq API key |
+| `GROQ_DEFAULT_MODEL` | `llama-3.3-70b-versatile` | Default model for the Groq client |
+| `ANTHROPIC_API_KEY` | -- | Anthropic API key |
+| `ANTHROPIC_DEFAULT_MODEL` | `claude-sonnet-4-20250514` | Default model for the Anthropic client |
+| `LLM_RATE_LIMIT_ENABLED` | `1` | Set to `0` to disable the rate limiter |
+| `LLM_RATE_LIMIT_TOKENS_PER_MIN` | `250000` | Token budget per minute |
+| `LLM_RATE_LIMIT_ADAPTIVE` | `1` | Enable adaptive throttling on 429 |
+| `LLM_RATE_LIMIT_REDUCTION_FACTOR` | `0.7` | Budget multiplier after a 429 |
+| `LLM_RATE_LIMIT_RECOVERY_FACTOR` | `1.1` | Budget multiplier during recovery |
+| `LLM_RATE_LIMIT_COOLDOWN_SECONDS` | `30` | Seconds to wait before recovery begins |
+| `LLM_RATE_LIMIT_RECOVERY_SUCCESS_THRESHOLD` | `20` | Consecutive successes needed for recovery |
+
 ## Spec compliance
 
 - Envelope, ACK lifecycle, Scheduler (priority/Duration), Worktree, HITL, Negotiation, Reasoning, Connector, Logging clients implemented.
 - Streaming resilience and interceptor hooks included by default.
 - JSON persistence for ActivityBuffer and ACK states.
 
+## Operational Contracts
+
+For production deployments, see the **[Operational Contracts](../docs/OPERATIONAL_CONTRACTS.md)** documentation, which defines:
+
+- Connection timeouts and keep-alive settings
+- Retry policies and error handling
+- Data consistency guarantees
+- Idempotency contracts
+- State persistence guarantees
+
+These are protocol-level contracts that all SW4RM SDKs honor.
+
 ## Links
 
 - Top-level README (overview and API): `../../README.md`
 - Quickstart for running local services: `../../QUICKSTART.md`
+- Operational Contracts: `../docs/OPERATIONAL_CONTRACTS.md`
 - Python SDK: `../py_sdk/README.md`
 - Rust SDK: `../rust_sdk/README.md`