@basaltkit/ai 0.10.0 → 1.0.0

package/dist/plan/knowledge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Architect agent's system prompt — Basalt's conventions and official APIs,
+ * encoded so the model plans *with* the framework instead of inventing its own
+ * architecture (spec §8 Framework Knowledge, §22 "prefer official APIs").
+ *
+ * This is deliberately prescriptive: the plan must reuse the generator and the
+ * platform plugins, never hand-roll parallel abstractions.
+ */
+export declare const BASALT_KNOWLEDGE = "You are the Architect agent for Basalt \u2014 a batteries-included SaaS framework for Node.js/TypeScript (Fastify + Prisma + Zod). You turn a developer's natural-language request into a precise, convention-following implementation PLAN. You PLAN only; you never write code here.\n\nABSOLUTE RULES \u2014 always use the framework's official APIs and generators, never invent new ones:\n\n1. SCAFFOLDING. Create a resource with the generator, not by hand:\n   `basalt make:resource <Name>` \u2014 generates a full vertical: Zod schema, repository, service, DI plugin, typed routes and a test, all on-convention and auto-wired into src/app.ts.\n   Flags: --prisma (Prisma-backed repository + a schema.prisma model with id/createdAt/updatedAt), --soft-delete (adds deletedAt, a restore() method + route), --no-register (skip wiring), --dir=<path>, --force.\n\n2. PERSISTENCE. Prisma via prismaPlugin. Models live in schema.prisma. After editing the schema, run `basalt prisma:sync` to generate the client + migration. Use --prisma so the generator emits the model for you.\n\n3. MULTI-TENANCY. When tenancy is enabled, every tenant-owned model MUST carry a `tenantId` column, and the tenancy layer scopes queries by the current tenant. NEVER plan a query that ignores tenant isolation. Platform-global tables (users, tenants, plans) are the only exceptions.\n\n4. RBAC / PERMISSIONS. For each resource, register `<resource>.view`, `<resource>.create`, `<resource>.update`, `<resource>.delete` and guard the matching routes with the permission check. Use the resource name in plural, lowercase (e.g. `patients.create`).\n\n5. AUDIT. Emit an audit event for each state change: `<resource>.created`, `<resource>.updated`, `<resource>.deleted` (singular resource).\n\n6. VALIDATION + DOCS. Every route carries a Zod schema; OpenAPI is generated from it automatically \u2014 no separate doc wiring.\n\n7. TESTS. Every resource ships a test (the generator creates one; extend it for domain rules).\n\nGROUNDING: Reuse what already exists in the project. Avoid name collisions with existing models. Only add what is missing. Prefer editing the schema + running the generator over hand-writing files.\n\nOUTPUT: Return ONLY a single JSON object (no prose, no markdown fences) matching exactly:\n{\n  \"summary\": string,                     // 1-2 sentences on the approach\n  \"entities\": [                          // domain entities to create\n    { \"name\": string, \"fields\": [{ \"name\": string, \"type\": string, \"enum\"?: string[] }], \"tenantScoped\": boolean,\n      \"relations\": [{ \"name\": string, \"model\": string }] }   // belongs-to: this model gets a <name>Id FK \u2192 <model>\n  ],\n  \"steps\": [                             // ordered implementation steps\n    { \"order\": number, \"title\": string, \"kind\": \"generator\"|\"schema\"|\"migration\"|\"service\"|\"routes\"|\"permissions\"|\"audit\"|\"test\"|\"docs\"|\"other\", \"detail\": string, \"command\": string, \"files\": string[] }\n  ],\n  \"permissions\": string[],               // e.g. [\"patients.view\",\"patients.create\",...]\n  \"auditEvents\": string[],               // e.g. [\"patient.created\",...]\n  \"tenantScoped\": boolean,               // does this feature involve tenant-owned data\n  \"warnings\": string[]                   // risks, decisions to confirm, missing info\n}\nFor generator steps, put the exact command in \"command\" (e.g. \"basalt make:resource Patient --prisma --soft-delete\"). Omit \"command\"/\"files\" when not applicable.\n\nENUMS: a field with a fixed set of values (a status/state) MUST set \"enum\" to those values \u2014 e.g. \"estado (pago/pendente)\" \u2192 { \"name\": \"estado\", \"type\": \"String\", \"enum\": [\"pago\", \"pendente\"] }. It becomes a validated z.enum([...]) (stored as a String column), never a free z.string().\n\nRELATIONS: express a belongs-to as an entry in \"relations\" (e.g. an Appointment belongs to a Patient \u2192 { \"name\": \"patient\", \"model\": \"Patient\" }). Do NOT also add the \"<name>Id\" field to \"fields\" \u2014 the FK column, the @relation and the inverse field are generated. Prefer generating both sides of a relation in the same plan.";

