mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-09 14:34:04 +00:00
062f88e3e3
* refactor: extract reusable AI runtime package * refactor: complete AI provider relocation * refactor: keep llm core internal * refactor(ai): make @openclaw/ai self-contained with host policy ports Move pure transport helpers (tool projections, strict-schema normalization, prompt-cache boundary, stream guards, anthropic/openai compat, request activity) from src into packages/ai; move utf16-slice into normalization-core. Inject host policy (guarded fetch, redaction, strict-tool defaults, diagnostics logging) through AiTransportHost with inert library defaults installed by src/llm/stream.ts. Narrow the public barrel to instance-scoped createApiRegistry/createLlmRuntime; the process-default runtime moves behind internal/ and registerBuiltInApiProviders takes an explicit registry. Delete the src/llm/api-registry re-export facade. * fix(ai): teach node, jiti, and vite resolvers the @openclaw/ai and utf16-slice subpaths The workspace alias tables in root-alias.cjs, plugin-sdk-native-resolver, sdk-alias, the shared vitest config, and the Control UI vite config only knew @openclaw/llm-core; Node-side plugin loading resolved @openclaw/ai through the pnpm symlink to the unbuilt dist (checks-node-compact CI failures), and the Control UI build broke on the new normalization-core/utf16-slice subpath. * chore(ui): drop leftover service-worker debug logging * build(release): ship @openclaw/ai with its own shrinkwrap and honest dependency set packages/ai declares only its six real runtime deps (kysely, chalk, json5, tslog, zod, fs-safe, and proxyline were never imported); orphaned root deps removed. generate-npm-shrinkwrap now treats publishable packages/* like publishable plugins so the AI tarball pins its transitive tree even though workspace deps are omitted from the root shrinkwrap. knip learns the package entry points; the tsdown dts neverBundle option moves to its documented deps.dts home; the README documents the no-semver internal/* contract and host ports. * docs(ai): add minimal external-consumer example app examples/ai-chat consumes only the public @openclaw/ai surface (built dist via the workspace link): isolated runtime, built-in provider registration, one streamed completion. Supports Anthropic/OpenAI via env keys and a keyless local Ollama target; live-verified against Ollama. * docs(ai): document the @openclaw/ai package and workspace shrinkwrap boundary * chore(check): include examples/ in duplicate-scan targets * fix: emit normalization package subpaths * fix: complete AI package boundary artifacts * fix: align AI package boundary contracts * fix(ci): stabilize package release contracts * test: align documentation contract checks * test: keep cron docs guard aligned * test: align restored docs contract guards * test: follow upstream docs contracts * docs: drop superseded talk wording
3.7 KiB
3.7 KiB
summary, title, read_when
| summary | title | read_when | |||
|---|---|---|---|---|---|
| The @openclaw/ai npm package: reusable model transports, isolated runtimes, and host policy ports | @openclaw/ai package |
|
@openclaw/ai is the publishable library form of OpenClaw's model execution
layer: provider-neutral message/tool/stream contracts, validation, diagnostics,
event streams, an isolated runtime registry, and lazy adapters for the eight
built-in API families (Anthropic Messages, OpenAI Completions, OpenAI
Responses, Azure OpenAI Responses, ChatGPT/Codex Responses, Google Generative
AI, Google Vertex, Mistral Conversations).
It publishes alongside the root openclaw package on every release, pinned to
the same version, with its own npm-shrinkwrap.json so its transitive
dependency tree is locked at install time. Installing openclaw installs the
matching @openclaw/ai automatically; library consumers can depend on it
directly without any OpenClaw application code.
Quick start
import { createLlmRuntime } from "@openclaw/ai";
import { registerBuiltInApiProviders } from "@openclaw/ai/providers";
const runtime = createLlmRuntime();
registerBuiltInApiProviders(runtime.registry);
const stream = runtime.streamSimple(model, { messages }, { apiKey });
for await (const event of stream) {
if (event.type === "text_delta") process.stdout.write(event.delta);
}
const result = await stream.result();
A runnable version lives in the repository at examples/ai-chat.
Design contract
- Instance-scoped by default. Importing the package registers nothing
globally.
createApiRegistry()/createLlmRuntime()return isolated instances;registerBuiltInApiProviders(registry)opts one registry into the built-in transports. Provider SDK modules load lazily on first use. - Host policy is injected, not bundled. Request fetch guarding (for
example SSRF policy), secret redaction of tool-result replay text, OpenAI
strict-tool defaults, and diagnostics logging are
AiTransportHostports configured withconfigureAiTransportHost. The library defaults are inert; OpenClaw installs its real implementations in its stream facade. - One event-stream identity.
@openclaw/ai/event-streamis the canonicalEventStreamconstructor shared by OpenClaw core, agent-core, and external consumers. internal/*subpaths are not API. They exist for the OpenClaw application itself and carry no semver guarantee.- Provider ids, credentials, model catalogs, retries, and failover remain
application concerns. OpenClaw layers those around this package; a library
consumer supplies a
Modelobject and options directly.
Subpath exports
| Subpath | Contents |
|---|---|
. |
Contracts, createApiRegistry, createLlmRuntime, configureAiTransportHost |
./providers |
registerBuiltInApiProviders, resetApiProviders |
./types |
Model/message/tool/stream types |
./validation |
Tool argument validation |
./diagnostics |
Diagnostics contracts |
./event-stream |
Shared EventStream implementation |
./internal/* |
OpenClaw-internal, no semver guarantee |