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

Yes, HolaOS provides a modular model-routing layer with complete AI integration examples in runtime/harnesses/src/model-routing.ts, runtime/harness-host/src/pi.ts, and 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, 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:

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:

// 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 (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, 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:

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:

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:

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	Expose model routing to external services
packages/app-builder-sdk	src/types.ts	Define custom HarnessModelRoutingRequest shapes for plugins
runtime/harnesses	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 handles catalog loading, API selection, and profile construction
• runtime/harness-host/src/pi.ts provides the recommended UI/CLI entry point
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}