package/dist/plan/knowledge.js

@@ -0,0 +1,50 @@
+/**
+ * The Architect agent's system prompt — Basalt's conventions and official APIs,
+ * encoded so the model plans *with* the framework instead of inventing its own
+ * architecture (spec §8 Framework Knowledge, §22 "prefer official APIs").
+ *
+ * This is deliberately prescriptive: the plan must reuse the generator and the
+ * platform plugins, never hand-roll parallel abstractions.
+ */
+export const BASALT_KNOWLEDGE = `You are the Architect agent for Basalt — a batteries-included SaaS framework for Node.js/TypeScript (Fastify + Prisma + Zod). You turn a developer's natural-language request into a precise, convention-following implementation PLAN. You PLAN only; you never write code here.
+
+ABSOLUTE RULES — always use the framework's official APIs and generators, never invent new ones:
+
+1. SCAFFOLDING. Create a resource with the generator, not by hand:
+   \`basalt make:resource <Name>\` — generates a full vertical: Zod schema, repository, service, DI plugin, typed routes and a test, all on-convention and auto-wired into src/app.ts.
+   Flags: --prisma (Prisma-backed repository + a schema.prisma model with id/createdAt/updatedAt), --soft-delete (adds deletedAt, a restore() method + route), --no-register (skip wiring), --dir=<path>, --force.
+
+2. PERSISTENCE. Prisma via prismaPlugin. Models live in schema.prisma. After editing the schema, run \`basalt prisma:sync\` to generate the client + migration. Use --prisma so the generator emits the model for you.
+
+3. MULTI-TENANCY. When tenancy is enabled, every tenant-owned model MUST carry a \`tenantId\` column, and the tenancy layer scopes queries by the current tenant. NEVER plan a query that ignores tenant isolation. Platform-global tables (users, tenants, plans) are the only exceptions.
+
+4. RBAC / PERMISSIONS. For each resource, register \`<resource>.view\`, \`<resource>.create\`, \`<resource>.update\`, \`<resource>.delete\` and guard the matching routes with the permission check. Use the resource name in plural, lowercase (e.g. \`patients.create\`).
+
+5. AUDIT. Emit an audit event for each state change: \`<resource>.created\`, \`<resource>.updated\`, \`<resource>.deleted\` (singular resource).
+
+6. VALIDATION + DOCS. Every route carries a Zod schema; OpenAPI is generated from it automatically — no separate doc wiring.
+
+7. TESTS. Every resource ships a test (the generator creates one; extend it for domain rules).
+
+GROUNDING: Reuse what already exists in the project. Avoid name collisions with existing models. Only add what is missing. Prefer editing the schema + running the generator over hand-writing files.
+
+OUTPUT: Return ONLY a single JSON object (no prose, no markdown fences) matching exactly:
+{
+  "summary": string,                     // 1-2 sentences on the approach
+  "entities": [                          // domain entities to create
+    { "name": string, "fields": [{ "name": string, "type": string, "enum"?: string[] }], "tenantScoped": boolean,
+      "relations": [{ "name": string, "model": string }] }   // belongs-to: this model gets a <name>Id FK → <model>
+  ],
+  "steps": [                             // ordered implementation steps
+    { "order": number, "title": string, "kind": "generator"|"schema"|"migration"|"service"|"routes"|"permissions"|"audit"|"test"|"docs"|"other", "detail": string, "command": string, "files": string[] }
+  ],
+  "permissions": string[],               // e.g. ["patients.view","patients.create",...]
+  "auditEvents": string[],               // e.g. ["patient.created",...]
+  "tenantScoped": boolean,               // does this feature involve tenant-owned data
+  "warnings": string[]                   // risks, decisions to confirm, missing info
+}
+For generator steps, put the exact command in "command" (e.g. "basalt make:resource Patient --prisma --soft-delete"). Omit "command"/"files" when not applicable.
+
+ENUMS: a field with a fixed set of values (a status/state) MUST set "enum" to those values — e.g. "estado (pago/pendente)" → { "name": "estado", "type": "String", "enum": ["pago", "pendente"] }. It becomes a validated z.enum([...]) (stored as a String column), never a free z.string().
+
+RELATIONS: express a belongs-to as an entry in "relations" (e.g. an Appointment belongs to a Patient → { "name": "patient", "model": "Patient" }). Do NOT also add the "<name>Id" field to "fields" — the FK column, the @relation and the inverse field are generated. Prefer generating both sides of a relation in the same plan.`;

