# How to Integrate AI Models in HolaOS Packages: A Complete Code Guide

> Discover how to integrate AI models in HolaOS packages with this complete code guide. Explore examples in runtime harnesses and request files for seamless integration.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Yes, HolaOS provides a modular model-routing layer with complete AI integration examples in [`runtime/harnesses/src/model-routing.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/model-routing.ts), [`runtime/harness-host/src/pi.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi.ts), and [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts).**

HolaOS ships with a production-ready **model-routing layer** that handles provider discovery, endpoint selection, and authentication for any AI model. This article breaks down the exact integration points, file paths, and working code examples you need to start integrating AI models into your HolaOS packages today.

## The HolaOS Model Routing Pipeline

The integration flow consists of five sequential steps, each implemented in specific source files:

1. **Model catalog lookup** – `runtimeConfigModelCatalog()` loads provider configurations from a JSON catalog
2. **API selection** – `resolveHarnessModelApi()` chooses the correct endpoint (OpenAI completions, OpenAI responses, Gemini, or Anthropic)
3. **Profile construction** – `resolveHarnessModelProfile()` builds the final executable configuration
4. **HTTP request execution** – `runtime-client` sends authenticated requests
5. **Harness execution** – The *Pi* harness forwards calls to model endpoints

## Core Integration Files

### model-routing.ts: Provider and API Selection

Located at [`runtime/harnesses/src/model-routing.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/model-routing.ts), this file contains the three main functions that power AI model integration.

#### Loading the Model Catalog

The `runtimeConfigModelCatalog()` function (lines 66-85) reads provider configurations from a JSON file path specified in `HOLABOSS_RUNTIME_CONFIG_PATH`:

```typescript
import { runtimeConfigModelCatalog } from "@/runtime/harnesses/src/model-routing";

// Returns a map of providers → model entries
const catalog = runtimeConfigModelCatalog();

```

#### Selecting the Right API Endpoint

The `resolveHarnessModelApi()` function (lines 300-313) implements provider-specific routing logic. It handles special cases like routing GPT-5 models to the OpenAI responses endpoint:

```typescript
// Internal logic pseudocode from source:
// - "openai" + "gpt-5" → "openai-responses"
// - "gemini_direct" → Google Gemini endpoint
// - "anthropic" → Anthropic Claude endpoint

```

#### Building the Resolved Profile

The `resolveHarnessModelProfile()` function (lines 815-868) constructs a `HarnessResolvedModelProfile` containing:

- **base URL** for the selected endpoint
- **auth-header flag** indicating whether to inject `Authorization`
- **compatible OpenAI options** for non-OpenAI providers
- **budget and cost** data for usage tracking
- **input modalities** (text, image, or both)

### pi.ts: High-Level Harness Entry Point

Located at [`runtime/harness-host/src/pi.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi.ts) (lines 81-96), the *Pi* harness provides the UI-facing integration point. It wraps the routing profile and handles end-user model calls.

### request.ts: HTTP Client with Auth Handling

Located at [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts), this module sends requests using the resolved profile. It automatically injects `Authorization` headers when `profile.authHeader` is true.

## Complete AI Model Integration Examples

### Example 1: Basic Routing Request

Build a `HarnessModelRoutingRequest` and resolve it to a complete profile:

```typescript
import {
  resolveHarnessModelProfile,
  runtimeConfigModelCatalog,
} from "@/runtime/harnesses/src/model-routing";

const request = {
  provider_id: "openai",                      // Provider identifier
  model_id: "openai/gpt-5.4",                 // Model name (will be normalized to "gpt-5.4")
  thinking_value: "high",                     // Optional reasoning level: "off", "minimal", "low", "medium", "high", "xhigh"
  model_client: {
    model_proxy_provider: "openai_compatible",
    api_key: "sk-YOUR-KEY-HERE",
    base_url: "https://api.openai.com/v1",
    default_headers: { "X-Custom-Header": "value" },
  },
};

const profile = resolveHarnessModelProfile(request, {
  modelCatalog: runtimeConfigModelCatalog(),
});

// profile now contains:
// - api: "openai-responses" | "openai-completions" | "gemini" | "anthropic"
// - baseUrl: resolved endpoint URL
// - headers: merged custom + auth headers
// - reasoning: { effort: "high" } (derived from thinking_value)
// - modalities: ["text", "image"] or ["text"]

```

### Example 2: Direct HTTP Call with Runtime Client

Use the resolved profile to send authenticated requests:

```typescript
import { makeRequest } from "@/packages/runtime-client/src/request";

async function callModel() {
  const response = await makeRequest({
    url: `${profile.baseUrl}/chat/completions`,
    method: "POST",
    headers: profile.headers,                 // Includes Authorization when profile.authHeader is true
    body: {
      model: request.model_id,
      messages: [{ role: "user", content: "Explain quantum entanglement." }],
      // Reasoning parameters injected automatically if profile.reasoning is set
    },
  });

  return response;
}

```

### Example 3: Using the Pi Harness (Recommended for UI Integration)

The *Pi* harness simplifies integration for UI and CLI applications:

```typescript
import { resolvePiModelProfile } from "@/runtime/harness-host/src/pi";

async function runInPi() {
  const piProfile = resolvePiModelProfile(request);
  
  // piProfile contains all routing data plus Pi-specific wiring
  const result = await makeRequest({
    url: `${piProfile.baseUrl}/chat/completions`,
    method: "POST",
    headers: piProfile.headers,
    body: {
      model: request.model_id,
      messages: [{ role: "user", content: "Hi!" }],
    },
  });

  return result;
}

```

## Provider-Specific Routing Logic

HolaOS handles edge cases automatically through the routing layer:

| Provider Combination | Routing Behavior | Handled In |
|----------------------|------------------|------------|
| `openai_compatible` + `openai_direct` + GPT-5 | Routes to OpenAI responses endpoint | `resolveHarnessModelApi()` |
| Legacy Codex models | Applies special budget overrides | `resolveHarnessModelProfile()` |
| Ollama local models | Forces "text-only" modality | Profile construction |
| Non-OpenAI providers | Injects OpenAI compatibility shims | `resolveHarnessModelProfile()` |

## Extending the Integration: Adding New Models

To integrate a new AI model into HolaOS packages:

1. **Add to runtime config catalog** – Edit the JSON file at `HOLABOSS_RUNTIME_CONFIG_PATH` with provider, model_id, and endpoint details
2. **Or use default heuristics** – Provide a `HarnessModelRoutingRequest` with `provider_id` and `model_id`; the routing layer will auto-detect compatible endpoints
3. **Issue the request** – Call `resolveHarnessModelProfile()` or `resolvePiModelProfile()` to execute

No changes to core routing code are required.

## Extension Points for Custom Integrations

| Package | File | Extension Use Case |
|---------|------|------------------|
| `packages/remote-api` | [`src/server/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/src/server/index.ts) | Expose model routing to external services |
| `packages/app-builder-sdk` | [`src/types.ts`](https://github.com/holaboss-ai/holaOS/blob/main/src/types.ts) | Define custom `HarnessModelRoutingRequest` shapes for plugins |
| `runtime/harnesses` | [`src/model-routing.ts`](https://github.com/holaboss-ai/holaOS/blob/main/src/model-routing.ts) | Add provider-specific routing rules |

## Summary

- **HolaOS AI model integration** centers on the `HarnessModelRoutingRequest` → `HarnessResolvedModelProfile` → HTTP request pipeline
- **[`runtime/harnesses/src/model-routing.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/model-routing.ts)** handles catalog loading, API selection, and profile construction
- **[`runtime/harness-host/src/pi.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi.ts)** provides the recommended UI/CLI entry point
- **[`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts)** executes authenticated requests with automatic header injection
- **Zero boilerplate required**: Provide a routing request and the system handles endpoint normalization, auth, budgeting, and compatibility shims

## Frequently Asked Questions

### What is the minimum code needed to integrate an OpenAI model in HolaOS?

Create a `HarnessModelRoutingRequest` with `provider_id`, `model_id`, and `model_client` configuration, then pass it to `resolveHarnessModelProfile()`. The function returns a complete profile with `baseUrl`, `headers`, and endpoint details ready for `makeRequest()`.

### How does HolaOS handle authentication for different AI providers?

The routing layer sets `profile.authHeader` based on provider type. When true, [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts) automatically injects the `Authorization` header using the `api_key` from `model_client`. For proxy-based providers, auth may be handled server-side instead.

### Can I use the same integration code for OpenAI, Gemini, and Anthropic models?

Yes. The `resolveHarnessModelProfile()` function normalizes all providers to a compatible interface. It selects the correct endpoint, applies provider-specific transforms, and returns OpenAI-compatible options even for non-OpenAI models like Gemini or Claude.

### How do I configure reasoning/thinking modes for supported models?

Add `thinking_value` to your `HarnessModelRoutingRequest` with values: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, or `"xhigh"`. The routing layer maps this to `reasoningEffortMap` entries for OpenAI-compatible request formats automatically.