Quick Start

AI Core is consumed as released runtime artifacts and tools. SDK users should not need the source tree to run packages, call models, or use local speech/LLM support.

Pick A Boundary

• Use Language Bindings when the host loads the AI Core shared library.
• Use Process Host CLI when the host wants a long-lived ai-core subprocess worker.
• Use the Rust SDK artifact when the host embeds AI Core directly.
• Use AI Packages when you need to build or sign .aip plugin and pipeline packages.

First Runtime Call

1. Start from an AI Core artifact that matches your platform, version, and trust mode.
2. Apply model, plugin, secret-reference, speech, and local LLM config.
3. Load license material if you use normal marketplace packages.
4. Install package bytes with ai_core_install_package_bytes or the equivalent process/Rust boundary.
5. Start a pipeline, resume a checkpoint, run a known Wasm action, or call a configured model directly.
6. Store pipeline state, step outputs, user decisions, and product records in the host.

What The Host Stores

Store these values outside AI Core:

• model endpoints and selected routing/default model slots;
• explicit local .gguf and Whisper model paths;
• plugin model-slot bindings;
• public plugin config and secret references;
• actual secret values in Keychain, Keystore, KMS, Vault, Kubernetes secrets, or another host-owned store;
• package bytes or package provenance;
• pipeline state, completed step outputs, and user approvals;
• license material and private KEM keys for normal marketplace packages.

AI Core keeps live runtime state in memory. It does not own durable product storage.

Common Operations

Install And Run A Pipeline

1. Receive or build a .aip package that matches requirements.core for this runtime version.
2. Apply model and plugin config.
3. Load license material if the package is an encrypted marketplace package.
4. Install package bytes.
5. Start the pipeline with run_id, task_id, plugin_id, and user_text.
6. If AI Core returns a checkpoint, ask the user for the missing data or approval and resume with state, previous_outputs, and control.

Call A Model Directly

1. Configure a model endpoint with a stable model_id.
2. Apply config.
3. Call ai_core_model_chat_json or the matching process/Rust API with that model_id, messages, response format, and optional token limit.

Run A Known Wasm Action

1. Install a Wasm plugin package.
2. Call the action by plugin_id and fully qualified action_id.
3. Process returned action output, events, and queued host calls.

Local Capabilities

Local speech-to-text requires a runtime artifact that includes the native Whisper provider and a compatible ggml-large-v3-turbo.bin model file.

Local LLM requires a runtime artifact that includes the native local LLM provider and an explicit .gguf model path. AI Core does not scan model directories for the host.

Error Handling

FFI functions return a JSON envelope. Treat ok: false as a failed call and use error.code plus error.message for host logs and UI diagnostics. Do not assume partial output is valid after a failed call.