Runtime Contracts

AI Core exposes the same runtime concepts through FFI, the Rust SDK, and the process-host binary. SDK users do not need source-level Rust structs to understand the contract: the host applies config, installs packages, starts or resumes work, and stores durable state outside AI Core.

Что принадлежит AI Core

AI Core owns live execution state:

• model endpoint registration and dispatch by model_id;
• routing/default model selection;
• plugin metadata, package install, and package reload checks;
• Wasm action execution;
• pipeline start/resume checkpoints;
• runtime events for transcription, routing, model calls, tools, plugins, and pipeline progress;
• in-memory license material while a normal marketplace runtime is running.

AI Core не владеет users, accounts, billing, application databases, queues, secret stores, long-term pipeline output storage или UI settings.

Host-owned config

Host configures runtime state with a JSON-equivalent snapshot:

{
  "models": [
    {
      "kind": "openai_compatible",
      "url": "http://127.0.0.1:1234/v1",
      "model_id": "qwen/qwen3-1.7b",
      "token_ref": "secret:models.routing_local.token",
      "enabled": true
    },
    {
      "kind": "openai",
      "url": "https://api.openai.com/v1",
      "model_id": "gpt-4.1-mini",
      "token_ref": "secret:models.default_openai.token",
      "enabled": true,
      "local": null
    },
    {
      "kind": "built_in_local",
      "model_id": "qwen3-1.7b",
      "enabled": true,
      "token_ref": null,
      "local": {
        "path": "/models/llm/qwen3-1.7b.gguf",
        "context_tokens": 4096,
        "backend": "cpu",
        "max_concurrent_requests": 1,
        "max_pending_requests": 0
      }
    }
  ],
  "local_llm": {
    "backend": "metal"
  },
  "model_selection": {
    "routing": "qwen/qwen3-1.7b",
    "default": "gpt-4.1-mini"
  },
  "plugin_model_bindings": [
    {
      "plugin_id": "example_pipeline",
      "slot_id": "draft",
      "model_id": "qwen3-1.7b"
    }
  ],
  "plugins": [
    {
      "plugin_id": "example_pipeline",
      "public": {
        "language": "en"
      },
      "secrets": {
        "api_token": "secret:plugins.example_pipeline.api_token"
      }
    }
  ],
  "speech": {
    "whisper": {
      "model_path": "/models/whisper/ggml-large-v3-turbo.bin",
      "coreml_encoder_path": null,
      "language": "auto"
    }
  }
}

Supported model kinds are openai, openai_compatible, claude, and built_in_local. Built-in local kind требует runtime artifact с native local LLM support и explicit .gguf path.

Local LLM backend preference is host-owned config. local_llm.backend applies to all built_in_local models and defaults to auto. A model can set local.backend to override the global preference for that one .gguf file, which is useful when a small router fits on GPU but a larger default model should start on CPU. Supported values are auto, cpu, metal, cuda and vulkan. Preference is not a hard guarantee: AI Core tries the preferred backend first, then falls back to automatic backend selection when the native provider reports a backend-level failure.

Runtime artifacts могут выходить в разных вариантах сборки. В одних есть и local speech-to-text, и local model execution, в других отсутствует одна или обе возможности. Актуальную матрицу артефактов смотрите на странице загрузки ядра на сайте.

Каждая non-local model может иметь свой token_ref. AI Core хранит только ссылку; host разрешает её через secret store и передает provider-у сырой токен в момент вызова. OpenAI и OpenAI-compatible models используют JSON-схему OpenAI chat-completions и Authorization: Bearer .... Claude использует JSON схему Anthropic messages и x-api-key.

Secret values are references such as secret:plugins.example_pipeline.api_token. Host resolves these references through Keychain, Keystore, KMS, Vault, Kubernetes secrets, environment injection, or another host-owned secret store.

В core runtime есть одна общая routing model и одна default model. Plugin packages могут объявлять generation model_slots, а runtime заполняет недостающие plugin_model_bindings из fallback, если он указывает на core.default или конкретную model. Routing не является plugin slot-ом.

Package activation

AI Core installs .aip packages after validating:

• package format and manifest file hashes;
• plugin id and version compatibility;
• requirements.core;
• plugin API version;
• Wasm entrypoint and ABI version for Wasm packages;
• Marketplace approval and license material in normal marketplace runtimes.

Если install не удался, предыдущая активная версия package остаётся активной. Installed package files хранятся в памяти для текущей runtime session, чтобы package execution и pipeline steps могли читать bundled skills, schemas и pipeline.json.

No-marketplace runtime artifacts - это отдельный local, enterprise или white-label режим. Они принимают packages, собранные для no-marketplace distribution, включая plaintext unsigned packages или developer-signed packages, собранные с aip-pack-no-marketplace.

Pipeline state

Pipeline calls exchange a serializable cursor:

{
  "schema": "ai_core.pipeline_state.v1",
  "run_id": "run-1",
  "task_id": "task-1",
  "plugin_id": "example_pipeline",
  "status": "waiting_for_approval",
  "next_step_index": 1
}

Host stores this state and any completed step outputs. On resume, host passes state, previous_outputs, new user_text, and a control value:

• "continue" to advance;
• "retry" повторно запускает завершённый шаг с user_text, который передал host. В prompt всё так же попадают skill шага, output schema и предыдущие outputs.

Если package pipeline.json declares a top-level input contract and start request is missing required values, AI Core can return a checkpoint before step 0. Host asks user for missing data and resumes with the same pipeline state.

Events

Runtime events are for host logging, UI progress, and diagnostics. Common event areas include transcription, router decisions, model request/response, package install, plugin action execution, pipeline checkpoints, and Wasm progress.

Language bindings should expose events as host-language objects or JSON arrays instead of leaking internal Rust event types.

Version rules

Packages declare runtime compatibility in requirements.core. AI Core parses that semver expression before install/reload activation. Ship runtime artifacts and packages from compatible release lines, and treat package/runtime mode as part of the artifact contract.