# AIRuntime — getting started

AIRuntime provides C# conversation and tool orchestration plus Unity Editor chat and Kanban agent tools.

**External services:** hosted inference requires your own provider account, credentials and any applicable usage payments. Provider terms, availability and model capabilities apply. The included offline example needs no account, model or network connection. AIRuntime does not include model weights or inference hosting.

## Install

1. Use Unity 2022.3.30f1 for the initial release candidate. See the release validation report for versions actually tested; other platforms and Unity versions are not yet claimed.
2. In Window > Package Manager, install by name `com.unity.nuget.newtonsoft-json` version `3.2.2`, `com.unity.test-framework` version `1.1.33`, and Unity UI (`com.unity.ugui` version `1.0.0`). The Editor tools reference the Test Runner assembly, so Test Framework is required even if you do not run the included tests. Unity UI is used by the component regression tests. Retain Unity's standard built-in modules, including UnityWebRequest, IMGUI, UI, UIElements, physics, physics2d, audio, animation, image conversion, screen capture and JSON serialization.
3. Import the AIRuntime package. It installs under `Assets/AIRuntime`.
4. Wait for compilation, then select **Window > AIRuntime > Examples > Run Offline Tool Loop**.
5. The Console should report `AIRuntime offline example PASS` and one tool call. This exercises a scripted provider, a real read-file capability, dispatch and a final response. It does not test live inference.

For a scene-based example, open `Examples/OfflineToolLoop.unity`, enter Play Mode and click **Run offline demo**. The scene displays the result with IMGUI. Its component source is `Runtime/Examples/OfflineToolLoop.cs`.

## Connect a provider

Open **Window > AIRuntime > Chat Console**. Choose a provider, enter its endpoint, model and credentials where required, and send a short message with tools disabled first. Enable only the tools needed for your next request. Hosted adapters include OpenAI, OpenRouter, Nous Portal and NVIDIA Developer. Ollama is an optional external service that you install and operate separately. Adapter inclusion does not guarantee every model supports tool calls or every provider-specific option.

For a runtime integration, read `Editor/OfflineExample.cs`: create `AIRuntime.Runtime.AIRuntime` with a workspace root, register capabilities, select a provider with `UseProvider`, then await `RunAsync`. The example is Editor-only; production applications own their UI, cancellation, credentials and deployment configuration. Never ship a provider secret in source, scene data, Resources or a client build; use a backend under your control for secret-bearing hosted access.

## Editor automation and Kanban

Use the windows under **Window > AIRuntime** to configure agent profiles, view activity and manage the Kanban workflow. Start on a backed-up or version-controlled test project. Agents with write tools can change scripts, scenes and assets. Inspect permissions and tool selection before running them. A completed card or automated review is not proof that a game works; inspect the result and run its tests.

Detailed guides are in `Documentation/Reference`, including architecture, graph, scheduling, memory, fallback and command-line operation. Some reference examples use illustrative `Assets/Runtime` paths; package files are under `Assets/AIRuntime/Runtime`. The developer documentation atlas and generated game are not included.

## Data, credentials and limitations

Read `Documentation/DATA_AND_LIMITATIONS.md` before using project tools with a hosted provider. The package contains no provider key. Saved agent profiles can contain plaintext keys, so do not commit, distribute or import them as build assets.

## Troubleshooting

- Missing Newtonsoft or TestRunner assembly: install the dependencies above and allow recompilation.
- Authentication or model errors: verify your own endpoint, model access and provider account. Repeated retries do not repair invalid credentials.
- Tool calls fail: check capability registration, enabled tools, arguments and permission settings.
- Provider cooldown or paused Kanban card: inspect its failure details and configured provider before resuming.
- Offline example fails: inspect the first Console error. It should not contact any hosted service.

Support: Voltron — mjdust.defender@gmail.com. Include the Unity version, operating system, reproduction steps and redacted Console error. Remove keys, prompts and private project contents from reports.
