Genesis Foundation AI
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 anapiKeyin 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()andgetAIProvider()return a no-op providerresolveAIConfig()returnsnull- 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
serverEndpointto your proxy route. The transport posts the Responses request body there; the proxy adds the API key, callshttps://api.openai.com/v1/responsesand 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
apiKeyand 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_SUPPORTEDandREQUEST_TOO_LARGEare configuration errors. The request is not retried, andAIServiceErroris thrown.VENDOR_UNREACHABLEis retried like its status would be, andAIServiceErroris 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', anERRORlist), or an empty body, is the app's router refusing the request before the proxy runs, with no session or without the right. It throwsAIServiceErrorwithSIGNED_OUTorACCESS_DENIED, fromAI_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
codeand an empty or non-JSON body is a size cap in front of the proxy. It throwsAIServiceErrorwithREQUEST_TOO_LARGE, and is not retried. AIServiceError.messageholds the vendor, status and code only. The proxy's ownerrortext is ondetail, 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:
- Enroll your domain in the Prompt API origin trial.
- Add the origin trial token (meta tag or header) to your app.
- 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→ Enabledchrome://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