npm.io
15.101.0 • Published 2d ago

@genesislcap/foundation-ai

Licence
SEE LICENSE IN license.txt
Version
15.101.0
Deps
3
Size
1.6 MB
Vulns
0
Weekly
0

Genesis Foundation AI

lerna TypeScript

API Docs

Provider-agnostic AI configuration and shared utilities. Configure once at app bootstrap; use across components via dependency injection.

Beta – not for production
This package is in beta. Do not use in production. API surface and behaviour may change. It is intended for evaluation and development only.

Supported providers:

  • OpenAI – the Responses API, through your server proxy (serverEndpoint) or directly with an apiKey in trusted contexts. See OpenAI.
  • Chrome built-in AI – Prompt API / Gemini Nano (no API key; Chrome 138+)

Each provider exposes capabilities such as interpretCriteria (natural language to structured criteria). Future capabilities (e.g. summarization) will be added as optional methods on the same interface.


Feature flag

AI features are disabled by default. Enable them via URL parameter or environment variable:

URL parameter — append ?feature.ai to any URL (useful for testing without rebuilding):

https://your-app.com/?feature.ai

Environment variable — set GENX_ENABLE_AI=true in your app's .env file to enable permanently without a URL parameter:

GENX_ENABLE_AI=true

When the flag is off:

  • createAIProvider() and getAIProvider() return a no-op provider
  • resolveAIConfig() returns null
  • AI components (e.g. *-ai-criteria-search, *-ai-indicator) do not render

You can check the flag programmatically:

import { isAIFeatureEnabled, AI_FEATURE_FLAG } from '@genesislcap/foundation-ai';

if (isAIFeatureEnabled()) {
  // AI features are enabled
}

Installation

Add @genesislcap/foundation-ai as a dependency. Run npm run bootstrap after changing dependencies.

{
  "dependencies": {
    "@genesislcap/foundation-ai": "latest"
  }
}

Configuration

1. Resolve config (Chrome-first or OpenAI)

Use resolveAIConfig to prefer Chrome when available, with a cloud provider as fallback. The cloud config it returns carries no endpoint, so add your proxy's serverEndpoint before creating the provider:

import { createAIProvider, resolveAIConfig, AIProvider } from '@genesislcap/foundation-ai';

const resolved = await resolveAIConfig({
  provider: 'openai', // default model: gpt-6-luna
  preferChrome: true,
});
const aiConfig =
  resolved && 'providerType' in resolved && resolved.providerType === 'openai'
    ? { ...resolved, serverEndpoint: '/gwf/ai-service/api/openai/chat' }
    : resolved;
2. Register provider in DI

Register the provider at app bootstrap (e.g. in main.ts):

import { Registration } from '@microsoft/fast-foundation';

this.container.register(
  Registration.instance(AIProvider, createAIProvider(aiConfig)),
);

Configure once; all components using getAIProvider() receive the same instance.

3. Use in components
import { getAIProvider } from '@genesislcap/foundation-ai';

const aiProvider = getAIProvider();
if (aiProvider?.interpretCriteria) {
  const result = await aiProvider.interpretCriteria(input, { fields: fieldMetadata });
}

OpenAI

OpenAIAIConfig (providerType: 'openai') builds an OpenAIProvider on OpenAITransport: criteria, prompt and chat, on the Responses API. Supported models are SUPPORTED_OPENAI_MODEL_IDS; the default is gpt-6-luna.

  • Server proxy (recommended): set serverEndpoint to your proxy route. The transport posts the Responses request body there; the proxy adds the API key, calls https://api.openai.com/v1/responses and returns the response. The key stays on the server. There is no default endpoint. Genesis Create's ai-service mounts one at /api/openai/chat (behind the gateway, /gwf/ai-service/api/openai/chat).
  • Direct: set apiKey and the transport calls OpenAI itself. Only use this in trusted contexts, since the key is in the client.

With neither serverEndpoint nor apiKey, a request throws.

Error codes a proxy can send

The Anthropic, Gemini and OpenAI transports read a code from a proxy's JSON error body, { "code": "…", "error": "…" }, and act on it whatever the status:

  • NO_API_KEY, BAD_API_KEY, KEY_UNREADABLE, MODEL_NOT_ALLOWED, BAD_REQUEST, FALLBACKS_NOT_SUPPORTED and REQUEST_TOO_LARGE are configuration errors. The request is not retried, and AIServiceError is thrown.
  • VENDOR_UNREACHABLE is retried like its status would be, and AIServiceError is thrown if it still fails.
  • Any other code is handled by its status, as before.
  • A 401 or 403 carrying the Genesis router's NACK (MESSAGE_TYPE: 'MSG_NACK', an ERROR list), or an empty body, is the app's router refusing the request before the proxy runs, with no session or without the right. It throws AIServiceError with SIGNED_OUT or ACCESS_DENIED, from AI_SERVICE_ACCESS_REFUSALS, which are not codes a proxy sends. Any other code-less 401 or 403 is handled by its status.
  • A 413 with no code and an empty or non-JSON body is a size cap in front of the proxy. It throws AIServiceError with REQUEST_TOO_LARGE, and is not retried.
  • AIServiceError.message holds the vendor, status and code only. The proxy's own error text is on detail, and is logged to the console.

AI_SERVICE_ERROR_CODES lists them, and DEFAULT_AI_SERVICE_ERROR_MESSAGES has what the assistant tells the user for each. The error text is for the console only. A proxy should use these constants rather than restate them.


Manual provider selection

To force a specific provider instead of using resolveAIConfig:

// OpenAI through your server proxy
Registration.instance(AIProvider, createAIProvider({
  providerType: 'openai',
  model: 'gpt-6-luna',
  serverEndpoint: '/gwf/ai-service/api/openai/chat',
}));

// Chrome only (when available)
Registration.instance(AIProvider, createAIProvider({
  providerType: 'chrome',
}));

Chrome built-in AI (Prompt API / Gemini Nano)

The Chrome provider uses the Prompt API with Gemini Nano. It runs on-device; no API key and no data is sent to external services.

Production (deployed apps)

Chrome built-in AI is in an origin trial. For production domains, users do not need to enable any flags:

  1. Enroll your domain in the Prompt API origin trial.
  2. Add the origin trial token (meta tag or header) to your app.
  3. The model download is triggered when your app calls LanguageModel.create() from a user gesture (e.g. the AI indicator "Install model" button).
Local development (localhost)

For testing on localhost, enable these Chrome flags:

  • chrome://flags/#optimization-guide-on-device-model → Enabled
  • chrome://flags/#prompt-api-for-gemini-nano → Enabled

Restart Chrome after changing flags.

Hardware and system requirements
  • OS: Windows 10/11, macOS 13+, Linux, or ChromeOS (Chromebook Plus)
  • Storage: At least 22 GB free (for model download)
  • GPU: >4 GB VRAM, or CPU: 16 GB RAM and 4+ cores
  • Network: Unmetered connection for initial model download only; inference runs offline

See Chrome's Prompt API docs for full requirements.


Speech-to-text

The package includes Web Speech API utilities for voice input:

import { isSpeechRecognitionAvailable, startSpeechRecognition } from '@genesislcap/foundation-ai';

if (isSpeechRecognitionAvailable()) {
  const stop = startSpeechRecognition(
    (transcript, isFinal) => { /* handle transcript */ },
    () => { /* on error */ },
  );
  // Call stop() to end recording
}

License

This project provides front-end dependencies and uses licensed components. Licenses are required during development. Contact Genesis Global for details.

Licensed components

Genesis low-code platform