ai_box #

Version: V1

This package provides a base class and test utilities for all AI provider classes that inherit from LLMAIBase.

LLMAIBase #

An abstract class that all AI providers (such as ChatGPT, Claude, Gemini, etc.) should inherit from.

Required Methods #

• completions(): Chat completion
• getModels(): Get a list of available models
• validateKey(): Validate the API key

Provided Utility Methods #

• chat() / chatStream(): Chat with structured messages
• chatWithStrings(): Chat with an array of strings
• generateText(): Simple text generation
• generateTextStream(): Stream text output
• askWithImages(): One-shot prompt with images

Multimodal input #

Pass images, audio, or files as LLMContentParts on any message. The same abstraction works across every provider — the provider converts it to the right wire format (OpenAI content arrays, Claude content blocks, Gemini inlineData / fileData).

import 'dart:typed_data';
import 'package:ai_box/ai_box.dart';

final res = await ai.chat(
  model: 'gpt-5.5',
  messages: [
    LLMContent.user('Describe these', attachments: [
      LLMImagePart.bytes(pngBytes, mimeType: 'image/png'),
      LLMImagePart.url('https://example.com/photo.jpg'),
      LLMFilePart.bytes(pdfBytes, mimeType: 'application/pdf'),
    ]),
  ],
);
print(res.text);

Just drop in a File (dart:io) #

import 'package:ai_box/io.dart';

final msg = LLMContent.user('What is in these?', attachments: [
  File('photo.png').toImagePart(),
  File('report.pdf').toFilePart(),
  File('memo.mp3').toAudioPart(),
]);

ai_box core stays platform-agnostic (no dart:io); the File helpers live in the separate package:ai_box/io.dart import.

Output: sealed parts cover every case #

LLMContent.parts is a list of the sealed LLMContentPart, so a switch is exhaustive:

for (final part in res.content.parts) {
  switch (part) {
    case LLMTextPart(:final text): print(text);
    case LLMImagePart(): saveImage(part.bytes);      // generated image bytes
    case LLMAudioPart(): saveAudio(part.bytes);      // generated audio bytes
    case LLMFilePart(): saveFile(part.bytes);
    case LLMToolCallPart(:final name): callTool(name, part.arguments);
    case LLMToolResultPart(): break;
    case LLMReasoningPart(:final text): logThinking(text);
    case LLMCodeExecutionPart(): break;
    case LLMCodeExecutionResultPart(): break;
  }
}

Convenience getters: res.text, res.content.images, res.content.audioList, res.content.files, res.toolCalls, res.content.reasoning.

res.finishReason is the normalized LLMFinishReason enum (stop / length / toolCalls / contentFilter / other), and res.usage carries inputTokens / outputTokens / cachedInputTokens / reasoningTokens.

Error handling: sealed LLMException #

Every provider normalizes failures into a sealed LLMException:

try {
  await ai.generateText(model: '...', message: 'hi');
} on LLMException catch (e) {
  switch (e) {
    case LLMAuthException(): // 401 / 403
    case LLMRateLimitException(): // 429
    case LLMInvalidRequestException(): // 4xx
    case LLMServerException(): // 5xx
    case LLMNetworkException(): // connectivity
    case LLMUnknownException():
  }
}

Tool / function calling #

final res = await ai.chat(
  model: 'gpt-5.5',
  messages: [LLMContent.user('Weather in Tokyo?')],
  tools: [
    LLMTool(
      name: 'get_weather',
      description: 'Get current weather',
      parameters: {
        'type': 'object',
        'properties': {'city': {'type': 'string'}},
        'required': ['city'],
      },
    ),
  ],
  toolChoice: LLMToolChoice.auto,
);

for (final call in res.toolCalls) {
  final result = await runTool(call.name, call.arguments);
  // Send the result back on the next turn:
  // LLMContent(role: LLMRole.user, parts: [
  //   LLMToolResultPart(toolCallId: call.id, content: result),
  // ])
}

Structured output (JSON Schema) #

final res = await ai.chat(
  model: 'gpt-5.5',
  messages: [LLMContent.user('Extract name and age')],
  responseFormat: LLMResponseFormat.jsonSchema(
    schema: {
      'type': 'object',
      'properties': {
        'name': {'type': 'string'},
        'age': {'type': 'integer'},
      },
      'required': ['name', 'age'],
    },
  ),
);

Streaming #

Every provider implements true token-by-token SSE streaming:

await for (final text in ai.generateTextStream(model: '...', message: 'Hi')) {
  stdout.write(text);
}

For full control (reasoning deltas, tool calls, usage), use chatStream() / completionsStream():

await for (final chunk in ai.chatStream(
  model: '...',
  messages: [LLMContent.user('Hi')],
)) {
  stdout.write(chunk.delta);          // incremental text
  logThinking(chunk.reasoningDelta);  // incremental thinking (if any)
  if (chunk.isDone) {
    // The final chunk carries the complete parts, finish reason and usage.
    print(chunk.finishReason);
    print(chunk.usage);
  }
}

Adding a New AI Provider #

1. Create a class that inherits from LLMAIBase.
2. Implement completions(), getModels() and validateKey().
3. Optionally override completionsStream() with the provider's SSE streaming (the shared helpers below already cover OpenAI-compatible APIs).

Shared helpers for provider implementations #

Two opt-in libraries keep provider packages free of copy-pasted plumbing (they are not exported from package:ai_box/ai_box.dart):

• package:ai_box/provider_http.dart — requestJson() runs an HTTP call and normalizes failures into the sealed LLMException hierarchy (LLMNetworkException on connectivity errors, LLMException.fromHttp on non-2xx responses). postSseData() / decodeSseJson() do the same for SSE streaming endpoints.
• package:ai_box/openai_compat.dart — buildOpenAiBody() / parseOpenAiResponse() / postOpenAiJson() / streamOpenAiCompletions() implement the OpenAI-compatible Chat Completions wire format (multimodal content, tools, structured output, SSE streaming), shared by chatgpt_box, deepseek_box, grok_box, minimax_box and openrouter_box.