@diabolicallabs/llm-client 0.1.1 → 0.3.0

package/README.md

@@ -1,12 +1,12 @@
 # @diabolicallabs/llm-client
 
-Unified LLM API across Anthropic, OpenAI, Google Gemini, and DeepSeek. Single interface for completion, streaming, and structured output. All provider errors are normalized into a consistent `LlmError` shape. © Diabolical Labs
+Unified LLM API across Anthropic, OpenAI, Google Gemini, DeepSeek, and Perplexity. Single interface for completion, streaming, and structured output. All provider errors are normalized into a consistent `LlmError` shape. © Diabolical Labs
 
 **Pre-1.0. APIs may change between minor versions.**
 
 ## Status
 
-**Published — v0.1.0.** All four providers are implemented. A fifth provider (Perplexity) is a stub and will be implemented in a future release.
+**Published — v0.2.0.** All five providers are implemented. v0.3.0 adds per-call timeouts, caller AbortSignal, and stream stall detection.
 
 ## Install
 
@@ -55,9 +55,79 @@ const result = await client.structured(messages, schema);
 |---|---|---|
 | `anthropic` | Implemented | `ANTHROPIC_API_KEY` |
 | `openai` | Implemented | `OPENAI_API_KEY` |
-| `google` | Implemented | `GOOGLE_AI_API_KEY` |
+| `gemini` | Implemented | `GOOGLE_AI_API_KEY` |
 | `deepseek` | Implemented | `DEEPSEEK_API_KEY` |
-| `perplexity` | Stub — throws `LlmError` | — |
+| `perplexity` | Implemented | `PERPLEXITY_API_KEY` |
+
+## Perplexity — web-grounded responses
+
+The Perplexity provider returns real-time web-grounded answers with source citations. Use it via `createClient` or `createClientFromEnv`:
+
+```typescript
+const client = createClientFromEnv('perplexity', 'sonar');
+const response = await client.complete([
+  { role: 'user', content: 'What happened in AI this week?' },
+]);
+
+// Citations are deduplicated by URL
+console.log(response.citations);
+// [{ url: 'https://example.com/article' }, { url: 'https://reuters.com/story' }]
+```
+
+### Citations
+
+`LlmResponse.citations` is populated when Perplexity returns source URLs. It is `undefined` for all other providers.
+
+```typescript
+interface LlmResponse {
+  content: string;
+  model: string;
+  usage: LlmUsage;
+  latencyMs: number;
+  citations?: Array<{
+    url: string;
+    title?: string;  // Perplexity currently returns URLs only; title is always undefined
+  }>;
+}
+```
+
+Citations are deduplicated by URL within a single response. They are **not available in stream mode** — use `complete()` when you need citations.
+
+### Search filters via `providerOptions`
+
+Perplexity supports search-specific parameters. Pass them via the `providerOptions` escape hatch on any call:
+
+```typescript
+await client.complete(messages, {
+  providerOptions: {
+    search_recency_filter: 'week',   // 'month' | 'week' | 'day' | 'hour'
+    search_domain_filter: ['nytimes.com', 'reuters.com'],  // allowlist
+  },
+});
+```
+
+`providerOptions` is `Record<string, unknown>` — unknown fields are forwarded to the Perplexity API unchanged, so newly-released filters work without a toolkit update. Other providers ignore `providerOptions`.
+
+### Reasoning models
+
+Pass reasoning model IDs as the `model` string:
+
+```typescript
+const client = createClientFromEnv('perplexity', 'sonar-reasoning-pro');
+```
+
+Available models (verified 2026-05-08):
+
+| Model | Notes |
+|---|---|
+| `sonar` | Lightweight search model. Default. |
+| `sonar-pro` | Advanced search, more citations. |
+| `sonar-reasoning-pro` | Chain-of-thought reasoning. Replaces deprecated `sonar-reasoning`. |
+| `sonar-deep-research` | Exhaustive research. Perplexity docs indicate async job support — treat as experimental with this toolkit. |
+
+`structured()` with `sonar-reasoning-pro` works correctly — reasoning tokens (`<think>...</think>`) are stripped before JSON parsing.
+
+`sonar-deep-research` is accepted as a model string. If Perplexity's API returns an incompatible async response shape, the call will throw a clear `LlmError`. In that case, use `sonar-reasoning-pro` instead, or wait for a future deep-research-specific brief.
 
 ## API
 
@@ -70,17 +140,114 @@ Creates an `LlmClient` for the given provider.
 Reads the API key from the environment automatically:
 - `anthropic` → `ANTHROPIC_API_KEY`
 - `openai` → `OPENAI_API_KEY`
