@adonis-agora/agent/dist/src/rag/ingest.d.ts

Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.

import { type EmbeddingProvider, type EmbeddingUsage } from '../spi/embedding-provider.js';
import { type ChunkOptions } from './chunk.js';
import type { VectorStore } from './vector-store.js';
/** A source document to ingest. `id` scopes the chunk ids (`${id}#${n}`); `source` is the citation. */
export interface IngestDocument {
    id: string;
    text: string;
    source?: string;
    metadata?: Record<string, unknown>;
}
/** A chunked, not-yet-embedded record. */
export interface ChunkRecord {
    id: string;
    text: string;
    source?: string;
    metadata?: Record<string, unknown>;
}
export interface IngestChunksOptions {
    embedder: EmbeddingProvider;
    store: VectorStore;
    /**
     * Chamado com o consumo do lote, quando o provider sabe reportar.
     *
     * É um CALLBACK e não uma gravação no ledger, e a razão é estrutural:
     * `agent_token_usage.thread_id` é NOT NULL com FK para as threads, e uma indexação em lote não
     * acontece dentro de conversa nenhuma. Gravar exigiria afrouxar a FK — decisão de esquema que
     * não cabe num callback de ingestão.
     *
     * Então o gasto de ingestão fica OBSERVÁVEL aqui, para o host contabilizar como preferir (uma
     * métrica, uma tabela própria), em vez de invisível como era. O gasto de RETRIEVAL, que é o
     * recorrente, esse vai para o ledger sozinho — ver o loop.
     */
    onUsage?: (usage: EmbeddingUsage) => void | Promise<void>;
}
export interface IngestOptions extends ChunkOptions, IngestChunksOptions {
}
/**
 * Split documents into chunk records. Chunk ids are `${doc.id}#${index}`, so re-chunking the same
 * document produces the same ids (upsert overwrites in place rather than duplicating).
 */
export declare function chunkDocuments(documents: IngestDocument[], options?: ChunkOptions): ChunkRecord[];
/** Embed pre-chunked records (one batched `embed`) and upsert them. Returns the record count. */
export declare function ingestChunks(chunks: ChunkRecord[], options: IngestChunksOptions): Promise<number>;
/** Chunk → embed → upsert in one call. Returns the number of chunks indexed. */
export declare function ingestDocuments(documents: IngestDocument[], options: IngestOptions): Promise<number>;
//# sourceMappingURL=ingest.d.ts.map