How AI Model Integration Works in AiToEarn: Architecture and Implementation Guide

AiToEarn integrates AI models through a modular NestJS library (@yikart/aitoearn-ai-client) that communicates via a provider-agnostic AI gateway, supporting both internal Agent workflows and external MCP-compatible assistants.

The AiToEarn platform (yikart/AiToEarn) implements a sophisticated AI model integration strategy built around a dedicated backend library rather than direct API calls to specific providers. This architecture decouples the application from individual AI services, allowing seamless switching between LLM providers through environment configuration. The system supports both programmatic AI consumption via NestJS services and integration with external AI assistants through the Model-Control-Protocol (MCP).

Modular AI Client Architecture

Core NestJS Module Structure

The foundation of AiToEarn's AI capabilities resides in the @yikart/aitoearn-ai-client library located at project/aitoearn-backend/libs/aitoearn-ai-client. This module exports AitoearnAiClientModule, which registers three essential services that handle different aspects of AI interaction.

The AiService acts as a thin wrapper around LLM endpoints, exposing methods such as chatCompletion and imageGeneration for direct model interaction. The AgentService orchestrates long-running AI workflows including content generation and video style transfer. Finally, the AitoearnAiClientService serves as the primary injection point used throughout the backend codebase, consumed by services like tools.service.ts and engagement.service.ts to access AI capabilities.

Provider-Agnostic Gateway Configuration

Rather than connecting directly to specific providers like OpenAI, Claude, or Gemini, the AI client communicates through a single AI gateway such as One-API or the community-maintained new-api project. This intermediary handles request translation and provider routing.

Configuration occurs through environment variables OPENAI_BASE_URL and OPENAI_API_KEY, documented in DOCKER_DEPLOYMENT_EN.md. This design enables a single AiToEarn deployment to switch between AI providers instantly by changing environment variables, without requiring code modifications or redeployment.

MCP Protocol for External AI Assistants

For integration with external AI assistants like Claude and Cursor, AiToEarn implements the MCP (Model-Control-Protocol). The backend's AiService exposes MCP endpoints that these assistants call to invoke the AI client functionality.

The MCP handshake, request/response schema, and routing logic are defined in project/aitoearn-backend/.claude/rules/ai-workflow.md. This same protocol layer powers the in-application Agent UI, utilizing Server-Sent Events (SSE) for streaming responses and multi-step workflow execution.

Agent-Driven Content Generation

Each Agent in AiToEarn represents a specialized NestJS injectable that composes multiple AI calls into coherent workflows. Agents such as Generating-Images, Generating-Videos, and Translating-Videos reside under project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/skills/.

These agents follow a predictable pipeline: prompt generation flows into LLM chat completion, followed by optional image generation or video synthesis. Each skill directory contains documentation detailing its specific workflow, such as the image generation flow described in generating-images/SKILL.md.

Frontend Integration Patterns

The web interface accesses AI capabilities through a thin TypeScript SDK also named @yikart/aitoearn-ai-client. State management occurs in project/aitoearn-web/src/store/agent/, where the useAgentStore hook handles task creation and SSE channel management.

Components like PublishDialogAi utilize useAISync.ts to trigger Agents and synchronize generated content back to the editor interface. This creates a seamless experience where users initiate AI generation in the UI and receive real-time updates as the backend Agent processes the request.

Implementation Examples

Backend Service Injection

Services throughout the backend access AI capabilities through dependency injection of the AI client:

// Inside any NestJS service (e.g. tools.service.ts)
@Injectable()
export class ToolsService {
  constructor(
    private readonly aiClient: AitoearnAiClientService,
  ) {}

  async generateCaption(prompt: string): Promise<string> {
    // Calls the LLM through the configured gateway
    const resp = await this.aiClient.chatCompletion({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: prompt }],
    });
    return resp.choices?.[0]?.message?.content ?? '';
  }
}

Frontend Agent Invocation

React components interact with Agents through the store hook:

import { useAgentStore } from '@/store/agent';

const { startTask, result, loading } = useAgentStore();

async function onGenerateImage() {
  await startTask({
    skill: 'generating-images',
    input: { prompt: 'A futuristic city at sunset' },
  });
  // `result` populates via SSE stream
  console.log('Generated image URL:', result?.imageUrl);
}

MCP Configuration for External Assistants

Configure Claude or Cursor to access AiToEarn capabilities:

# Example mcp.toml for Claude

[aitolearn]
api_key = "sk-your-new-api-key"
base_url = "https://your-new-api-host/v1"
model = "claude-3.5-sonnet"

Summary

• The AI model integration relies on a centralized NestJS library (@yikart/aitoearn-ai-client) that abstracts provider-specific implementations
• A provider-agnostic gateway (One-API/new-api) handles routing to OpenAI, Claude, or Gemini via OPENAI_BASE_URL and OPENAI_API_KEY environment variables
• MCP protocol support enables external assistants like Claude and Cursor to interact with the platform's AI capabilities through standardized endpoints
• Agent-driven workflows in project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/skills/ orchestrate multi-step content generation processes
• Frontend integration uses React hooks (useAgentStore) and Server-Sent Events (SSE) for real-time AI response streaming

Frequently Asked Questions

What AI providers does AiToEarn support?

AiToEarn supports any provider compatible with the OpenAI API format, including OpenAI, Anthropic Claude, Google Gemini, and self-hosted models. The system communicates through an AI gateway configured via the OPENAI_BASE_URL environment variable, allowing provider switching without code changes or redeployment.

How does the frontend receive AI-generated content in real-time?

The frontend uses Server-Sent Events (SSE) through the useAgentStore hook located in project/aitoearn-web/src/store/agent/. When an Agent task starts, the hook opens an SSE channel to stream progress updates and final results back to the React UI, as implemented in components like PublishDialogAi that utilize useAISync.ts.

What is the MCP protocol used for in AiToEarn?

The Model-Control-Protocol (MCP) enables external AI assistants like Claude and Cursor to invoke AiToEarn's AI capabilities. Defined in project/aitoearn-backend/.claude/rules/ai-workflow.md, MCP provides standardized endpoints for assistants to trigger content generation workflows and receive structured responses, effectively turning AiToEarn into a callable tool for external AI systems.

Where are the AI Agent skills defined in the codebase?

Agent skills are defined as NestJS injectables under project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/skills/, with each skill containing its own logic documentation in corresponding SKILL.md files. These skills orchestrate multiple AI calls to produce complex outputs like styled videos or translated content, following a pipeline from prompt generation through media synthesis.

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