-- `google` → `GOOGLE_AI_API_KEY`
+- `gemini` → `GOOGLE_AI_API_KEY`
 - `deepseek` → `DEEPSEEK_API_KEY`
+- `perplexity` → `PERPLEXITY_API_KEY`
 
 ### `LlmClient` interface
 
 | Method | Description |
 |---|---|
-| `complete(messages, options?)` | Non-streaming completion. Returns `LlmResponse`. |
-| `stream(messages, options?)` | Streaming — async generator of `LlmStreamChunk`. Final chunk includes `usage`. |
+| `complete(messages, options?)` | Non-streaming completion. Returns `LlmResponse` (includes `citations` for Perplexity). |
+| `stream(messages, options?)` | Streaming — async generator of `LlmStreamChunk`. Final chunk includes `usage`. Citations unavailable. |
 | `structured(messages, schema, options?)` | Structured output validated against a Zod schema. Returns `LlmStructuredResponse<T>`. |
 
+All methods accept `LlmCallOptions` as the options parameter:
+
+```typescript
+interface LlmCallOptions {
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  timeoutMs?: number;              // Per-call timeout (ms). Overrides config.timeoutMs.
+  signal?: AbortSignal;            // Caller-supplied cancel signal. Never retried.
+  streamStallTimeoutMs?: number;   // Per-chunk silence timeout for stream(). Default 30000.
+  providerOptions?: Record<string, unknown>;  // Perplexity search filters, etc.
+}
+```
+
+## Cancellation, timeouts, stall detection
+
+### Per-call timeout override
+
+The default timeout is set at client construction via `config.timeoutMs` (default 30 000 ms). Override it per-call:
+
+```typescript
+const client = createClient({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-6',
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  timeoutMs: 30_000, // client default
+});
+
+// This call gets 90 seconds — useful for sonar-deep-research or long reasoning
+const response = await client.complete(messages, { timeoutMs: 90_000 });
+```
+
+On timeout, `LlmError.kind === 'timeout'` and `retryable === true`. Each retry attempt gets a fresh deadline — the timeout resets per attempt, not across the full retry sequence.
+
+### Caller AbortSignal
+
+Pass any `AbortSignal` to cancel an in-flight call immediately:
+
+```typescript
+const ac = new AbortController();
+
+// Cancel on user navigation, request supersede, shutdown, etc.
+const responsePromise = client.complete(messages, { signal: ac.signal });
+
+// Cancel before the call returns
+ac.abort('user navigated away');
+
+try {
+  await responsePromise;
+} catch (err) {
+  if (err instanceof LlmError && err.kind === 'cancelled') {
+    // Gracefully handle the cancellation
+  }
+}
+```
+
+- A signal already aborted at call time throws immediately — no SDK call is made, no retry.
+- A mid-call abort propagates to the SDK (Anthropic, OpenAI, DeepSeek, Perplexity) or wins a `Promise.race` (Gemini). `kind === 'cancelled'`, `retryable === false`. Never retried.
+
+### Stream stall detection
+
+A stream that emits a first chunk and then silently hangs will stall the consumer indefinitely without this feature. `streamStallTimeoutMs` fires a timer per chunk — if no chunk arrives within the window, the stream is aborted and a `kind: 'stream_stall'` error surfaces:
+
+```typescript
+try {
+  for await (const chunk of client.stream(messages, { streamStallTimeoutMs: 10_000 })) {
+    process.stdout.write(chunk.token);
+  }
+} catch (err) {
+  if (err instanceof LlmError && err.kind === 'stream_stall') {
+    console.error('stream stalled — retry or fallback');
+  }
+}
+```
+
+- Default `streamStallTimeoutMs`: 30 000 ms (set independently of `timeoutMs` — tolerant of reasoning-model think-pauses).
+- The stall timer resets after each chunk arrives, so slow-but-not-stalled streams complete normally.
+- Stall errors are **not retried** — partial output is unsafe to re-issue. The error surfaces to the caller.
+
+### `LlmError.kind` discriminator
+
+```typescript
+type LlmErrorKind = 'cancelled' | 'timeout' | 'stream_stall' | 'http' | 'network' | 'unknown';
+
+class LlmError extends Error {
+  readonly provider: string;
+  readonly statusCode?: number;
+  readonly retryable: boolean;
+  readonly kind: LlmErrorKind | undefined; // undefined on errors from older paths
+}
+```
+
+### Gemini cancellation caveat
+
+`@google/genai` does not accept a per-call `AbortSignal`. Cancellation uses `Promise.race` — when the internal controller aborts, we stop awaiting, but the SDK's HTTP request continues in the background until the SDK-level timeout fires. The SDK client is constructed with `httpOptions.timeout = configTimeoutMs * 2` as a backstop. This bounds the leaked request to at most 2× the configured timeout. Native signal support will be added when the SDK provides it.
+
 ## Error handling
 
 All provider errors are normalized into `LlmError`:
