What Is the Purpose of lib/ai in OpenMAIC? The Core AI Abstraction Layer Explained

The lib/ai directory in OpenMAIC functions as the centralized abstraction layer for all large-language-model (LLM) operations, unifying vendor interactions through callLLM and streamLLM APIs while managing provider selection, "thinking" budgets, and usage tracking.

The lib/ai folder represents the nerve center of the OpenMAIC codebase. This directory consolidates every aspect of AI service integration into a single, provider-agnostic interface that routes all LLM calls through standardized wrappers. By decoupling business logic from vendor-specific implementations, OpenMAIC achieves consistent behavior across OpenAI, Anthropic, Google, Azure, and other compatible providers.

Unified LLM API: callLLM and streamLLM

At the heart of lib/ai lies lib/ai/llm.ts, which exposes the primary public interfaces for AI generation. The module wraps the underlying AI SDK's generateText and streamText functions to provide synchronous and streaming generation capabilities respectively.

The callLLM function handles standard request-response cycles with built-in retry logic, validation, and fire-and-forget usage logging. For real-time applications, streamLLM returns a streaming response interface that processes chunks as they arrive from providers. Both methods automatically record token consumption and model metadata without blocking the request flow, ensuring accurate accounting while maintaining performance.

Multi-Provider Architecture and Model Resolution

OpenMAIC supports heterogeneous AI environments through a canonical model identification system defined across multiple configuration files.

lib/ai/providers.ts defines each supported vendor—including OpenAI, Anthropic, Google, and Azure—mapping their specific models and capabilities to internal structures. When a model identifier like gpt-4o-mini or claude-3-5-sonnet is requested, lib/ai/model-aliases.ts resolves these canonical IDs to provider-specific endpoints, enabling seamless switching between vendors without changing application code.

lib/ai/azure.ts contains Azure-specific authentication utilities that integrate with the provider wrapper, while lib/ai/model-metadata.ts offers helpers for retrieving model capabilities and pricing information programmatically.

Thinking Configuration and Async Context Management

A distinctive feature of the OpenMAIC AI layer is the "thinking" system, which controls reasoning effort and token budgets on a per-request basis.

The configuration schema lives in lib/ai/thinking-config.ts, defining modes such as budget (token limits) or effort (reasoning levels). These settings propagate through lib/ai/thinking-context.ts, which implements an async-local storage pattern to carry ThinkingConfig objects across asynchronous call stacks. This architecture allows provider-specific request payloads to adjust automatically based on the current thinking context, without requiring explicit parameter passing through every function layer.

Streaming and Provider-Specific Utilities

For advanced streaming scenarios, lib/ai/reasoning-sse.ts handles Server-Sent Events (SSE) parsing for streamed reasoning responses, particularly useful when consuming chain-of-thought outputs from compatible models. This modular approach keeps transport-specific logic separated from the core generation APIs while maintaining extensibility for future providers.

Practical Implementation Examples

The following patterns demonstrate standard usage of the lib/ai module in OpenMAIC applications:

import { callLLM, streamLLM } from '@/lib/ai/llm';
import type { ThinkingConfig } from '@/lib/types/provider';

// Simple generation with default thinking configuration
const result = await callLLM(
  { model: 'gpt-4o-mini', prompt: 'Explain quantum tunnelling.' },
  'my-feature',
);
console.log(result.text);

For streaming responses with custom reasoning budgets:

// Generation with a custom thinking budget (e.g., 500 tokens)
const myThinking: ThinkingConfig = { mode: 'budget', budgetTokens: 500 };
const streamed = streamLLM(
  { 
    model: 'claude-3-5-sonnet', 
    messages: [{ role: 'user', content: 'Summarise this article.' }] 
  },
  'summary-task',
  myThinking,
);

for await (const chunk of streamed.text) {
  process.stdout.write(chunk);
}

Summary

• lib/ai/llm.ts provides the unified callLLM and streamLLM interfaces that wrap all vendor SDKs with retry logic and usage logging.
• The directory supports multiple providers (OpenAI, Anthropic, Google, Azure) through providers.ts and canonical model resolution in model-aliases.ts.
• Thinking configuration is managed via thinking-config.ts and propagated through async-local storage in thinking-context.ts for per-request budget control.
• Usage tracking occurs automatically via fire-and-forget logging in llm.ts, recording tokens and metadata without impacting latency.
• Helper modules like azure.ts and reasoning-sse.ts provide extensibility for authentication and streaming protocols.

Frequently Asked Questions

What is the main entry point for LLM calls in OpenMAIC?

The primary entry points are the callLLM and streamLLM functions exported from lib/ai/llm.ts. These functions serve as the single integration point for all AI generation tasks, abstracting away provider-specific implementations while adding cross-cutting concerns like retries, validation, and usage recording.

How does OpenMAIC handle different AI providers in lib/ai?

OpenMAIC uses a two-layer resolution system: lib/ai/providers.ts defines vendor configurations and capabilities, while lib/ai/model-aliases.ts maps canonical model IDs (like gpt-4o-mini) to provider-specific endpoints. This architecture allows the same application code to switch between OpenAI, Anthropic, Google, or Azure by simply changing the model identifier string.

What is the "thinking" feature in OpenMAIC's lib/ai?

The thinking feature controls reasoning effort and computational budget for LLM requests. Implemented in lib/ai/thinking-config.ts, it supports modes like budget (token limits) or effort (reasoning levels). The current configuration travels through async-local storage via lib/ai/thinking-context.ts, automatically adjusting provider payloads without manual parameter threading.

How does lib/ai track AI usage without affecting performance?

Usage tracking is implemented as a fire-and-forget side effect within lib/ai/llm.ts. After successful LLM completion, token counts, model identifiers, and provider metadata are logged asynchronously. This approach ensures accurate accounting and billing data capture while preventing logging latency from blocking the main request-response cycle.

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