feat: add AI provider abstraction with OpenAI support

Author: sebuzdugan

TODO.md

@@ -27,10 +27,11 @@
 - ✅ **Day 8:** Assemble AI feature backlog with user stories; prioritise RAG, eval, fine-tuning governance; publish roadmap entries.
 - ✅ **Day 9:** Implement `frai rag index` command, vector store abstraction, and RAG helper modules; cover with CLI tests.
 - ✅ **Day 10:** Scaffold `frai eval` baseline metrics leveraging open-source models; ensure configurable thresholds and reporting.
-- **Day 11:** Draft fine-tuning governance spec (dataset audit, training hooks, bias evals); prototype config schema.
-- **Day 12:** Develop VS Code MCP endpoint + extension scaffold reading data from `frai-core`; document protocol usage.
-- **Day 13:** Author problem-solution playbooks (RAG compliance, LLM agent docs) in `/docs`; tie features to user pain points.
-- **Day 14:** Add opt-in telemetry, gather KPIs (usage of new commands/tests), and produce sprint retrospective summary.
+- ✅ **Day 11:** Implement AI provider abstraction (`frai-core/src/providers`) supporting OpenAI + future adapters with comprehensive test coverage.
+- **Day 12:** Draft fine-tuning governance spec (dataset audit, training hooks, bias evals); prototype config schema.
+- **Day 13:** Develop VS Code MCP endpoint + extension scaffold reading data from `frai-core`; document protocol usage.
+- **Day 14:** Author problem-solution playbooks (RAG compliance, LLM agent docs) in `/docs`; tie features to user pain points.
+- **Day 15:** Add opt-in telemetry, gather KPIs (usage of new commands/tests), and produce sprint retrospective summary.
 
 ## Workstreams (Weeks 3-6)
 

docs/refactor-plan.md

@@ -17,7 +17,12 @@
 - ✅ Extract questionnaire prompts, answer mapping, and validation into `frai-core/src/questionnaire`.
 - ✅ Relocate document templates/builders into `frai-core/src/documents` with override support.
 - ✅ Refactor scanning heuristics into `frai-core/src/scanners` with plugin registry pattern.
-- [ ] Implement AI provider abstraction (`frai-core/src/providers`) supporting OpenAI + future adapters.
+- ✅ Implement AI provider abstraction (`frai-core/src/providers`) supporting OpenAI + future adapters with comprehensive test coverage.
+  - Provider registry system with factory pattern
+  - OpenAI provider with chat completion API
+  - Error handling and response parsing
+  - Full test coverage with mocked fetch
+  - Export integration in main index.js
 
 ### 3. AI Feature Delivery
 - ✅ Assemble AI feature backlog (Day 8) with prioritised user stories (RAG, eval, fine-tune).

packages/frai-core/src/index.js

@@ -5,3 +5,4 @@ export * as Scanners from './scanners/index.js';
 export * as Rag from './rag/index.js';
 
 export * as Eval from './eval/index.js';
+export * as Providers from './providers/index.js';

packages/frai-core/src/providers/constants.js

@@ -0,0 +1,4 @@
+export const PROVIDER_OPENAI = 'openai';
+
+export const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
+export const DEFAULT_OPENAI_CHAT_MODEL = 'gpt-4.1-nano-2025-04-14';

packages/frai-core/src/providers/index.js

@@ -0,0 +1,24 @@
+import { PROVIDER_OPENAI } from './constants.js';
+import { createOpenAIProvider } from './openai.js';
+
+const registry = new Map([[PROVIDER_OPENAI, createOpenAIProvider]]);
+
+export function registerProvider(id, factory) {
+  if (!id || typeof id !== 'string') {
+    throw new Error('Provider id must be a non-empty string');
+  }
+  if (typeof factory !== 'function') {
+    throw new Error('Provider factory must be a function');
+  }
+  registry.set(id, factory);
+}
+
+export function createProvider({ provider = PROVIDER_OPENAI, ...options } = {}) {
+  const factory = registry.get(provider);
+  if (!factory) {
+    throw new Error(`Unknown provider "${provider}"`);
+  }
+  return factory(options);
+}
+
+export { PROVIDER_OPENAI, createOpenAIProvider };

packages/frai-core/src/providers/openai.js