@@ -92,12 +259,12 @@ try {
   const response = await client.complete(messages);
 } catch (err) {
   if (err instanceof LlmError) {
-    console.error(err.provider, err.statusCode, err.retryable);
+    console.error(err.provider, err.statusCode, err.retryable, err.kind);
   }
 }
 ```
 
-Retryable errors (429, 5xx, network failures) are retried automatically with exponential backoff and full jitter before throwing.
+Retryable errors (429, 5xx, network failures, timeout) are retried automatically with exponential backoff and full jitter before throwing. Cancelled and stream-stall errors are never retried.
 
 ## Token normalization
 

package/dist/index.d.ts

@@ -2,6 +2,17 @@
  * Core type definitions for @diabolicallabs/llm-client.
  * These are the stable public API surface — implementation is in Week 2.
  * Types here match the spec in briefs/brief-platform.md §4.1 exactly.
+ *
+ * Week 5 additions:
+ *   LlmResponse.citations — populated by the Perplexity provider; undefined for all others.
+ *   LlmCallOptions — per-call options type extracted for reuse; adds providerOptions escape hatch.
+ *
+ * Week 6 additions (v0.3.0 — abort/timeout/stall):
+ *   LlmCallOptions.timeoutMs      — per-call timeout override (ms); overrides config.timeoutMs.
+ *   LlmCallOptions.signal         — caller-supplied AbortSignal; aborts in-flight call.
+ *   LlmCallOptions.streamStallTimeoutMs — per-stream stall detection (ms); default 30000.
+ *   LlmClientConfig.streamStallTimeoutMs — config-level stall default.
+ *   LlmError.kind                 — discriminator for error classification.
  */
 interface LlmMessage {
     role: 'system' | 'user' | 'assistant';
@@ -16,6 +27,12 @@ interface LlmClientConfig {
     maxTokens?: number;
     temperature?: number;
     timeoutMs?: number;
+    /**
+     * Default stall timeout for stream() calls (ms). Fires when no chunk is received
+     * for this duration. Independent of timeoutMs — tolerant of reasoning-model think-pauses.
+     * Default: 30000.
+     */
+    streamStallTimeoutMs?: number;
 }
 interface LlmUsage {
     inputTokens: number;
@@ -29,22 +46,76 @@ interface LlmResponse {
     model: string;
     usage: LlmUsage;
     latencyMs: number;
+    /**
+     * Web citations returned by the Perplexity provider.
+     * Populated only when the Perplexity API returns source references.
+     * Always undefined for Anthropic, OpenAI, Gemini, and DeepSeek.
+     * Deduplicated by URL within a single response.
+     */
+    citations?: Array<{
+        url: string;
+        title?: string;
+    }>;
+}
+/**
+ * Per-call options shared across complete(), stream(), and structured().
+ * Extends the standard model/maxTokens/temperature overrides with:
+ *   timeoutMs           — per-call timeout override; overrides config.timeoutMs for this call only.
+ *   signal              — caller-supplied AbortSignal; aborts the in-flight call immediately.
+ *                         A pre-aborted signal throws without making an SDK call (no retry).
+ *                         A mid-call abort throws kind:'cancelled', retryable:false (no retry).
+ *   streamStallTimeoutMs — per-call stall detection for stream(); overrides config default.
+ *   providerOptions     — generic escape hatch for provider-specific parameters.
+ *                         The Perplexity provider reads search_domain_filter and
+ *                         search_recency_filter from this field; other providers ignore it.
+ *                         Unknown fields are passed through unchanged.
+ */
+interface LlmCallOptions extends Partial<Pick<LlmClientConfig, 'model' | 'maxTokens' | 'temperature' | 'timeoutMs'>> {
+    /** Caller-supplied AbortSignal. Cancels the in-flight call. Never retried. */
+    signal?: AbortSignal;
+    /**
+     * Per-call stall timeout for stream() in ms. Overrides config.streamStallTimeoutMs.
+     * Fires when no chunk arrives within this window. Default: config.streamStallTimeoutMs ?? 30000.
+     */
+    streamStallTimeoutMs?: number;
+    providerOptions?: Record<string, unknown>;
 }
 interface LlmStreamChunk {
     token: string;
     usage?: LlmUsage;
 }
+/**
+ * Discriminator for LlmError — lets callers branch on error class without
+ * parsing message strings.
+ *
+ * cancelled    — AbortSignal fired (caller-initiated). Never retried.
+ * timeout      — Per-call timeoutMs deadline exceeded. Retried by withRetry.
+ * stream_stall — No chunk received within streamStallTimeoutMs. Not retried
+ *                (partial stream output is unsafe to re-issue).
+ * http         — Non-retryable HTTP error (4xx excluding 429).
+ * network      — Retryable network-layer error (ECONNRESET, ETIMEDOUT, etc.).
+ * unknown      — Unclassified error.
+ */
+type LlmErrorKind = 'cancelled' | 'timeout' | 'stream_stall' | 'http' | 'network' | 'unknown';
 declare class LlmError extends Error {
     readonly name = "LlmError";
     readonly provider: string;
     readonly statusCode: number | undefined;
     readonly retryable: boolean;
+    /**
+     * Optional error kind discriminator. Present on errors produced by the abort/timeout/stall
+     * machinery (v0.3.0+). May be undefined on errors from providers that pre-date the kind field
+     * or on errors that fall through to the generic normalization path.
+     * Typed as LlmErrorKind | undefined to satisfy exactOptionalPropertyTypes.
+     */
+    readonly kind: LlmErrorKind | undefined;
     readonly cause: unknown;
     constructor(opts: {
         message: string;
         provider: string;
         statusCode?: number;
         retryable: boolean;
+        kind?: LlmErrorKind;
         cause?: unknown;
     });
 }
@@ -55,11 +126,11 @@ type LlmStructuredResponse<T> = {
 };
 interface LlmClient {
     readonly config: Readonly<LlmClientConfig>;
-    complete(messages: LlmMessage[], options?: Partial<Pick<LlmClientConfig, 'model' | 'maxTokens' | 'temperature'>>): Promise<LlmResponse>;
-    stream(messages: LlmMessage[], options?: Partial<Pick<LlmClientConfig, 'model' | 'maxTokens' | 'temperature'>>): AsyncGenerator<LlmStreamChunk>;
+    complete(messages: LlmMessage[], options?: LlmCallOptions): Promise<LlmResponse>;
+    stream(messages: LlmMessage[], options?: LlmCallOptions): AsyncGenerator<LlmStreamChunk>;
     structured<T>(messages: LlmMessage[], schema: {
         parse: (data: unknown) => T;
-    }, options?: Partial<Pick<LlmClientConfig, 'model' | 'maxTokens' | 'temperature'>>): Promise<LlmStructuredResponse<T>>;
+    }, options?: LlmCallOptions): Promise<LlmStructuredResponse<T>>;
 }
 
 /**
@@ -73,15 +144,13 @@ interface LlmClient {
  *   'openai'     → fully implemented (Week 2)
  *   'gemini'     → fully implemented (Week 3)
  *   'deepseek'   → fully implemented (Week 3)
- *   'perplexity' → stub, throws "not yet implemented" (later week)
+ *   'perplexity' → fully implemented (Week 5) — search-grounded, citations, providerOptions
  */
 
 /**
  * Create an LlmClient for the given provider and config.
  * Dispatches to the provider-specific implementation.
- *
- * Anthropic, OpenAI, Gemini, and DeepSeek are fully implemented.
- * Perplexity is a type-registered stub that throws "not yet implemented".
+ * All five providers are fully implemented.
  */
 declare function createClient(config: LlmClientConfig): LlmClient;
 /**
@@ -92,10 +161,10 @@ declare function createClient(config: LlmClientConfig): LlmClient;
  *   openai     → OPENAI_API_KEY
  *   gemini     → GOOGLE_AI_API_KEY
  *   deepseek   → DEEPSEEK_API_KEY
- *   perplexity → PERPLEXITY_API_KEY
+ *   perplexity → PERPLEXITY_API_KEY — recommended default model: 'sonar'
  *
  * Throws LlmError if the required env var is not set.
  */
 declare function createClientFromEnv(provider: LlmClientConfig['provider'], model: string, overrides?: Partial<Omit<LlmClientConfig, 'provider' | 'model' | 'apiKey'>>): LlmClient;
 
-export { type LlmClient, type LlmClientConfig, LlmError, type LlmMessage, type LlmResponse, type LlmStreamChunk, type LlmStructuredResponse, type LlmUsage, createClient, createClientFromEnv };
+export { type LlmCallOptions, type LlmClient, type LlmClientConfig, LlmError, type LlmMessage, type LlmResponse, type LlmStreamChunk, type LlmStructuredResponse, type LlmUsage, createClient, createClientFromEnv };