Core AI SDK

A simplified TypeScript SDK for integrating with the Core AI Service.

Features

• ✅ Type-safe TypeScript SDK with full type definitions
• 🔁 Automatic Retries with configurable exponential backoff
• 🌊 Streaming Support for real-time responses
• 🛡️ Content Safety with built-in NSFW detection
• 📊 Unified Schema for consistent API interaction
• 📦 Zero-Dependency (runtime) architecture using native fetch

Requirements

• Node.js >= 18.0.0

Installation

npm install @apnhalil/core-ai-sdk

Configuration

The SDK can be configured via environment variables or directly through the constructor.

Environment Variables (.env)

# Core AI Service (Required)
CORE_AI_APP_ID=your-app-id
CORE_AI_BASE_URL=https://core-ai-provider.run.app

# SDK Settings (Optional)
SDK_TIMEOUT=60000
SDK_MAX_RETRIES=3

Quick Start

import { CoreAI } from "@apnhalil/core-ai-sdk";

// Initialize the SDK
// (Credentials can also be loaded from process.env.CORE_AI_APP_ID)
const client = new CoreAI({
  credentials: {
    appId: "your-app-id",
  },
  options: {
    timeout: 30000, // 30s
    maxRetries: 3,
  },
});

1. Chat Completion

const response = await client.chat.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is the capital of France?" },
  ],
  temperature: 0.7,
});

console.log(response.choices[0]?.message.content);

2. Streaming Response

const stream = await client.chat.createStream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Tell me a story." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

3. NSFW Content Check

The SDK includes a built-in safety resource to check content for NSFW material.

const result = await client.safety.checkNSFW({
  text: "Some text content to analyze",
  // imageUrl: 'https://example.com/image.jpg', // Optional: Check image URL
  // imageBase64: '...', // Optional: Check base64 image
  model: "gpt-4o",
});

if (result.isNsfw) {
  console.log("NSFW Content detected!", result.categories);
} else {
  console.log("Content is safe.");
}

CLI Tool

The SDK includes a CLI tool for testing models and chat interactions.

# List available models
npx core-ai models

# Start an interactive chat
npx core-ai chat [model]

Error Handling

The SDK provides typed error classes for better error handling.

import { CoreAIError, AuthenticationError, RateLimitError } from '@apnhalil/core-ai-sdk';

try {
  await client.chat.create({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Check your App ID');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Request failed:', error.message);
  }
}

API Reference

Main Resources

• client.chat - Chat completions and streaming
• client.models - List available models
• client.safety - Content moderation (NSFW checks)

Types

All request and response types are exported from the package:

import type {
  ChatCompletionRequest,
  ChatCompletionResponse,
  NsfwCheckRequest,
  NsfwCheckResponse,
} from "@apnhalil/core-ai-sdk";