@allanfsouza/aether-sdk 2.4.10 → 2.4.11

package/dist/ai.d.ts

@@ -0,0 +1,300 @@
+import type { AxiosInstance } from "axios";
+import type { PlataformaClient } from "./index.js";
+/**
+ * Opções para o método chat()
+ */
+export interface ChatOptions {
+    /** ID da conversa para manter contexto entre mensagens */
+    conversationId?: string;
+    /** Contexto adicional (ex: "vendas", "suporte", "produtos") */
+    context?: string;
+    /** Callback chamado a cada chunk de texto recebido (streaming) */
+    onChunk?: (chunk: string) => void;
+    /** Callback chamado quando a resposta completa é recebida */
+    onComplete?: (fullResponse: string, metadata: ChatMetadata) => void;
+    /** Callback chamado em caso de erro */
+    onError?: (error: Error) => void;
+    /** Timeout em ms (padrão: 30000) */
+    timeout?: number;
+}
+/**
+ * Metadados retornados após uma resposta completa
+ */
+export interface ChatMetadata {
+    conversationId: string;
+    messageId?: string;
+    tokensUsed?: number;
+    sources?: RetrievedSource[];
+}
+/**
+ * Fonte de dados usada pelo RAG
+ */
+export interface RetrievedSource {
+    type: string;
+    content: string;
+    similarity: number;
+}
+/**
+ * Resposta do método ask()
+ */
+export interface AskResponse {
+    text: string;
+    conversationId: string;
+    sources?: RetrievedSource[];
+}
+/**
+ * Conversa persistida
+ */
+export interface Conversation {
+    id: string;
+    title: string;
+    context: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount?: number;
+}
+/**
+ * Mensagem de uma conversa
+ */
+export interface Message {
+    id: string;
+    conversationId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    metadata?: Record<string, any>;
+    createdAt: string;
+}
+/**
+ * Tipo de feedback
+ */
+export type FeedbackType = 'thumbs_up' | 'thumbs_down';
+/**
+ * Opções para busca semântica
+ */
+export interface SemanticSearchOptions {
+    /** Número máximo de resultados (padrão: 10) */
+    limit?: number;
+    /** Score mínimo de similaridade 0-1 (padrão: 0.5) */
+    minScore?: number;
+    /** Filtrar por collection específica */
+    collection?: string;
+}
+/**
+ * Resultado de busca semântica
+ */
+export interface SemanticSearchResult {
+    id: string;
+    content: string;
+    collection: string;
+    similarity: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Opções para geração de conteúdo
+ */
+export interface GenerateOptions {
+    /** Tom do texto (formal, casual, técnico, etc) */
+    tone?: 'formal' | 'casual' | 'technical' | 'friendly';
+    /** Tamanho aproximado (short, medium, long) */
+    length?: 'short' | 'medium' | 'long';
+    /** Idioma (padrão: pt-BR) */
+    language?: string;
+    /** Contexto adicional para a geração */
+    context?: string;
+}
+export declare class AIModule {
+    private client;
+    private http;
+    /** Sub-módulo para gerenciar conversas */
+    conversations: ConversationsAPI;
+    /** Sub-módulo para funções administrativas */
+    admin: AIAdminAPI;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * Faz uma pergunta simples e aguarda a resposta completa.
+     * Ideal para quando não precisa de streaming.
+     *
+     * @example
+     * const { text } = await aether.ai.ask("Quais produtos estão em promoção?");
+     * console.log(text);
+     */
+    ask(message: string, conversationId?: string): Promise<AskResponse>;
+    /**
+     * Inicia um chat com streaming de resposta.
+     * A resposta chega em chunks conforme a IA gera.
+     *
+     * @example
+     * await aether.ai.chat("Explique como funciona o sistema de pagamentos", {
+     *   onChunk: (chunk) => {
+     *     // Atualiza UI em tempo real
+     *     setResponse(prev => prev + chunk);
+     *   },
+     *   onComplete: (full, meta) => {
+     *     console.log("Conversa ID:", meta.conversationId);
+     *   }
+     * });
+     */
+    chat(message: string, options?: ChatOptions): Promise<void>;
+    /**
+     * Envia feedback sobre uma resposta da IA.
+     * Ajuda a melhorar as respostas futuras.
+     *
+     * @example
+     * await aether.ai.feedback(messageId, 'thumbs_up');
+     * await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');
+     */
+    feedback(messageId: string, type: FeedbackType, comment?: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Busca semântica nos dados do projeto.
+     * Encontra documentos similares usando embeddings.
+     *
+     * @example
+     * // Busca produtos similares a uma descrição
+     * const results = await aether.ai.search("tênis confortável para corrida");
+     *
+     * // Com filtros
+     * const results = await aether.ai.search("problema no login", {
+     *   collection: "support_tickets",
+     *   limit: 5,
+     *   minScore: 0.7
+     * });
+     */
+    search(query: string, options?: SemanticSearchOptions): Promise<SemanticSearchResult[]>;
+    /**
+     * Gera texto baseado em um prompt e contexto.
+     * Útil para descrições de produtos, resumos, etc.
+     *
+     * @example
+     * // Gerar descrição de produto
+     * const descricao = await aether.ai.generate(
+     *   "Escreva uma descrição para o produto",
+     *   { productName: "iPhone 15", price: 5999, features: ["5G", "48MP"] },
+     *   { tone: 'friendly', length: 'medium' }
+     * );
+     */
+    generate(prompt: string, data: Record<string, any>, options?: GenerateOptions): Promise<string>;
+    /**
+     * Analisa dados e retorna insights em linguagem natural.
+     *
+     * @example
+     * const insights = await aether.ai.analyze("orders", {
+     *   question: "Como foram as vendas essa semana?",
+     *   period: "7d"
+     * });
+     */
+    analyze(collection: string, options: {
+        question: string;
+        period?: string;
+    }): Promise<{
+        insights: string;
+        data?: any;
+    }>;
+    /**
+     * Processa linguagem natural e converte em query estruturada.
+     * Útil para criar filtros de busca baseados em texto do usuário.
+     *
+     * @example
+     * const query = await aether.ai.parseQuery(
+     *   "produtos vermelhos acima de 100 reais ordenados por preço"
+     * );
+     * // Retorna: { filter: { color: 'vermelho', price: { $gt: 100 } }, sort: { price: 'ASC' } }
+     */
+    parseQuery(naturalLanguage: string, collection?: string): Promise<{
+        filter?: Record<string, any>;
+        sort?: Record<string, any>;
+    }>;
+}
+declare class ConversationsAPI {
+    private client;
+    private http;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * Lista todas as conversas do usuário no projeto.
+     *
+     * @example
+     * const conversas = await aether.ai.conversations.list();
+     */
+    list(): Promise<Conversation[]>;
+    /**
+     * Busca o histórico de mensagens de uma conversa.
+     *
+     * @example
+     * const mensagens = await aether.ai.conversations.getMessages(conversationId);
+     */
+    getMessages(conversationId: string): Promise<Message[]>;
+    /**
+     * Deleta uma conversa e todo seu histórico.
+     *
+     * @example
+     * await aether.ai.conversations.delete(conversationId);
+     */
+    delete(conversationId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Renomeia uma conversa.
+     *
+     * @example
+     * await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
+     */
+    rename(conversationId: string, title: string): Promise<Conversation>;
+}
+declare class AIAdminAPI {
+    private client;
+    private http;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * Reindexa todos os dados do projeto para RAG.
+     * Use após adicionar/modificar grandes volumes de dados.
+     * Executa em background.
+     *
+     * @example
+     * await aether.ai.admin.reindex();
+     */
+    reindex(): Promise<{
+        message: string;
+    }>;
+    /**
+     * Limpa todos os embeddings do projeto.
+     * CUIDADO: A IA "esquece" todo o contexto aprendido.
+     *
+     * @example
+     * const { deletedCount } = await aether.ai.admin.clear();
+     */
+    clear(): Promise<{
+        deletedCount: number;
+    }>;
+    /**
+     * Retorna estatísticas de uso da IA.
+     *
+     * @example
+     * const stats = await aether.ai.admin.stats();
+     * console.log(stats.totalConversations, stats.totalMessages);
+     */
+    stats(): Promise<{
+        totalConversations: number;
+        totalMessages: number;
+        totalEmbeddings: number;
+        storageUsedMB: number;
+    }>;
+    /**
+     * Configura quais collections são indexadas automaticamente.
+     *
+     * @example
+     * await aether.ai.admin.setIndexedCollections(['products', 'articles', 'faq']);
+     */
+    setIndexedCollections(collections: string[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Busca configurações atuais de IA do projeto.
+     */
+    getConfig(): Promise<{
+        indexedCollections: string[];
+        autoIndex: boolean;
+        embeddingModel: string;
+    }>;
+}
+export {};

package/dist/ai.js

@@ -0,0 +1,370 @@
+// src/ai.ts
+// [NOVO] Módulo de IA do Aether SDK
+// Permite que clientes adicionem IA aos seus apps com poucas linhas de código
+// Data: Dezembro 2025
+// =============================================================================
+// MÓDULO PRINCIPAL
+// =============================================================================
+export class AIModule {
+    constructor(client, http) {
+        this.client = client;
+        this.http = http;
+        this.conversations = new ConversationsAPI(client, http);
+        this.admin = new AIAdminAPI(client, http);
+    }
+    // ===========================================================================
+    // MÉTODOS PRINCIPAIS
+    // ===========================================================================
+    /**
+     * Faz uma pergunta simples e aguarda a resposta completa.
+     * Ideal para quando não precisa de streaming.
+     *
+     * @example
+     * const { text } = await aether.ai.ask("Quais produtos estão em promoção?");
+     * console.log(text);
+     */
+    async ask(message, conversationId) {
+        return new Promise((resolve, reject) => {
+            let fullText = '';
+            let metadata = { conversationId: conversationId || '' };
+            this.chat(message, {
+                conversationId,
+                onChunk: (chunk) => {
+                    fullText += chunk;
+                },
+                onComplete: (response, meta) => {
+                    metadata = meta;
+                    resolve({
+                        text: fullText,
+                        conversationId: meta.conversationId,
+                        sources: meta.sources
+                    });
+                },
+                onError: reject
+            }).catch(reject);
+        });
+    }
+    /**
+     * Inicia um chat com streaming de resposta.
+     * A resposta chega em chunks conforme a IA gera.
+     *
+     * @example
+     * await aether.ai.chat("Explique como funciona o sistema de pagamentos", {
+     *   onChunk: (chunk) => {
+     *     // Atualiza UI em tempo real
+     *     setResponse(prev => prev + chunk);
+     *   },
+     *   onComplete: (full, meta) => {
+     *     console.log("Conversa ID:", meta.conversationId);
+     *   }
+     * });
+     */
+    async chat(message, options = {}) {
+        const projectId = this.client.projectId;
+        const token = this.client.getToken();
+        if (!token) {
+            const error = new Error('Usuário não autenticado. Faça login primeiro.');
+            if (options.onError) {
+                options.onError(error);
+                return;
+            }
+            throw error;
+        }
+        const timeout = options.timeout || 30000;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(`${this.client.apiUrl}/v1/ai/chat`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${token}`,
+                    'X-Project-ID': projectId
+                },
+                body: JSON.stringify({
+                    message,
+                    projectId,
+                    conversationId: options.conversationId,
+                    context: options.context || 'general'
+                }),
+                signal: controller.signal
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Erro na API: ${response.status} - ${errorText}`);
+            }
+            // Captura conversation ID do header (se disponível)
+            const convIdFromHeader = response.headers.get('X-Conversation-ID');
+            // Processa o stream
+            const reader = response.body?.getReader();
+            const decoder = new TextDecoder();
+            let fullResponse = '';
+            if (!reader) {
+                throw new Error('Stream não disponível');
+            }
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                const chunk = decoder.decode(value, { stream: true });
+                fullResponse += chunk;
+                if (options.onChunk) {
+                    options.onChunk(chunk);
+                }
+            }
+            // Callback de conclusão
+            if (options.onComplete) {
+                options.onComplete(fullResponse, {
+                    conversationId: convIdFromHeader || options.conversationId || '',
+                });
+            }
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') {
+                error = new Error(`Timeout: A requisição excedeu ${timeout}ms`);
+            }
+            if (options.onError) {
+                options.onError(error);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Envia feedback sobre uma resposta da IA.
+     * Ajuda a melhorar as respostas futuras.
+     *
+     * @example
+     * await aether.ai.feedback(messageId, 'thumbs_up');
+     * await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');
+     */
+    async feedback(messageId, type, comment) {
+        const { data } = await this.http.post('/ai/feedback', {
+            messageId,
+            feedbackType: type,
+            comment
+        });
+        return data;
+    }
+    // ===========================================================================
+    // BUSCA SEMÂNTICA
+    // ===========================================================================
+    /**
+     * Busca semântica nos dados do projeto.
+     * Encontra documentos similares usando embeddings.
+     *
+     * @example
+     * // Busca produtos similares a uma descrição
+     * const results = await aether.ai.search("tênis confortável para corrida");
+     *
+     * // Com filtros
+     * const results = await aether.ai.search("problema no login", {
+     *   collection: "support_tickets",
+     *   limit: 5,
+     *   minScore: 0.7
+     * });
+     */
+    async search(query, options = {}) {
+        const { data } = await this.http.post('/ai/search', {
+            query,
+            projectId: this.client.projectId,
+            limit: options.limit || 10,
+            minScore: options.minScore || 0.5,
+            collection: options.collection
+        });
+        return data.results;
+    }
+    // ===========================================================================
+    // GERAÇÃO DE CONTEÚDO
+    // ===========================================================================
+    /**
+     * Gera texto baseado em um prompt e contexto.
+     * Útil para descrições de produtos, resumos, etc.
+     *
+     * @example
+     * // Gerar descrição de produto
+     * const descricao = await aether.ai.generate(
+     *   "Escreva uma descrição para o produto",
+     *   { productName: "iPhone 15", price: 5999, features: ["5G", "48MP"] },
+     *   { tone: 'friendly', length: 'medium' }
+     * );
+     */
+    async generate(prompt, data, options = {}) {
+        const { data: response } = await this.http.post('/ai/generate', {
+            prompt,
+            data,
+            projectId: this.client.projectId,
+            tone: options.tone || 'friendly',
+            length: options.length || 'medium',
+            language: options.language || 'pt-BR',
+            context: options.context
+        });
+        return response.text;
+    }
+    // ===========================================================================
+    // ANÁLISE DE DADOS
+    // ===========================================================================
+    /**
+     * Analisa dados e retorna insights em linguagem natural.
+     *
+     * @example
+     * const insights = await aether.ai.analyze("orders", {
+     *   question: "Como foram as vendas essa semana?",
+     *   period: "7d"
+     * });
+     */
+    async analyze(collection, options) {
+        const { data } = await this.http.post('/ai/analyze', {
+            collection,
+            projectId: this.client.projectId,
+            question: options.question,
+            period: options.period || '7d'
+        });
+        return data;
+    }
+    /**
+     * Processa linguagem natural e converte em query estruturada.
+     * Útil para criar filtros de busca baseados em texto do usuário.
+     *
+     * @example
+     * const query = await aether.ai.parseQuery(
+     *   "produtos vermelhos acima de 100 reais ordenados por preço"
+     * );
+     * // Retorna: { filter: { color: 'vermelho', price: { $gt: 100 } }, sort: { price: 'ASC' } }
+     */
+    async parseQuery(naturalLanguage, collection) {
+        const { data } = await this.http.post('/ai/parse-query', {
+            query: naturalLanguage,
+            collection,
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+}
+// =============================================================================
+// SUB-MÓDULO: CONVERSAS
+// =============================================================================
+class ConversationsAPI {
+    constructor(client, http) {
+        this.client = client;
+        this.http = http;
+    }
+    /**
+     * Lista todas as conversas do usuário no projeto.
+     *
+     * @example
+     * const conversas = await aether.ai.conversations.list();
+     */
+    async list() {
+        const { data } = await this.http.get('/ai/conversations', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+    /**
+     * Busca o histórico de mensagens de uma conversa.
+     *
+     * @example
+     * const mensagens = await aether.ai.conversations.getMessages(conversationId);
+     */
+    async getMessages(conversationId) {
+        const { data } = await this.http.get(`/ai/messages/${conversationId}`);
+        return data;
+    }
+    /**
+     * Deleta uma conversa e todo seu histórico.
+     *
+     * @example
+     * await aether.ai.conversations.delete(conversationId);
+     */
+    async delete(conversationId) {
+        const { data } = await this.http.delete(`/ai/conversations/${conversationId}`);
+        return data;
+    }
+    /**
+     * Renomeia uma conversa.
+     *
+     * @example
+     * await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
+     */
+    async rename(conversationId, title) {
+        const { data } = await this.http.patch(`/ai/conversations/${conversationId}`, {
+            title
+        });
+        return data;
+    }
+}
+// =============================================================================
+// SUB-MÓDULO: ADMIN
+// =============================================================================
+class AIAdminAPI {
+    constructor(client, http) {
+        this.client = client;
+        this.http = http;
+    }
+    /**
+     * Reindexa todos os dados do projeto para RAG.
+     * Use após adicionar/modificar grandes volumes de dados.
+     * Executa em background.
+     *
+     * @example
+     * await aether.ai.admin.reindex();
+     */
+    async reindex() {
+        const { data } = await this.http.post('/ai/reindex', {
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+    /**
+     * Limpa todos os embeddings do projeto.
+     * CUIDADO: A IA "esquece" todo o contexto aprendido.
+     *
+     * @example
+     * const { deletedCount } = await aether.ai.admin.clear();
+     */
+    async clear() {
+        const { data } = await this.http.post('/ai/clear', {
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+    /**
+     * Retorna estatísticas de uso da IA.
+     *
+     * @example
+     * const stats = await aether.ai.admin.stats();
+     * console.log(stats.totalConversations, stats.totalMessages);
+     */
+    async stats() {
+        const { data } = await this.http.get('/ai/stats', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+    /**
+     * Configura quais collections são indexadas automaticamente.
+     *
+     * @example
+     * await aether.ai.admin.setIndexedCollections(['products', 'articles', 'faq']);
+     */
+    async setIndexedCollections(collections) {
+        const { data } = await this.http.post('/ai/config/collections', {
+            projectId: this.client.projectId,
+            collections
+        });
+        return data;
+    }
+    /**
+     * Busca configurações atuais de IA do projeto.
+     */
+    async getConfig() {
+        const { data } = await this.http.get('/ai/config', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allanfsouza/aether-sdk",
-  "version": "2.4.10",
+  "version": "2.4.11",
   "description": "SDK do Cliente para a Plataforma Aether",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/ai.ts

@@ -0,0 +1,580 @@
+// src/ai.ts
+// [NOVO] Módulo de IA do Aether SDK
+// Permite que clientes adicionem IA aos seus apps com poucas linhas de código
+// Data: Dezembro 2025
+
+import type { AxiosInstance } from "axios";
+import type { PlataformaClient } from "./index.js";
+
+// =============================================================================
+// TIPOS
+// =============================================================================
+
+/**
+ * Opções para o método chat()
+ */
+export interface ChatOptions {
+    /** ID da conversa para manter contexto entre mensagens */
+    conversationId?: string;
+
+    /** Contexto adicional (ex: "vendas", "suporte", "produtos") */
+    context?: string;
+
+    /** Callback chamado a cada chunk de texto recebido (streaming) */
+    onChunk?: (chunk: string) => void;
+
+    /** Callback chamado quando a resposta completa é recebida */
+    onComplete?: (fullResponse: string, metadata: ChatMetadata) => void;
+
+    /** Callback chamado em caso de erro */
+    onError?: (error: Error) => void;
+
+    /** Timeout em ms (padrão: 30000) */
+    timeout?: number;
+}
+
+/**
+ * Metadados retornados após uma resposta completa
+ */
+export interface ChatMetadata {
+    conversationId: string;
+    messageId?: string;
+    tokensUsed?: number;
+    sources?: RetrievedSource[];
+}
+
+/**
+ * Fonte de dados usada pelo RAG
+ */
+export interface RetrievedSource {
+    type: string;
+    content: string;
+    similarity: number;
+}
+
+/**
+ * Resposta do método ask()
+ */
+export interface AskResponse {
+    text: string;
+    conversationId: string;
+    sources?: RetrievedSource[];
+}
+
+/**
+ * Conversa persistida
+ */
+export interface Conversation {
+    id: string;
+    title: string;
+    context: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount?: number;
+}
+
+/**
+ * Mensagem de uma conversa
+ */
+export interface Message {
+    id: string;
+    conversationId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    metadata?: Record<string, any>;
+    createdAt: string;
+}
+
+/**
+ * Tipo de feedback
+ */
+export type FeedbackType = 'thumbs_up' | 'thumbs_down';
+
+/**
+ * Opções para busca semântica
+ */
+export interface SemanticSearchOptions {
+    /** Número máximo de resultados (padrão: 10) */
+    limit?: number;
+
+    /** Score mínimo de similaridade 0-1 (padrão: 0.5) */
+    minScore?: number;
+
+    /** Filtrar por collection específica */
+    collection?: string;
+}
+
+/**
+ * Resultado de busca semântica
+ */
+export interface SemanticSearchResult {
+    id: string;
+    content: string;
+    collection: string;
+    similarity: number;
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Opções para geração de conteúdo
+ */
+export interface GenerateOptions {
+    /** Tom do texto (formal, casual, técnico, etc) */
+    tone?: 'formal' | 'casual' | 'technical' | 'friendly';
+
+    /** Tamanho aproximado (short, medium, long) */
+    length?: 'short' | 'medium' | 'long';
+
+    /** Idioma (padrão: pt-BR) */
+    language?: string;
+
+    /** Contexto adicional para a geração */
+    context?: string;
+}
+
+// =============================================================================
+// MÓDULO PRINCIPAL
+// =============================================================================
+
+export class AIModule {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    /** Sub-módulo para gerenciar conversas */
+    public conversations: ConversationsAPI;
+
+    /** Sub-módulo para funções administrativas */
+    public admin: AIAdminAPI;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+        this.conversations = new ConversationsAPI(client, http);
+        this.admin = new AIAdminAPI(client, http);
+    }
+
+    // ===========================================================================
+    // MÉTODOS PRINCIPAIS
+    // ===========================================================================
+
+    /**
+     * Faz uma pergunta simples e aguarda a resposta completa.
+     * Ideal para quando não precisa de streaming.
+     * 
+     * @example
+     * const { text } = await aether.ai.ask("Quais produtos estão em promoção?");
+     * console.log(text);
+     */
+    async ask(message: string, conversationId?: string): Promise<AskResponse> {
+        return new Promise((resolve, reject) => {
+            let fullText = '';
+            let metadata: ChatMetadata = { conversationId: conversationId || '' };
+
+            this.chat(message, {
+                conversationId,
+                onChunk: (chunk) => {
+                    fullText += chunk;
+                },
+                onComplete: (response, meta) => {
+                    metadata = meta;
+                    resolve({
+                        text: fullText,
+                        conversationId: meta.conversationId,
+                        sources: meta.sources
+                    });
+                },
+                onError: reject
+            }).catch(reject);
+        });
+    }
+
+    /**
+     * Inicia um chat com streaming de resposta.
+     * A resposta chega em chunks conforme a IA gera.
+     * 
+     * @example
+     * await aether.ai.chat("Explique como funciona o sistema de pagamentos", {
+     *   onChunk: (chunk) => {
+     *     // Atualiza UI em tempo real
+     *     setResponse(prev => prev + chunk);
+     *   },
+     *   onComplete: (full, meta) => {
+     *     console.log("Conversa ID:", meta.conversationId);
+     *   }
+     * });
+     */
+    async chat(message: string, options: ChatOptions = {}): Promise<void> {
+        const projectId = this.client.projectId;
+        const token = this.client.getToken();
+
+        if (!token) {
+            const error = new Error('Usuário não autenticado. Faça login primeiro.');
+            if (options.onError) {
+                options.onError(error);
+                return;
+            }
+            throw error;
+        }
+
+        const timeout = options.timeout || 30000;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+        try {
+            const response = await fetch(`${this.client.apiUrl}/v1/ai/chat`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${token}`,
+                    'X-Project-ID': projectId
+                },
+                body: JSON.stringify({
+                    message,
+                    projectId,
+                    conversationId: options.conversationId,
+                    context: options.context || 'general'
+                }),
+                signal: controller.signal
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Erro na API: ${response.status} - ${errorText}`);
+            }
+
+            // Captura conversation ID do header (se disponível)
+            const convIdFromHeader = response.headers.get('X-Conversation-ID');
+
+            // Processa o stream
+            const reader = response.body?.getReader();
+            const decoder = new TextDecoder();
+            let fullResponse = '';
+
+            if (!reader) {
+                throw new Error('Stream não disponível');
+            }
+
+            while (true) {
+                const { done, value } = await reader.read();
+
+                if (done) break;
+
+                const chunk = decoder.decode(value, { stream: true });
+                fullResponse += chunk;
+
+                if (options.onChunk) {
+                    options.onChunk(chunk);
+                }
+            }
+
+            // Callback de conclusão
+            if (options.onComplete) {
+                options.onComplete(fullResponse, {
+                    conversationId: convIdFromHeader || options.conversationId || '',
+                });
+            }
+
+        } catch (error: any) {
+            clearTimeout(timeoutId);
+
+            if (error.name === 'AbortError') {
+                error = new Error(`Timeout: A requisição excedeu ${timeout}ms`);
+            }
+
+            if (options.onError) {
+                options.onError(error);
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Envia feedback sobre uma resposta da IA.
+     * Ajuda a melhorar as respostas futuras.
+     * 
+     * @example
+     * await aether.ai.feedback(messageId, 'thumbs_up');
+     * await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');
+     */
+    async feedback(
+        messageId: string,
+        type: FeedbackType,
+        comment?: string
+    ): Promise<{ success: boolean }> {
+        const { data } = await this.http.post('/ai/feedback', {
+            messageId,
+            feedbackType: type,
+            comment
+        });
+        return data;
+    }
+
+    // ===========================================================================
+    // BUSCA SEMÂNTICA
+    // ===========================================================================
+
+    /**
+     * Busca semântica nos dados do projeto.
+     * Encontra documentos similares usando embeddings.
+     * 
+     * @example
+     * // Busca produtos similares a uma descrição
+     * const results = await aether.ai.search("tênis confortável para corrida");
+     * 
+     * // Com filtros
+     * const results = await aether.ai.search("problema no login", {
+     *   collection: "support_tickets",
+     *   limit: 5,
+     *   minScore: 0.7
+     * });
+     */
+    async search(
+        query: string,
+        options: SemanticSearchOptions = {}
+    ): Promise<SemanticSearchResult[]> {
+        const { data } = await this.http.post('/ai/search', {
+            query,
+            projectId: this.client.projectId,
+            limit: options.limit || 10,
+            minScore: options.minScore || 0.5,
+            collection: options.collection
+        });
+        return data.results;
+    }
+
+    // ===========================================================================
+    // GERAÇÃO DE CONTEÚDO
+    // ===========================================================================
+
+    /**
+     * Gera texto baseado em um prompt e contexto.
+     * Útil para descrições de produtos, resumos, etc.
+     * 
+     * @example
+     * // Gerar descrição de produto
+     * const descricao = await aether.ai.generate(
+     *   "Escreva uma descrição para o produto",
+     *   { productName: "iPhone 15", price: 5999, features: ["5G", "48MP"] },
+     *   { tone: 'friendly', length: 'medium' }
+     * );
+     */
+    async generate(
+        prompt: string,
+        data: Record<string, any>,
+        options: GenerateOptions = {}
+    ): Promise<string> {
+        const { data: response } = await this.http.post('/ai/generate', {
+            prompt,
+            data,
+            projectId: this.client.projectId,
+            tone: options.tone || 'friendly',
+            length: options.length || 'medium',
+            language: options.language || 'pt-BR',
+            context: options.context
+        });
+        return response.text;
+    }
+
+    // ===========================================================================
+    // ANÁLISE DE DADOS
+    // ===========================================================================
+
+    /**
+     * Analisa dados e retorna insights em linguagem natural.
+     * 
+     * @example
+     * const insights = await aether.ai.analyze("orders", {
+     *   question: "Como foram as vendas essa semana?",
+     *   period: "7d"
+     * });
+     */
+    async analyze(
+        collection: string,
+        options: { question: string; period?: string }
+    ): Promise<{ insights: string; data?: any }> {
+        const { data } = await this.http.post('/ai/analyze', {
+            collection,
+            projectId: this.client.projectId,
+            question: options.question,
+            period: options.period || '7d'
+        });
+        return data;
+    }
+
+    /**
+     * Processa linguagem natural e converte em query estruturada.
+     * Útil para criar filtros de busca baseados em texto do usuário.
+     * 
+     * @example
+     * const query = await aether.ai.parseQuery(
+     *   "produtos vermelhos acima de 100 reais ordenados por preço"
+     * );
+     * // Retorna: { filter: { color: 'vermelho', price: { $gt: 100 } }, sort: { price: 'ASC' } }
+     */
+    async parseQuery(
+        naturalLanguage: string,
+        collection?: string
+    ): Promise<{ filter?: Record<string, any>; sort?: Record<string, any> }> {
+        const { data } = await this.http.post('/ai/parse-query', {
+            query: naturalLanguage,
+            collection,
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+}
+
+// =============================================================================
+// SUB-MÓDULO: CONVERSAS
+// =============================================================================
+
+class ConversationsAPI {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+    }
+
+    /**
+     * Lista todas as conversas do usuário no projeto.
+     * 
+     * @example
+     * const conversas = await aether.ai.conversations.list();
+     */
+    async list(): Promise<Conversation[]> {
+        const { data } = await this.http.get('/ai/conversations', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+
+    /**
+     * Busca o histórico de mensagens de uma conversa.
+     * 
+     * @example
+     * const mensagens = await aether.ai.conversations.getMessages(conversationId);
+     */
+    async getMessages(conversationId: string): Promise<Message[]> {
+        const { data } = await this.http.get(`/ai/messages/${conversationId}`);
+        return data;
+    }
+
+    /**
+     * Deleta uma conversa e todo seu histórico.
+     * 
+     * @example
+     * await aether.ai.conversations.delete(conversationId);
+     */
+    async delete(conversationId: string): Promise<{ success: boolean }> {
+        const { data } = await this.http.delete(`/ai/conversations/${conversationId}`);
+        return data;
+    }
+
+    /**
+     * Renomeia uma conversa.
+     * 
+     * @example
+     * await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
+     */
+    async rename(conversationId: string, title: string): Promise<Conversation> {
+        const { data } = await this.http.patch(`/ai/conversations/${conversationId}`, {
+            title
+        });
+        return data;
+    }
+}
+
+// =============================================================================
+// SUB-MÓDULO: ADMIN
+// =============================================================================
+
+class AIAdminAPI {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+    }
+
+    /**
+     * Reindexa todos os dados do projeto para RAG.
+     * Use após adicionar/modificar grandes volumes de dados.
+     * Executa em background.
+     * 
+     * @example
+     * await aether.ai.admin.reindex();
+     */
+    async reindex(): Promise<{ message: string }> {
+        const { data } = await this.http.post('/ai/reindex', {
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+
+    /**
+     * Limpa todos os embeddings do projeto.
+     * CUIDADO: A IA "esquece" todo o contexto aprendido.
+     * 
+     * @example
+     * const { deletedCount } = await aether.ai.admin.clear();
+     */
+    async clear(): Promise<{ deletedCount: number }> {
+        const { data } = await this.http.post('/ai/clear', {
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+
+    /**
+     * Retorna estatísticas de uso da IA.
+     * 
+     * @example
+     * const stats = await aether.ai.admin.stats();
+     * console.log(stats.totalConversations, stats.totalMessages);
+     */
+    async stats(): Promise<{
+        totalConversations: number;
+        totalMessages: number;
+        totalEmbeddings: number;
+        storageUsedMB: number;
+    }> {
+        const { data } = await this.http.get('/ai/stats', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+
+    /**
+     * Configura quais collections são indexadas automaticamente.
+     * 
+     * @example
+     * await aether.ai.admin.setIndexedCollections(['products', 'articles', 'faq']);
+     */
+    async setIndexedCollections(collections: string[]): Promise<{ success: boolean }> {
+        const { data } = await this.http.post('/ai/config/collections', {
+            projectId: this.client.projectId,
+            collections
+        });
+        return data;
+    }
+
+    /**
+     * Busca configurações atuais de IA do projeto.
+     */
+    async getConfig(): Promise<{
+        indexedCollections: string[];
+        autoIndex: boolean;
+        embeddingModel: string;
+    }> {
+        const { data } = await this.http.get('/ai/config', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+}