decisionmemos 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to Decision Memos will be documented in this file.
+
+## [1.1.0] — 2026-02-13
+
+### SDK Monetisation Split
+- **Free SDK**: New `MultiModelQuery` class and `createMultiModelQuery()` factory — query 4 models in parallel with typed responses, zero boilerplate
+- **Paid API**: Synthesis, personas, briefing, consensus scoring, and Decision Memos are now exclusive to the hosted API
+- Restructured public exports: free SDK ships only `MultiModelQuery`, model clients, and basic types
+- Engine internals (`DecisionEngine`, `Synthesizer`, `BriefingGenerator`, personas) excluded from npm package
+
+### Pricing Changes
+- **Pro**: 40 memos/month (doubled from 20)
+- **Team**: 200 memos/month (doubled from 100)
+- **BYOK discount**: 20% off per provider key supplied (up to 80% with all 4 keys)
+
+### Documentation
+- Docs sidebar reorganised into Free SDK / Paid API / Guides sections
+- New SDK reference documents `MultiModelQuery` API
+- BYOK guide updated with discount tiers and cost comparison
+- Quickstart rewritten for free SDK entry point with paid API upgrade path
+- For Developers section now shows both free and paid code snippets
+
+---
+
+## [1.0.0] — 2026-02-13
+
+### Core SDK
+- Multi-model parallel query engine (OpenAI, Anthropic, xAI, Google)
+- Persona layer — advisor archetypes (Strategist, Analyst, Challenger, Architect)
+- Transparent mode toggle — show real model names when needed
+- Decision Memo schema — structured JSON output with typed interfaces
+- Dynamic briefing generator — AI-powered contextual follow-up questions
+- Consensus scoring — strong, moderate, weak agreement levels
+- Custom persona support — override default archetypes
+
+### Hosted API
+- `POST /v1/deliberate` — Run panel deliberations via REST
+- `POST /v1/briefing` — Generate dynamic follow-up questions
+- `GET /v1/status` — Provider availability and usage stats
+- `GET /health` — Public health check
+- SSE streaming — real-time deliberation events (advisor.thinking, advisor.snippet, advisor.complete, synthesis.started, deliberation.complete)
+- Bearer token authentication (dm_live_ / dm_test_ keys)
+- Rate limiting — sliding window, per-plan limits
+- Quota enforcement — monthly memo caps
+- BYOK support — bring your own provider API keys per-request
+
+### Web
+- Landing page — hero, artifact showcase, how-it-works, advisor panel, developer section, pricing
+- Documentation site — 14 pages covering SDK, API, guides
+- Example gallery — real memo showcases
+- SaaS application:
+  - Guided memo flow (question → briefing → live deliberation → memo)
+  - Decision library with search
+  - Memo viewer with tabbed interface (verdict, perspectives, consensus, risks, next steps)
+  - Settings — plan management, API keys, BYOK configuration, transparent mode
+  - Share and PDF export actions
+
+### CLI
+- `npm run consultation` — Run memos from markdown files
+- JSON output with full comparison matrix

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decision Memos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# Decision Memos
+
+**Four advisors. One structured verdict.**
+
+Decision Memos has two tiers:
+
+1. **Free SDK** — Query GPT, Claude, Grok, and Gemini in parallel with one function call. Typed responses, zero boilerplate.
+2. **Paid API** — Adds persona-tuned prompts, synthesis with consensus scoring, dynamic briefing, and structured Decision Memos.
+
+## Free SDK — Quick Start
+
+```bash
+npm install decisionmemos
+```
+
+```typescript
+import { createMultiModelQuery } from 'decisionmemos';
+
+const query = createMultiModelQuery();
+
+const result = await query.ask(
+  'Should we migrate to microservices or adopt a modular monolith?'
+);
+
+for (const r of result.responses) {
+  console.log(`[${r.modelName}] ${r.response.slice(0, 200)}`);
+}
+// → 4 typed responses from 4 models, in parallel
+```
+
+### API Keys
+
+You need keys for the AI providers you want to use. The SDK works with any subset — missing providers are gracefully excluded.
+
+| Provider | Env Variable |
+|----------|-------------|
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| Google AI | `GOOGLE_API_KEY` |
+
+```bash
+# .env
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+XAI_API_KEY=xai-...
+GOOGLE_API_KEY=AIza...
+```
+
+## Paid API — Structured Verdicts
+
+The hosted API adds the orchestration layer that turns four raw responses into one structured verdict:
+
+| Feature | Free SDK | Paid API |
+|---------|----------|----------|
+| Parallel multi-model queries | Yes | Yes |
+| Typed model responses | Yes | Yes |
+| Advisor personas | - | Yes |
+| Persona-tuned system prompts | - | Yes |
+| Dynamic briefing (context intake) | - | Yes |
+| Synthesis with consensus scoring | - | Yes |
+| Structured Decision Memo | - | Yes |
+| SSE streaming deliberation | - | Yes |
+| BYOK discount (20% per key) | - | Yes |
+
+```bash
+curl -X POST https://api.decisionmemos.com/v1/deliberate \
+  -H "Authorization: Bearer dm_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "Should we migrate to microservices?",
+    "criteria": [
+      { "name": "Team readiness" },
+      { "name": "Timeline" }
+    ],
+    "byok": {
+      "openai": "sk-..."
+    }
+  }'
+```
+
+### BYOK Discount
+
+Supply your own provider API keys and save:
+- 1 key → 20% off
+- 2 keys → 40% off
+- 3 keys → 60% off
+- 4 keys → 80% off
+
+### Plans
+
+| Plan | Memos |
+|------|-------|
+| Starter ($14/mo) | 5/month |
+| Pro ($29/mo) | 40/month |
+| Team ($99/mo) | 200/month |
+| Enterprise | Unlimited |
+
+## The Decision Memo
+
+Every paid memo produces a structured artifact:
+
+- **Verdict** — Synthesised recommendation with consensus scoring (strong / moderate / weak)
+- **Perspectives** — Each advisor's individual analysis
+- **Consensus map** — Where the panel agreed and diverged
+- **Risks** — Identified risks with mitigations
+- **Trade-offs** — Key tensions the decision involves
+- **Next steps** — Prioritised implementation actions
+
+### Advisors
+
+| Advisor | Role | Strength |
+|---------|------|----------|
+| **The Strategist** | Big-picture thinking | Balanced, diplomatic, sees all angles |
+| **The Analyst** | Risk & nuance | Identifies second-order consequences |
+| **The Challenger** | Breaking groupthink | Challenges premises, calls out weak logic |
+| **The Architect** | Structure & implementation | Turns ideas into frameworks with evidence |
+
+## Brand & design system (source of truth)
+
+If you’re making **any** design, UI, or copy decision, start here:
+
+- `docs/BRAND.md`
+
+## Project Structure
+
+```
+decisionmemos/
+  src/                    # SDK source
+    index.ts              # Public API (free tier exports)
+    multi-model-query.ts  # MultiModelQuery class
+    types.ts              # TypeScript interfaces
+    clients/              # AI provider clients
+    engine/               # Deliberation engine (paid API only)
+    personas.ts           # Advisor archetypes (paid API only)
+  api/                    # Hosted API server
+    src/
+      server.ts           # Express server
+      auth.ts             # API key authentication
+      metering.ts         # Rate limits, quotas, BYOK discount
+      sse.ts              # Streaming helpers
+      routes/             # API endpoints
+  web/                    # Next.js landing + SaaS app
+  bin/                    # CLI tools (internal)
+```
+
+## Production (Vercel + Railway)
+
+Before go-live, set spending limits and follow the **rate limiting & caching** checklist so bots and traffic spikes don’t cause surprise bills: **[docs/RATE-LIMITING-AND-CACHING.md](docs/RATE-LIMITING-AND-CACHING.md)**.
+
+## Documentation
+
+Full documentation at [decisionmemos.com/docs](https://decisionmemos.com/docs):
+
+- [Quickstart](https://decisionmemos.com/docs/quickstart)
+- [SDK Reference](https://decisionmemos.com/docs/sdk)
+- [API Reference](https://decisionmemos.com/docs/api/deliberate)
+- [BYOK & Pricing](https://decisionmemos.com/docs/guides/byok)
+- [Streaming Guide](https://decisionmemos.com/docs/guides/streaming)
+- [Concepts](https://decisionmemos.com/docs/concepts)
+
+## Testing as a live user
+
+You can run the full memo flow end-to-end locally:
+
+1. **Start the API server** (needs provider API keys in `.env`):
+   ```bash
+   cd api
+   npm install
+   npm run dev    # listens on http://localhost:4000
+   ```
+
+2. **Set environment variables** for the web app:
+   ```bash
+   # web/.env.local
+   NEXT_PUBLIC_API_URL=http://localhost:4000
+   NEXT_PUBLIC_DM_API_KEY=dm_test_dev_key_001
+   ```
+   The dev test key (`dm_test_dev_key_001`) is seeded automatically in `api/src/auth.ts`.
+
+3. **Start the web app**:
+   ```bash
+   cd web
+   npm run dev    # listens on http://localhost:3000
+   ```
+
+4. **Use it**: Go to [http://localhost:3000/app/new](http://localhost:3000/app/new), enter a question, answer the briefing, and watch a real deliberation. When `NEXT_PUBLIC_API_URL` is not set, the app falls back to mock data so the UI is always testable.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/src/clients/anthropic-client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Anthropic API Client for Claude
+ */
+import { BaseModelClient } from './model-interface.js';
+import { ModelResponse } from '../types.js';
+export declare class AnthropicClient extends BaseModelClient {
+    readonly name: string;
+    readonly provider = "anthropic";
+    private client;
+    private model;
+    private maxOutputTokens;
+    constructor(apiKey: string, model?: string, maxOutputTokens?: number);
+    query(prompt: string, systemPrompt?: string): Promise<ModelResponse>;
+    testConnection(): Promise<boolean>;
+}
+//# sourceMappingURL=anthropic-client.d.ts.map

package/dist/src/clients/anthropic-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-client.d.ts","sourceRoot":"","sources":["../../../src/clients/anthropic-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,qBAAa,eAAgB,SAAQ,eAAe;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,eAAe;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,eAAe,CAAS;gBAG9B,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAA4B,EACnC,eAAe,GAAE,MAAkC;IAS/C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA4CpE,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAQzC"}

package/dist/src/clients/anthropic-client.js

@@ -0,0 +1,67 @@
+/**
+ * Anthropic API Client for Claude
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { BaseModelClient } from './model-interface.js';
+import { DEFAULT_MAX_OUTPUT_TOKENS } from '../constants.js';
+export class AnthropicClient extends BaseModelClient {
+    name;
+    provider = 'anthropic';
+    client;
+    model;
+    maxOutputTokens;
+    constructor(apiKey, model = 'claude-sonnet-4-6', maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS) {
+        super(apiKey);
+        this.client = new Anthropic({ apiKey });
+        this.model = model;
+        this.name = model;
+        this.maxOutputTokens = maxOutputTokens;
+    }
+    async query(prompt, systemPrompt) {
+        if (!this.isConfigured()) {
+            return this.createErrorResponse(new Error('Anthropic API key not configured'));
+        }
+        const startTime = Date.now();
+        try {
+            const message = await this.withRetry(() => this.client.messages.create({
+                model: this.model,
+                max_tokens: this.maxOutputTokens,
+                temperature: 0.7,
+                system: systemPrompt || undefined,
+                messages: [
+                    {
+                        role: 'user',
+                        content: prompt,
+                    },
+                ],
+            }));
+            const latency = Date.now() - startTime;
+            const responseText = message.content
+                .filter((block) => block.type === 'text')
+                .map((block) => block.text)
+                .join('\n');
+            return {
+                modelName: this.name,
+                provider: this.provider,
+                response: responseText,
+                timestamp: new Date(),
+                tokensUsed: message.usage.input_tokens + message.usage.output_tokens,
+                latency
+            };
+        }
+        catch (error) {
+            console.error(`Anthropic query error:`, error.message);
+            return this.createErrorResponse(error);
+        }
+    }
+    async testConnection() {
+        try {
+            const response = await this.query('Test connection. Respond with: OK');
+            return !response.error && response.response.includes('OK');
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=anthropic-client.js.map

package/dist/src/clients/anthropic-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-client.js","sourceRoot":"","sources":["../../../src/clients/anthropic-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,OAAO,eAAgB,SAAQ,eAAe;IACzC,IAAI,CAAS;IACb,QAAQ,GAAG,WAAW,CAAC;IACxB,MAAM,CAAY;IAClB,KAAK,CAAS;IACd,eAAe,CAAS;IAEhC,YACE,MAAc,EACd,QAAgB,mBAAmB,EACnC,kBAA0B,yBAAyB;QAEnD,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,YAAqB;QAC/C,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,mBAAmB,CAAC,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC,CAAC;QACjF,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAC1B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,UAAU,EAAE,IAAI,CAAC,eAAe;gBAChC,WAAW,EAAE,GAAG;gBAChB,MAAM,EAAE,YAAY,IAAI,SAAS;gBACjC,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,MAAM;qBAChB;iBACF;aACF,CAAC,CACH,CAAC;YAEF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAEvC,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO;iBACjC,MAAM,CAAC,CAAC,KAAU,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;iBAC7C,GAAG,CAAC,CAAC,KAAU,EAAE,EAAE,CAAE,KAA0B,CAAC,IAAI,CAAC;iBACrD,IAAI,CAAC,IAAI,CAAC,CAAC;YAEd,OAAO;gBACL,SAAS,EAAE,IAAI,CAAC,IAAI;gBACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,QAAQ,EAAE,YAAY;gBACtB,SAAS,EAAE,IAAI,IAAI,EAAE;gBACrB,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa;gBACpE,OAAO;aACR,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACvD,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;YACvE,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/src/clients/google-client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Google AI API Client for Gemini
+ */
+import { BaseModelClient } from './model-interface.js';
+import { ModelResponse } from '../types.js';
+export declare class GoogleClient extends BaseModelClient {
+    readonly name: string;
+    readonly provider = "google";
+    private client;
+    private model;
+    private maxOutputTokens;
+    constructor(apiKey: string, model?: string, maxOutputTokens?: number);
+    query(prompt: string, systemPrompt?: string): Promise<ModelResponse>;
+    testConnection(): Promise<boolean>;
+}
+//# sourceMappingURL=google-client.d.ts.map

package/dist/src/clients/google-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-client.d.ts","sourceRoot":"","sources":["../../../src/clients/google-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,qBAAa,YAAa,SAAQ,eAAe;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,YAAY;IAC7B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,eAAe,CAAS;gBAG9B,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAA+B,EACtC,eAAe,GAAE,MAAkC;IAS/C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAkCpE,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAQzC"}

package/dist/src/clients/google-client.js

@@ -0,0 +1,59 @@
+/**
+ * Google AI API Client for Gemini
+ */
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { BaseModelClient } from './model-interface.js';
+import { DEFAULT_MAX_OUTPUT_TOKENS } from '../constants.js';
+export class GoogleClient extends BaseModelClient {
+    name;
+    provider = 'google';
+    client;
+    model;
+    maxOutputTokens;
+    constructor(apiKey, model = 'gemini-3-pro-preview', maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS) {
+        super(apiKey);
+        this.client = new GoogleGenerativeAI(apiKey);
+        this.model = model;
+        this.name = model;
+        this.maxOutputTokens = maxOutputTokens;
+    }
+    async query(prompt, systemPrompt) {
+        if (!this.isConfigured()) {
+            return this.createErrorResponse(new Error('Google API key not configured'));
+        }
+        const startTime = Date.now();
+        try {
+            const genModel = this.client.getGenerativeModel({
+                model: this.model,
+                systemInstruction: systemPrompt,
+                generationConfig: { maxOutputTokens: this.maxOutputTokens }
+            });
+            const result = await this.withRetry(() => genModel.generateContent(prompt));
+            const response = result.response;
+            const text = response.text();
+            const latency = Date.now() - startTime;
+            return {
+                modelName: this.name,
+                provider: this.provider,
+                response: text,
+                timestamp: new Date(),
+                tokensUsed: response.usageMetadata?.totalTokenCount,
+                latency
+            };
+        }
+        catch (error) {
+            console.error(`Google AI query error:`, error.message);
+            return this.createErrorResponse(error);
+        }
+    }
+    async testConnection() {
+        try {
+            const response = await this.query('Test connection. Respond with: OK');
+            return !response.error && response.response.includes('OK');
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=google-client.js.map

package/dist/src/clients/google-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-client.js","sourceRoot":"","sources":["../../../src/clients/google-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,OAAO,YAAa,SAAQ,eAAe;IACtC,IAAI,CAAS;IACb,QAAQ,GAAG,QAAQ,CAAC;IACrB,MAAM,CAAqB;IAC3B,KAAK,CAAS;IACd,eAAe,CAAS;IAEhC,YACE,MAAc,EACd,QAAgB,sBAAsB,EACtC,kBAA0B,yBAAyB;QAEnD,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,YAAqB;QAC/C,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,mBAAmB,CAAC,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC,CAAC;QAC9E,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC;gBAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,iBAAiB,EAAE,YAAY;gBAC/B,gBAAgB,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE;aAC5D,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAS,CAAC;YAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;YAE7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAEvC,OAAO;gBACL,SAAS,EAAE,IAAI,CAAC,IAAI;gBACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,QAAQ,EAAE,IAAI;gBACd,SAAS,EAAE,IAAI,IAAI,EAAE;gBACrB,UAAU,EAAE,QAAQ,CAAC,aAAa,EAAE,eAAe;gBACnD,OAAO;aACR,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACvD,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;YACvE,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/src/clients/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * API Clients index - exports all model clients
+ */
+export type { AIModelClient } from './model-interface.js';
+export { BaseModelClient } from './model-interface.js';
+export { OpenAIClient } from './openai-client.js';
+export { XAIClient } from './xai-client.js';
+export { AnthropicClient } from './anthropic-client.js';
+export { GoogleClient } from './google-client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/clients/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/clients/index.js

@@ -0,0 +1,9 @@
+/**
+ * API Clients index - exports all model clients
+ */
+export { BaseModelClient } from './model-interface.js';
+export { OpenAIClient } from './openai-client.js';
+export { XAIClient } from './xai-client.js';
+export { AnthropicClient } from './anthropic-client.js';
+export { GoogleClient } from './google-client.js';
+//# sourceMappingURL=index.js.map

package/dist/src/clients/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/clients/model-interface.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Unified interface for all AI model clients
+ */
+import { ModelResponse } from '../types.js';
+export interface AIModelClient {
+    /**
+     * Name of the model (e.g., "GPT-5.2", "Claude Opus 4.6", "Grok 4.1", "Gemini 3 Pro")
+     */
+    readonly name: string;
+    /**
+     * Provider identifier
+     */
+    readonly provider: string;
+    /**
+     * Whether the client is properly configured and ready to use
+     */
+    isConfigured(): boolean;
+    /**
+     * Query the model with a prompt and system context
+     * @param prompt The user prompt/question
+     * @param systemPrompt Optional system-level instructions
+     * @returns ModelResponse with the completion and metadata
+     */
+    query(prompt: string, systemPrompt?: string): Promise<ModelResponse>;
+    /**
+     * Test the connection and configuration
+     */
+    testConnection(): Promise<boolean>;
+}
+export declare abstract class BaseModelClient implements AIModelClient {
+    abstract readonly name: string;
+    abstract readonly provider: string;
+    protected apiKey: string;
+    /** Maximum retries for transient API errors (0 = no retry) */
+    protected maxRetries: number;
+    constructor(apiKey: string);
+    isConfigured(): boolean;
+    abstract query(prompt: string, systemPrompt?: string): Promise<ModelResponse>;
+    abstract testConnection(): Promise<boolean>;
+    /**
+     * Retry wrapper for transient API errors.
+     * Retries up to `maxRetries` times with exponential backoff (1s, 2s, 4s…)
+     * only when the thrown error is classified as transient (network issues,
+     * rate limits, server errors).
+     *
+     * The `() => T` signature (rather than `() => Promise<T>`) ensures that
+     * when SDK module types are unavailable and the callback returns `any`,
+     * the result correctly resolves to `any` via `Awaited<any>` instead of
+     * falling back to `unknown`.
+     */
+    protected withRetry<T>(fn: () => T): Promise<Awaited<T>>;
+    protected createErrorResponse(error: unknown): ModelResponse;
+}
+/** Determine whether an error is transient and worth retrying. */
+export declare function isRetryableError(error: unknown): boolean;
+/** Calculate the backoff delay for a given retry attempt. */
+export declare function retryDelay(attempt: number, error?: unknown): number;
+/** Promisified sleep. */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=model-interface.d.ts.map

package/dist/src/clients/model-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-interface.d.ts","sourceRoot":"","sources":["../../../src/clients/model-interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAwB5C,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,YAAY,IAAI,OAAO,CAAC;IAExB;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAErE;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACpC;AAMD,8BAAsB,eAAgB,YAAW,aAAa;IAC5D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IACnC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IAEzB,8DAA8D;IAC9D,SAAS,CAAC,UAAU,EAAE,MAAM,CAAuB;gBAEvC,MAAM,EAAE,MAAM;IAI1B,YAAY,IAAI,OAAO;IAIvB,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAC7E,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAE3C;;;;;;;;;;OAUG;cACa,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAsB9D,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa;CAgB7D;AAMD,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASxD;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CASnE;AAED,yBAAyB;AACzB,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/src/clients/model-interface.js

@@ -0,0 +1,109 @@
+/**
+ * Unified interface for all AI model clients
+ */
+// ---------------------------------------------------------------------------
+// Retry configuration
+// ---------------------------------------------------------------------------
+/** HTTP status codes that indicate a transient, retryable failure */
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 529]);
+/** Error message substrings that indicate a transient failure */
+const RETRYABLE_PATTERNS = [
+    'econnrefused', 'econnreset', 'etimedout', 'enotfound',
+    'timeout', 'rate limit', 'rate_limit', 'overloaded',
+    'capacity', 'network', 'socket hang up', 'fetch failed',
+    'service unavailable', 'internal server error',
+];
+/** Default number of retries for transient API errors */
+const DEFAULT_MAX_RETRIES = 2;
+// ---------------------------------------------------------------------------
+// Base class with built-in retry
+// ---------------------------------------------------------------------------
+export class BaseModelClient {
+    apiKey;
+    /** Maximum retries for transient API errors (0 = no retry) */
+    maxRetries = DEFAULT_MAX_RETRIES;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    isConfigured() {
+        return !!this.apiKey && this.apiKey !== 'your_api_key_here';
+    }
+    /**
+     * Retry wrapper for transient API errors.
+     * Retries up to `maxRetries` times with exponential backoff (1s, 2s, 4s…)
+     * only when the thrown error is classified as transient (network issues,
+     * rate limits, server errors).
+     *
+     * The `() => T` signature (rather than `() => Promise<T>`) ensures that
+     * when SDK module types are unavailable and the callback returns `any`,
+     * the result correctly resolves to `any` via `Awaited<any>` instead of
+     * falling back to `unknown`.
+     */
+    async withRetry(fn) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastError = err;
+                if (attempt < this.maxRetries && isRetryableError(err)) {
+                    const delay = retryDelay(attempt, err);
+                    console.warn(`[${this.name}] Attempt ${attempt + 1}/${this.maxRetries + 1} failed` +
+                        ` (${err instanceof Error ? err.message : err}), retrying in ${delay}ms…`);
+                    await sleep(delay);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        throw lastError;
+    }
+    createErrorResponse(error) {
+        const message = error instanceof Error
+            ? error.message
+            : typeof error === 'string'
+                ? error
+                : 'Unknown error occurred';
+        return {
+            modelName: this.name,
+            provider: this.provider,
+            response: '',
+            timestamp: new Date(),
+            latency: 0,
+            error: message
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers (exported for testing)
+// ---------------------------------------------------------------------------
+/** Determine whether an error is transient and worth retrying. */
+export function isRetryableError(error) {
+    if (!error)
+        return false;
+    // HTTP status from SDK errors (OpenAI, Anthropic, etc.)
+    const status = error?.status ?? error?.statusCode;
+    if (typeof status === 'number' && RETRYABLE_STATUS_CODES.has(status))
+        return true;
+    const msg = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return RETRYABLE_PATTERNS.some((p) => msg.includes(p));
+}
+/** Calculate the backoff delay for a given retry attempt. */
+export function retryDelay(attempt, error) {
+    // Honour Retry-After from rate-limit responses (in seconds)
+    const retryAfter = error?.headers?.['retry-after'];
+    if (retryAfter) {
+        const secs = parseInt(retryAfter, 10);
+        if (!isNaN(secs) && secs > 0 && secs <= 60)
+            return secs * 1000;
+    }
+    // Exponential backoff: 1s, 2s, 4s… capped at 10s
+    return Math.min(1000 * Math.pow(2, attempt), 10_000);
+}
+/** Promisified sleep. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=model-interface.js.map