Core Packages in holaOS for AI Development: A Complete Guide to the Built-In AI Stack

holaOS bundles eight essential AI packages—OpenAI, Anthropic Claude, Pi‑AI, Pi‑Coding‑Agent, TypeBox, Canvas, Tree‑Sitter, and utility I/O libraries—that form its complete runtime environment for building and deploying AI agents.

The core packages in holaOS for AI development are declared in a single workspace file, runtime/harness-host/package.json, which serves as the execution harness for model routing and agent orchestration. This article breaks down each package's role, shows runnable code examples, and maps the key source files that tie everything together.

---

The Eight Core AI Packages

holaOS installs these dependencies as a cohesive stack. No external AI libraries are required to build production agents.

Package	Version	Purpose
openai	^6.26.0	Official OpenAI client for Chat Completions, embeddings, and fine-tuning
@anthropic-ai/claude-agent-sdk	^0.3.199	Anthropic Claude integration for text and Claude 2 model access
@earendil-works/pi-ai	0.80.2	High-level agent primitives: tool use, planning, and memory
@earendil-works/pi-coding-agent	0.80.2	Code-generation agent with linting and refactoring helpers
@sinclair/typebox	^0.34.41	Runtime type validation for model-profile configuration objects
@napi-rs/canvas	^0.1.100	Native canvas implementation for image generation and drawing
tree-sitter-wasms / web-tree-sitter	^0.1.12 / ^0.25.10	Source-code parsing for code-aware agents
exceljs, jszip, mcporter``, **unpdf`	Various	Data I/O: spreadsheets, archives, and PDF processing

These packages split naturally into four layers: LLM providers, agent frameworks, type safety and parsing, and media utilities.

---

LLM Provider Packages: OpenAI and Anthropic

OpenAI (openai)

The official OpenAI client powers GPT-4, GPT-4o-mini, and embedding workflows. In runtime/harness-host/src/pi.ts, the holaOS runtime imports APIError as OpenAIApiError from this package to normalize error handling across providers.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function chat(prompt: string) {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: prompt }],
  });
  return resp.choices[0].message.content;
}

Anthropic Claude (@anthropic-ai/claude-agent-sdk)

Provides first-class access to Claude 3.5 Sonnet and earlier models. The SDK follows a similar pattern to OpenAI but with Anthropic-specific parameters for extended context windows.

import { Claude } from "@anthropic-ai/claude-agent-sdk";

const claude = new Claude({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function complete(prompt: string) {
  const result = await claude.completions.create({
    model: "claude-3-5-sonnet-20240620",
    prompt,
  });
  return result.completion;
}

---

Agent Framework: Pi‑AI and Pi‑Coding‑Agent

Pi‑AI (@earendil-works/pi-ai)

Pi‑AI supplies the tool-use, planning, and memory abstractions that holaOS agents build upon. It wraps raw LLM calls into structured, stateful agent sessions.

import { createAgent } from "@earendil-works/pi-ai";

const agent = createAgent({
  name: "Echo",
  tools: [], // custom tools injected here
});

async function ask(question: string) {
  const answer = await agent.run({ prompt: question });
  return answer;
}

Pi‑Coding‑Agent (@earendil-works/pi-coding-agent)

Built atop Pi‑AI, this package adds code-generation, lint-aware editing, and refactoring workflows. It accepts task descriptions and returns structured code blocks with metadata.

import { createCodingAgent } from "@earendil-works/pi-coding-agent";

const coder = createCodingAgent({ model: "openai/gpt-4o-mini" });

async function generateCode(task: string) {
  const { code } = await coder.generate({ description: task });
  return code;
}

---

Type Safety and Code Parsing

TypeBox (@sinclair/typebox)

Strict runtime type validation for model-profile objects. holaOS uses TypeBox schemas to validate configuration before routing requests to providers, catching misconfigurations early.

Tree‑Sitter (tree-sitter-wasms / web-tree-sitter)

Enables syntactic code analysis for agents that need to understand source structure. The WASM-based parser runs natively in the harness environment.

import * as tsParser from "web-tree-sitter";

await tsParser.init();
const parser = new tsParser.Parser();
parser.setLanguage(await tsParser.Language.load("tree-sitter-typescript.wasm"));

const source = `function hello(){return "hi";}`;
const tree = parser.parse(source);
console.log(tree.rootNode.toString()); // AST output

---

Media and I/O Utilities

Canvas (@napi-rs/canvas)

Fast, native image generation without Node-canvas dependencies. Used for rendering charts, diagrams, and agent-generated visuals.

import { createCanvas } from "@napi-rs/canvas";

const canvas = createCanvas(256, 256);
const ctx = canvas.getContext("2d");

ctx.fillStyle = "#ff6600";
ctx.fillRect(0, 0, 256, 256);
ctx.fillStyle = "#ffffff";
ctx.font = "32px sans-serif";
ctx.fillText("holaOS", 50, 140);

await canvas.encode("png", "output.png");

Data Processing Libraries

• exceljs: Read/write Excel workbooks
• jszip: Archive creation and extraction
• mcporter: Specialized format conversion
• unpdf: PDF text and structure extraction

These utilities let agents ingest documents, transform data, and output packaged deliverables.

---

Key Source Files in holaOS

Understanding where these packages are wired together helps with debugging and extension.

File	Responsibility
runtime/harness-host/package.json	Declares all eight core dependencies
runtime/harness-host/src/pi.ts	Integrates OpenAI client and error types into Pi‑AI runtime
runtime/harness-host/src/pi.test.ts	Unit tests for OpenAI-compatible error handling and profile normalization
runtime/harnesses/src/model-routing.ts	Chooses between OpenAI, Anthropic, and custom providers by model ID
runtime/harnesses/src/codex.ts	Enumerates OpenAI Codex models (gpt-5, gpt-5.4)

The model-routing.ts file is particularly important—it implements the logic that maps a model string like "openai/gpt-4o-mini" or "anthropic/claude-3-5-sonnet" to the correct SDK instance.

---

How the Stack Fits Together

1. Configuration — TypeBox validates model profiles at startup
2. Routing — model-routing.ts selects OpenAI or Anthropic SDK based on model ID
3. Execution — Pi‑AI or Pi‑Coding‑Agent orchestrates tool use and memory
4. Enhancement — Tree‑Sitter parses code context; Canvas and I/O utilities handle non-text output

This architecture keeps agent logic provider-agnostic while giving direct access to provider-specific features when needed.

---

Summary

• holaOS installs eight core packages via runtime/harness-host/package.json—no additional AI dependencies required
• OpenAI and Anthropic SDKs provide LLM endpoints with unified error handling in pi.ts
• Pi‑AI and Pi‑Coding‑Agent deliver the agent framework: tools, planning, memory, and code generation
• TypeBox and Tree‑Sitter ensure type-safe configs and code-aware parsing
• Canvas, exceljs, jszip, mcporter, and unpdf complete the stack with media and document capabilities

---

Frequently Asked Questions

What is the main configuration file for holaOS AI packages?

The runtime/harness-host/package.json file declares all core AI dependencies including OpenAI, Anthropic, Pi‑AI, and supporting libraries. This workspace serves as the primary execution environment for agents.

Can I use holaOS with LLM providers other than OpenAI and Anthropic?

The core packages in holaOS for AI development are built around OpenAI and Anthropic as first-class providers. However, runtime/harnesses/src/model-routing.ts implements a pluggable routing layer that could be extended to additional providers following the same pattern.

How does holaOS handle type safety for AI model configurations?

The @sinclair/typebox package provides runtime JSON schema validation. Model-profile objects are validated against TypeBox schemas before being passed to routing logic, preventing malformed configurations from reaching provider SDKs.

What enables code-aware capabilities in holaOS agents?

The web-tree-sitter and tree-sitter-wasms packages parse source code into ASTs. Agents can query this structure for symbol extraction, dependency analysis, and context-aware code generation, as demonstrated in pi-coding-agent workflows.

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