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

> Discover how AiToEarn seamlessly integrates AI models using a modular NestJS library and a provider-agnostic AI gateway for internal and external assistant support. Learn about the architecture and implementation.

- Repository: [yikart/AiToEarn](https://github.com/yikart/AiToEarn)
- Tags: architecture
- Published: 2026-05-12

---

**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`](https://github.com/yikart/AiToEarn/blob/main/tools.service.ts) and [`engagement.service.ts`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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:

```typescript
// 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:

```typescript
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:

```toml

# 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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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.