@genesislcap/foundation-ai

中文文档
15.96.2发布于 2026/11/16SEE LICENSE IN license.txtTypeScriptCommonJS近 30 天下载 4万

Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities

原始使用文档
文档目录17 节
  1. API Docs
  2. Feature flag
  3. Installation
  4. Configuration
  5. 1. Resolve config (Chrome-first or OpenAI)
  6. 2. Register provider in DI
  7. 3. Use in components
  8. OpenAI
  9. Error codes a proxy can send
  10. Manual provider selection
  11. Chrome built-in AI (Prompt API / Gemini Nano)
  12. Production (deployed apps)
  13. Local development (localhost)
  14. Hardware and system requirements
  15. Speech-to-text
  16. License
  17. Licensed components

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

版本与发布记录

@genesislcap/foundation-ai 共发布 852 个版本,首次发布于 2026/02/27;过去 12 个月发布了 852 个版本。

版本发布日期距今
15.96.2latest2026/11/16今天
15.96.12026/11/16今天
15.96.0-GENC-1665.32026/11/142 天前
15.96.02026/11/142 天前
15.95.2-GENC-1665.22026/11/132 天前
15.95.22026/11/133 天前

其他发布通道:TPD-4881 → 14.401.0-TPD-4881.2,hide-status-pill → 14.401.3-hide-status-pill.4,ai-assistant → 14.403.0-ai-assistant.7,FUI-2491 → 14.407.0-FUI-2491.1,PA-1853 → 14.408.0-PA-1853.1,icon-renderer → 14.408.0-icon-renderer.4。

关于 @genesislcap/foundation-ai 的常见问题

@genesislcap/foundation-ai 是什么?

Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities

如何安装 @genesislcap/foundation-ai?

在项目目录运行 npm install @genesislcap/foundation-ai,或使用 pnpm add / yarn add / bun add。

@genesislcap/foundation-ai 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genesislcap/foundation-ai 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@genesislcap/foundation-ai 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@genesislcap/foundation-ai 可以商用吗?

@genesislcap/foundation-ai 使用 SEE LICENSE IN license.txt 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@genesislcap/foundation-ai 的下载量有多少?

根据 npm 官方下载统计,@genesislcap/foundation-ai 在 2026/10/16 – 2026/11/14 这 30 天内被下载 39,641 次,日均约 1,321 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genesislcap/foundation-ai 还在维护吗?

最新版本 15.96.2 发布于 2026/11/16(今天);至今共发布 852 个版本,其中过去 12 个月发布了 852 个;首次发布于 2026/02/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。