@@ -0,0 +1,127 @@
+import {
+  DEFAULT_OPENAI_BASE_URL,
+  DEFAULT_OPENAI_CHAT_MODEL,
+  PROVIDER_OPENAI
+} from './constants.js';
+
+const ensureFetch = (providedFetch) => {
+  if (typeof providedFetch === 'function') {
+    return providedFetch;
+  }
+  if (typeof globalThis !== 'undefined' && typeof globalThis.fetch === 'function') {
+    return globalThis.fetch.bind(globalThis);
+  }
+  return null;
+};
+
+const buildHeaders = ({ apiKey, organization }) => {
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`
+  };
+  if (organization) {
+    headers['OpenAI-Organization'] = organization;
+  }
+  return headers;
+};
+
+const buildChatPayload = ({
+  messages,
+  model = DEFAULT_OPENAI_CHAT_MODEL,
+  temperature,
+  maxTokens,
+  responseFormat,
+  seed
+}) => {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new Error('messages array is required for chat completion');
+  }
+
+  const payload = {
+    model,
+    messages
+  };
+
+  if (typeof temperature === 'number') {
+    payload.temperature = temperature;
+  }
+
+  if (typeof maxTokens === 'number') {
+    payload.max_tokens = maxTokens;
+  }
+
+  if (responseFormat) {
+    payload.response_format = responseFormat;
+  }
+
+  if (typeof seed === 'number') {
+    payload.seed = seed;
+  }
+
+  return payload;
+};
+
+const parseChatResponse = async (response) => {
+  const json = await response.json();
+  const choice = json?.choices?.[0];
+  const content = choice?.message?.content ?? '';
+
+  return {
+    content,
+    model: json.model ?? null,
+    usage: json.usage ?? null,
+    raw: json
+  };
+};
+
+const parseErrorResponse = async (response) => {
+  try {
+    const payload = await response.json();
+    const message = payload?.error?.message ?? `OpenAI request failed with status ${response.status}`;
+    const error = new Error(message);
+    error.status = response.status;
+    error.payload = payload;
+    return error;
+  } catch (error) {
+    const generic = new Error(`OpenAI request failed with status ${response.status}`);
+    generic.status = response.status;
+    return generic;
+  }
+};
+
+export function createOpenAIProvider({
+  apiKey,
+  baseUrl = DEFAULT_OPENAI_BASE_URL,
+  organization,
+  fetch: providedFetch
+} = {}) {
+  if (!apiKey) {
+    throw new Error('OpenAI provider requires an API key');
+  }
+
+  const fetchFn = ensureFetch(providedFetch);
+  if (!fetchFn) {
+    throw new Error('OpenAI provider requires a fetch implementation');
+  }
+
+  const headers = buildHeaders({ apiKey, organization });
+
+  return {
+    id: PROVIDER_OPENAI,
+    async chatCompletion(options) {
+      const payload = buildChatPayload(options ?? {});
+      const response = await fetchFn(`${baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+        signal: options?.signal
+      });
+
+      if (!response.ok) {
+        throw await parseErrorResponse(response);
+      }
+
+      return parseChatResponse(response);
+    }
+  };
+}

packages/frai-core/src/providers/openai.test.js

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { DEFAULT_OPENAI_BASE_URL, PROVIDER_OPENAI } from './constants.js';
+import { createOpenAIProvider } from './openai.js';
+import { createProvider } from './index.js';
+
+const buildFetchMock = (responsePayload, options = {}) => {
+  const ok = options.ok ?? true;
+  return vi.fn(async () => ({
+    ok,
+    status: options.status ?? (ok ? 200 : 400),
+    async json() {
+      return responsePayload;
+    }
+  }));
+};
+
+describe('OpenAI provider', () => {
+  it('requires an API key', () => {
+    expect(() => createOpenAIProvider()).toThrow(/api key/i);
+  });
+
+  it('requires a fetch implementation when global fetch is unavailable', () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // eslint-disable-next-line no-global-assign
+      globalThis.fetch = undefined;
+      expect(() => createOpenAIProvider({ apiKey: 'test-key' })).toThrow(/fetch/i);
+    } finally {
+      // eslint-disable-next-line no-global-assign
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('calls the chat completions endpoint with provided payload', async () => {
+    const fetch = buildFetchMock({
+      id: 'chatcmpl-123',
+      model: 'gpt-test',
+      choices: [
+        {
+          index: 0,
+          message: { role: 'assistant', content: 'Hello world' }
+        }
+      ],
+      usage: { total_tokens: 10 }
+    });
+
+    const provider = createOpenAIProvider({
+      apiKey: 'key',
+      fetch
+    });
+
+    const result = await provider.chatCompletion({
+      messages: [{ role: 'user', content: 'Hi' }],
+      model: 'gpt-test',
+      temperature: 0.2,
+      maxTokens: 100
+    });
+
+    expect(fetch).toHaveBeenCalledTimes(1);
+    const [url, request] = fetch.mock.calls[0];
+    expect(url).toBe(`${DEFAULT_OPENAI_BASE_URL}/chat/completions`);
+    const body = JSON.parse(request.body);
+    expect(body.model).toBe('gpt-test');
+    expect(body.temperature).toBe(0.2);
+    expect(body.max_tokens).toBe(100);
+
+    expect(result.content).toBe('Hello world');
+    expect(result.model).toBe('gpt-test');
+    expect(result.usage).toEqual({ total_tokens: 10 });
+  });
+
+  it('surfaces API errors with response payload details', async () => {
+    const errorPayload = {
+      error: {
+        message: 'Invalid request'
+      }
+    };
+    const fetch = buildFetchMock(errorPayload, { ok: false, status: 400 });
+
+    const provider = createOpenAIProvider({
+      apiKey: 'key',
+      fetch
+    });
+
+    await expect(
+      provider.chatCompletion({ messages: [{ role: 'user', content: 'hi' }] })
+    ).rejects.toMatchObject({
+      message: 'Invalid request',
+      status: 400,
+      payload: errorPayload
+    });
+  });
+});
+
+describe('providers registry', () => {
+  it('creates providers via registry defaults', () => {
+    const fetch = buildFetchMock({
+      choices: [{ message: { content: 'ok' } }]
+    });
+
+    const provider = createProvider({
+      apiKey: 'key',
+      fetch
+    });
+
+    expect(provider.id).toBe(PROVIDER_OPENAI);
+  });
+
+  it('throws for unknown providers', () => {
+    expect(() =>
+      createProvider({ provider: 'unknown', apiKey: 'key' })
+    ).toThrow(/unknown provider/i);
+  });
+});