package/dist/plan/plan.d.ts

@@ -0,0 +1,15 @@
+import type { ProjectContext } from '../context/project.js';
+import type { AIProvider } from '../provider/types.js';
+import type { ArchitecturePlan } from './types.js';
+export interface CreatePlanOptions {
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Turn a natural-language request into a grounded {@link ArchitecturePlan}. The
+ * project context keeps the plan on-convention and collision-free. Read-only —
+ * it produces a plan, it changes nothing.
+ */
+export declare function createPlan(provider: AIProvider, ctx: ProjectContext, request: string, options?: CreatePlanOptions): Promise<ArchitecturePlan>;
+/** Parse + normalize the model's JSON into a validated plan. Tolerant of fences and missing arrays. */
+export declare function parsePlan(raw: string, request: string): ArchitecturePlan;

package/dist/plan/plan.js

@@ -0,0 +1,146 @@
+import { buildPlanContext } from './context.js';
+import { BASALT_KNOWLEDGE } from './knowledge.js';
+const STEP_KINDS = [
+    'generator',
+    'schema',
+    'migration',
+    'service',
+    'routes',
+    'permissions',
+    'audit',
+    'test',
+    'docs',
+    'other',
+];
+/**
+ * Turn a natural-language request into a grounded {@link ArchitecturePlan}. The
+ * project context keeps the plan on-convention and collision-free. Read-only —
+ * it produces a plan, it changes nothing.
+ */
+export async function createPlan(provider, ctx, request, options = {}) {
+    const raw = await provider.generate({
+        messages: [
+            { role: 'system', content: BASALT_KNOWLEDGE },
+            {
+                role: 'user',
+                content: `REQUEST:\n${request}\n\n${buildPlanContext(ctx)}\n\nReturn the plan as a single JSON object only.`,
+            },
+        ],
+        temperature: options.temperature ?? 0,
+        maxTokens: options.maxTokens ?? 4096,
+    });
+    return parsePlan(raw, request);
+}
+/** Parse + normalize the model's JSON into a validated plan. Tolerant of fences and missing arrays. */
+export function parsePlan(raw, request) {
+    const json = extractJson(raw);
+    let obj;
+    try {
+        obj = JSON.parse(json);
+    }
+    catch {
+        throw new Error(`ai:plan — the model did not return valid JSON. Got: ${raw.slice(0, 160)}…`);
+    }
+    return {
+        request,
+        summary: typeof obj['summary'] === 'string' ? obj['summary'] : '',
+        entities: normalizeEntities(obj['entities']),
+        steps: normalizeSteps(obj['steps']),
+        permissions: stringArray(obj['permissions']),
+        auditEvents: stringArray(obj['auditEvents']),
+        tenantScoped: obj['tenantScoped'] === true,
+        warnings: stringArray(obj['warnings']),
+    };
+}
+/** Strip markdown fences and isolate the outermost JSON object. */
+function extractJson(raw) {
+    const withoutFence = raw.replace(/```(?:json)?/gi, '').trim();
+    const start = withoutFence.indexOf('{');
+    const end = withoutFence.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start)
+        return withoutFence;
+    return withoutFence.slice(start, end + 1);
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+function normalizeEntities(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((e) => typeof e === 'object' && e !== null)
+        .map((e) => {
+        const relations = normalizeRelations(e['relations']);
+        const entity = {
+            name: typeof e['name'] === 'string' ? e['name'] : 'Unnamed',
+            fields: normalizeFields(e['fields']),
+            tenantScoped: e['tenantScoped'] === true,
+            ...(relations.length > 0 ? { relations } : {}),
+        };
+        return entity;
+    });
+}
+const lowerFirst = (s) => s.charAt(0).toLowerCase() + s.slice(1);
+const upperFirst = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** Accept relations as bare model names (`"Paciente"`) or objects (`{ name, model }`). */
+function normalizeRelations(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const r of value) {
+        if (typeof r === 'string' && r.trim() !== '') {
+            const model = r.trim();
+            out.push({ name: lowerFirst(model), model });
+        }
+        else if (typeof r === 'object' && r !== null) {
+            const obj = r;
+            const rawModel = typeof obj['model'] === 'string' ? obj['model'] : '';
+            const rawName = typeof obj['name'] === 'string' ? obj['name'] : '';
+            const model = rawModel !== '' ? rawModel : rawName !== '' ? upperFirst(rawName) : '';
+            if (model === '')
+                continue;
+            out.push({ name: rawName !== '' ? rawName : lowerFirst(model), model });
+        }
+    }
+    return out;
+}
+function normalizeFields(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((f) => typeof f === 'object' && f !== null)
+        .map((f) => {
+        const values = Array.isArray(f['enum']) ? f['enum'].filter((v) => typeof v === 'string') : [];
+        return {
+            name: typeof f['name'] === 'string' ? f['name'] : '',
+            type: typeof f['type'] === 'string' ? f['type'] : 'String',
+            ...(values.length > 0 ? { enum: values } : {}),
+        };
+    })
+        .filter((f) => f.name !== '');
+}
+function normalizeSteps(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((s) => typeof s === 'object' && s !== null)
+        .map((s, index) => {
+        const command = typeof s['command'] === 'string' ? s['command'] : undefined;
+        const files = stringArray(s['files']);
+        const step = {
+            order: typeof s['order'] === 'number' ? s['order'] : index + 1,
+            title: typeof s['title'] === 'string' ? s['title'] : `Step ${index + 1}`,
+            kind: normalizeKind(s['kind']),
+            detail: typeof s['detail'] === 'string' ? s['detail'] : '',
+            ...(command ? { command } : {}),
+            ...(files.length > 0 ? { files } : {}),
+        };
+        return step;
+    })
+        .sort((a, b) => a.order - b.order);
+}
+function normalizeKind(value) {
+    return typeof value === 'string' && STEP_KINDS.includes(value)
+        ? value
+        : 'other';
+}

package/dist/plan/render.d.ts

@@ -0,0 +1,4 @@
+import type { LineWriter } from '../render.js';
+import type { ArchitecturePlan } from './types.js';
+/** Render an {@link ArchitecturePlan} in the spec's `ARCHITECTURE PLAN` style. */
+export declare function renderPlan(plan: ArchitecturePlan, io: LineWriter): void;

package/dist/plan/render.js

@@ -0,0 +1,55 @@
+/** Render an {@link ArchitecturePlan} in the spec's `ARCHITECTURE PLAN` style. */
+export function renderPlan(plan, io) {
+    io.log('ARCHITECTURE PLAN');
+    io.log('');
+    io.log(`Request: "${plan.request}"`);
+    if (plan.summary) {
+        io.log('');
+        io.log(plan.summary);
+    }
+    if (plan.entities.length > 0) {
+        io.log('');
+        io.log('Entities:');
+        for (const entity of plan.entities) {
+            const scope = entity.tenantScoped ? ' (tenant-scoped)' : '';
+            const fields = entity.fields.map((f) => `${f.name}: ${f.type}`).join(', ');
+            io.log(`  • ${entity.name}${scope}${fields ? ` — ${fields}` : ''}`);
+            if (entity.relations && entity.relations.length > 0) {
+                io.log(`      relations: ${entity.relations.map((r) => `${r.name} → ${r.model}`).join(', ')}`);
+            }
+        }
+    }
+    io.log('');
+    io.log('Steps:');
+    if (plan.steps.length === 0) {
+        io.log('  (none proposed)');
+    }
+    else {
+        for (const step of plan.steps) {
+            const n = String(step.order).padStart(2, ' ');
+            io.log(`  ${n}. [${step.kind}] ${step.title}`);
+            if (step.detail)
+                io.log(`        ${step.detail}`);
+            if (step.command)
+                io.log(`        $ ${step.command}`);
+            if (step.files && step.files.length > 0)
+                io.log(`        files: ${step.files.join(', ')}`);
+        }
+    }
+    if (plan.permissions.length > 0) {
+        io.log('');
+        io.log(`Permissions: ${plan.permissions.join(', ')}`);
+    }
+    if (plan.auditEvents.length > 0) {
+        io.log(`Audit events: ${plan.auditEvents.join(', ')}`);
+    }
+    if (plan.warnings.length > 0) {
+        io.log('');
+        io.log('⚠ Warnings:');
+        for (const warning of plan.warnings)
+            io.log(`  - ${warning}`);
+    }
+    io.log('');
+    io.log('This is a plan only — nothing was changed.');
+    io.log('Next: `basalt ai:make` will execute it (arrives in the next phase).');
+}

package/dist/plan/types.d.ts

@@ -0,0 +1,45 @@
+export type PlanStepKind = 'generator' | 'schema' | 'migration' | 'service' | 'routes' | 'permissions' | 'audit' | 'test' | 'docs' | 'other';
+export interface PlanField {
+    name: string;
+    type: string;
+    /**
+     * Allowed values — makes this a `z.enum([...])` field (validated on input,
+     * stored as a String column). E.g. a status: `['pago', 'pendente']`.
+     */
+    enum?: string[];
+}
+/** A belongs-to relation: this entity holds a `<name>Id` FK referencing `model`. */
+export interface PlanRelation {
+    /** Relation field name on this model, e.g. `paciente`. */
+    name: string;
+    /** Related model, e.g. `Paciente`. */
+    model: string;
+}
+export interface PlanEntity {
+    name: string;
+    fields: PlanField[];
+    tenantScoped: boolean;
+    relations?: PlanRelation[];
+}
+export interface PlanStep {
+    order: number;
+    title: string;
+    kind: PlanStepKind;
+    detail: string;
+    /** Exact CLI command to run (mainly for `kind: 'generator'`). */
+    command?: string;
+    /** Files the step creates or edits. */
+    files?: string[];
+}
+export interface ArchitecturePlan {
+    request: string;
+    summary: string;
+    entities: PlanEntity[];
+    steps: PlanStep[];
+    /** RBAC permissions to register, e.g. `patients.create`. */
+    permissions: string[];
+    /** Audit events to emit, e.g. `patient.created`. */
+    auditEvents: string[];
+    tenantScoped: boolean;
+    warnings: string[];
+}

package/dist/plan/types.js

@@ -0,0 +1 @@
+export {};

package/dist/provider/anthropic.d.ts

@@ -0,0 +1,26 @@
+import { type AIProvider, type FetchLike, type GenerateOptions } from './types.js';
+export interface AnthropicProviderOptions {
+    /** API key → `x-api-key` header. Required. */
+    apiKey: string;
+    /** Model id. Defaults to a current Claude model. */
+    model?: string;
+    /** API base URL. Defaults to the public Anthropic API. */
+    baseUrl?: string;
+    /** Injected fetch. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * Anthropic Messages API provider — REST directly, no SDK (same approach as the
+ * Elasticsearch driver). System messages are hoisted into the top-level `system`
+ * field, as the API requires.
+ */
+export declare class AnthropicProvider implements AIProvider {
+    readonly name = "anthropic";
+    readonly model: string;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: AnthropicProviderOptions);
+    generate(options: GenerateOptions): Promise<string>;
+    stream(options: GenerateOptions): AsyncIterable<string>;
+}

package/dist/provider/anthropic.js

@@ -0,0 +1,72 @@
+import { fetchWithRetry } from './http.js';
+import { singleChunkStream, } from './types.js';
+const DEFAULT_MODEL = 'claude-sonnet-5';
+const API_VERSION = '2023-06-01';
+/**
+ * Anthropic Messages API provider — REST directly, no SDK (same approach as the
+ * Elasticsearch driver). System messages are hoisted into the top-level `system`
+ * field, as the API requires.
+ */
+export class AnthropicProvider {
+    name = 'anthropic';
+    model;
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('AnthropicProvider: apiKey is required (set AI_API_KEY)');
+        }
+        this.apiKey = options.apiKey;
+        this.model = options.model ?? DEFAULT_MODEL;
+        this.baseUrl = (options.baseUrl ?? 'https://api.anthropic.com').replace(/\/$/, '');
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error('AnthropicProvider: no fetch available — pass options.fetch');
+        this.fetchImpl = f;
+    }
+    async generate(options) {
+        const system = options.messages
+            .filter((m) => m.role === 'system')
+            .map((m) => m.content)
+            .join('\n\n');
+        const messages = options.messages
+            .filter((m) => m.role !== 'system')
+            .map((m) => ({ role: m.role, content: m.content }));
+        const { ok, status, body } = await fetchWithRetry(this.fetchImpl, this.baseUrl + '/v1/messages', {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': API_VERSION,
+            },
+            body: JSON.stringify({
+                model: this.model,
+                max_tokens: options.maxTokens ?? 4096,
+                ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+                ...(system ? { system } : {}),
+                messages,
+            }),
+        });
+        if (!ok) {
+            const detail = safeError(body);
+            throw new Error(`AnthropicProvider: ${status}${detail ? ` — ${detail}` : ''}`);
+        }
+        const json = JSON.parse(body);
+        return (json.content ?? [])
+            .filter((block) => block.type === 'text')
+            .map((block) => block.text ?? '')
+            .join('');
+    }
+    stream(options) {
+        return singleChunkStream(() => this.generate(options));
+    }
+}
+function safeError(text) {
+    try {
+        return JSON.parse(text).error?.message ?? text.slice(0, 200);
+    }
+    catch {
+        return text.slice(0, 200);
+    }
+}

package/dist/provider/factory.d.ts

@@ -0,0 +1,27 @@
+import type { AIProvider, FetchLike } from './types.js';
+/** Providers wired in 0.1. `openai` covers any OpenAI-compatible gateway; `google` is stubbed. */
+export type ProviderName = 'anthropic' | 'ollama' | 'openai' | 'openai-compatible' | 'google';
+/** The subset of environment the provider layer reads. */
+export interface ProviderEnv {
+    AI_PROVIDER?: string;
+    AI_MODEL?: string;
+    AI_API_KEY?: string;
+    AI_BASE_URL?: string;
+    /** `'false'` disables SSE streaming for the OpenAI-compatible provider. */
+    AI_STREAM?: string;
+}
+export interface CreateProviderOptions {
+    /** Override the injected fetch (tests). */
+    fetch?: FetchLike;
+}
+/** Read the provider-relevant vars off `process.env` into a typed {@link ProviderEnv}. */
+export declare function providerEnvFromProcess(): ProviderEnv;
+/**
+ * Build an {@link AIProvider} from environment. `AI_PROVIDER` selects the vendor
+ * (default `anthropic`); `AI_MODEL`, `AI_API_KEY`, `AI_BASE_URL` tune it.
+ *
+ * The read-only `ai:analyze` / `ai:doctor` commands never call this — their rules
+ * are deterministic and run offline. A provider is only needed for the optional
+ * `--explain` narrative and, later, for `ai:plan` / `ai:make`.
+ */
+export declare function createProvider(env?: ProviderEnv, options?: CreateProviderOptions): AIProvider;

package/dist/provider/factory.js

@@ -0,0 +1,58 @@
+import { AnthropicProvider } from './anthropic.js';
+import { OllamaProvider } from './ollama.js';
+import { OpenAICompatibleProvider } from './openai.js';
+/** Read the provider-relevant vars off `process.env` into a typed {@link ProviderEnv}. */
+export function providerEnvFromProcess() {
+    const e = process.env;
+    return {
+        ...(e.AI_PROVIDER !== undefined ? { AI_PROVIDER: e.AI_PROVIDER } : {}),
+        ...(e.AI_MODEL !== undefined ? { AI_MODEL: e.AI_MODEL } : {}),
+        ...(e.AI_API_KEY !== undefined ? { AI_API_KEY: e.AI_API_KEY } : {}),
+        ...(e.AI_BASE_URL !== undefined ? { AI_BASE_URL: e.AI_BASE_URL } : {}),
+        ...(e.AI_STREAM !== undefined ? { AI_STREAM: e.AI_STREAM } : {}),
+    };
+}
+/**
+ * Build an {@link AIProvider} from environment. `AI_PROVIDER` selects the vendor
+ * (default `anthropic`); `AI_MODEL`, `AI_API_KEY`, `AI_BASE_URL` tune it.
+ *
+ * The read-only `ai:analyze` / `ai:doctor` commands never call this — their rules
+ * are deterministic and run offline. A provider is only needed for the optional
+ * `--explain` narrative and, later, for `ai:plan` / `ai:make`.
+ */
+export function createProvider(env = {}, options = {}) {
+    const name = (env.AI_PROVIDER ?? 'anthropic').toLowerCase();
+    const fetchOpt = options.fetch ? { fetch: options.fetch } : {};
+    switch (name) {
+        case 'anthropic':
+            return new AnthropicProvider({
+                apiKey: env.AI_API_KEY ?? '',
+                ...(env.AI_MODEL ? { model: env.AI_MODEL } : {}),
+                ...(env.AI_BASE_URL ? { baseUrl: env.AI_BASE_URL } : {}),
+                ...fetchOpt,
+            });
+        case 'ollama':
+            return new OllamaProvider({
+                ...(env.AI_MODEL ? { model: env.AI_MODEL } : {}),
+                ...(env.AI_BASE_URL ? { baseUrl: env.AI_BASE_URL } : {}),
+                ...fetchOpt,
+            });
+        case 'openai':
+        case 'openai-compatible':
+            // Any OpenAI Chat Completions endpoint — OpenAI, LiteLLM, OpenRouter,
+            // go4ai, etc. Point AI_BASE_URL at the gateway's `/v1`. Streams by default
+            // (AI_STREAM=false to disable).
+            return new OpenAICompatibleProvider({
+                apiKey: env.AI_API_KEY ?? '',
+                ...(env.AI_MODEL ? { model: env.AI_MODEL } : {}),
+                ...(env.AI_BASE_URL ? { baseUrl: env.AI_BASE_URL } : {}),
+                ...(env.AI_STREAM === 'false' ? { stream: false } : {}),
+                ...fetchOpt,
+            });
+        case 'google':
+            throw new Error(`createProvider: 'google' is not implemented in @basaltkit/ai@0.1. ` +
+                `Available now: 'anthropic', 'ollama', 'openai' (OpenAI-compatible).`);
+        default:
+            throw new Error(`createProvider: unknown AI_PROVIDER='${name}'. Use 'anthropic', 'ollama' or 'openai'.`);
+    }
+}

package/dist/provider/http.d.ts

@@ -0,0 +1,24 @@
+import type { FetchLike } from './types.js';
+export interface RetryOptions {
+    /** Extra attempts after the first (so `2` = up to 3 tries). */
+    retries?: number;
+    /** Base backoff in ms; doubles each attempt. */
+    baseDelayMs?: number;
+}
+/**
+ * Fetch with retry on transient 5xx/429 responses and network errors, using
+ * exponential backoff. Providers hit remote gateways (go4ai, OpenAI, Anthropic)
+ * that occasionally return a spurious 500 — one retry usually clears it.
+ *
+ * Reads the body only on the terminal attempt, so retried responses are simply
+ * discarded.
+ */
+export declare function fetchWithRetry(fetchImpl: FetchLike, url: string, init: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}, options?: RetryOptions): Promise<{
+    ok: boolean;
+    status: number;
+    body: string;
+}>;

package/dist/provider/http.js

@@ -0,0 +1,36 @@
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Transient failures worth retrying: gateway/server errors and rate limits. */
+function isRetryableStatus(status) {
+    return status >= 500 || status === 429;
+}
+/**
+ * Fetch with retry on transient 5xx/429 responses and network errors, using
+ * exponential backoff. Providers hit remote gateways (go4ai, OpenAI, Anthropic)
+ * that occasionally return a spurious 500 — one retry usually clears it.
+ *
+ * Reads the body only on the terminal attempt, so retried responses are simply
+ * discarded.
+ */
+export async function fetchWithRetry(fetchImpl, url, init, options = {}) {
+    const retries = options.retries ?? 2;
+    const baseDelayMs = options.baseDelayMs ?? 300;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const res = await fetchImpl(url, init);
+            if (isRetryableStatus(res.status) && attempt < retries) {
+                await sleep(baseDelayMs * 2 ** attempt);
+                continue;
+            }
+            return { ok: res.ok, status: res.status, body: await res.text() };
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= retries)
+                throw error;
+            await sleep(baseDelayMs * 2 ** attempt);
+        }
+    }
+    // Unreachable: the loop either returns or throws.
+    throw lastError instanceof Error ? lastError : new Error('fetchWithRetry: exhausted retries');
+}

package/dist/provider/ollama.d.ts

@@ -0,0 +1,22 @@
+import { type AIProvider, type FetchLike, type GenerateOptions } from './types.js';
+export interface OllamaProviderOptions {
+    /** Model id, e.g. `'llama3.1'`. */
+    model?: string;
+    /** Ollama base URL. Defaults to the local daemon. */
+    baseUrl?: string;
+    /** Injected fetch. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * Local Ollama provider (`/api/chat`, `stream: false`). Needs no API key, so it's
+ * the zero-cost default for offline development and CI.
+ */
+export declare class OllamaProvider implements AIProvider {
+    readonly name = "ollama";
+    readonly model: string;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: OllamaProviderOptions);
+    generate(options: GenerateOptions): Promise<string>;
+    stream(options: GenerateOptions): AsyncIterable<string>;
+}

package/dist/provider/ollama.js

@@ -0,0 +1,42 @@
+import { fetchWithRetry } from './http.js';
+import { singleChunkStream, } from './types.js';
+const DEFAULT_MODEL = 'llama3.1';
+/**
+ * Local Ollama provider (`/api/chat`, `stream: false`). Needs no API key, so it's
+ * the zero-cost default for offline development and CI.
+ */
+export class OllamaProvider {
+    name = 'ollama';
+    model;
+    baseUrl;
+    fetchImpl;
+    constructor(options = {}) {
+        this.model = options.model ?? DEFAULT_MODEL;
+        this.baseUrl = (options.baseUrl ?? 'http://localhost:11434').replace(/\/$/, '');
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error('OllamaProvider: no fetch available — pass options.fetch');
+        this.fetchImpl = f;
+    }
+    async generate(options) {
+        const { ok, status, body } = await fetchWithRetry(this.fetchImpl, this.baseUrl + '/api/chat', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model: this.model,
+                stream: false,
+                messages: options.messages.map((m) => ({ role: m.role, content: m.content })),
+                ...(options.temperature !== undefined ? { options: { temperature: options.temperature } } : {}),
+            }),
+        });
+        if (!ok)
+            throw new Error(`OllamaProvider: ${status} — ${body.slice(0, 200)}`);
+        const json = JSON.parse(body);
+        if (json.error)
+            throw new Error(`OllamaProvider: ${json.error}`);
+        return json.message?.content ?? '';
+    }
+    stream(options) {
+        return singleChunkStream(() => this.generate(options));
+    }
+}