vectorgov 0.2.0 → 0.3.0

package/README.md

@@ -181,6 +181,152 @@ await vg.feedback(results.metadata.queryId, true);
 await vg.feedback(results.metadata.queryId, false);
 ```
 
+## Streaming
+
+```typescript
+// Resposta em tempo real com Server-Sent Events
+for await (const chunk of vg.askStream('O que é ETP?')) {
+  if (chunk.type === 'token') {
+    process.stdout.write(chunk.content || '');
+  } else if (chunk.type === 'complete') {
+    console.log('\n\nCitações:', chunk.citations);
+  }
+}
+```
+
+## System Prompts
+
+```typescript
+// Ver prompts disponíveis
+console.log(vg.availablePrompts); // ['default', 'concise', 'detailed', 'chatbot']
+
+// Obter prompt específico
+const prompt = vg.getSystemPrompt('detailed');
+
+// Usar com seu LLM
+const results = await vg.search('O que é ETP?');
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [
+    { role: 'system', content: prompt + '\n\n' + results.toContext() },
+    { role: 'user', content: 'O que é ETP?' }
+  ]
+});
+```
+
+## Function Calling (Agentes)
+
+Use VectorGov como ferramenta em agentes de IA:
+
+### OpenAI Function Calling
+
+```typescript
+const tools = [vg.toOpenAITool()];
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Pesquise sobre ETP' }],
+  tools,
+  tool_choice: 'auto'
+});
+
+// Se o modelo chamou a ferramenta
+const toolCall = response.choices[0].message.tool_calls?.[0];
+if (toolCall) {
+  const result = await vg.executeToolCall(toolCall);
+  console.log(result);
+}
+```
+
+### Anthropic Claude Tools
+
+```typescript
+const tools = [vg.toAnthropicTool()];
+
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  tools,
+  messages: [{ role: 'user', content: 'Pesquise sobre ETP' }]
+});
+```
+
+### Google Gemini Tools
+
+```typescript
+const tools = [vg.toGoogleTool()];
+// Use com a API do Gemini
+```
+
+## BYOLLM (Bring Your Own LLM)
+
+Armazene respostas geradas pelo seu próprio LLM para analytics:
+
+```typescript
+const results = await vg.search('O que é ETP?');
+
+// Gere resposta com seu LLM
+const myResponse = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: results.toMessages('O que é ETP?')
+});
+
+// Armazene para analytics
+await vg.storeResponse({
+  query: 'O que é ETP?',
+  answer: myResponse.choices[0].message.content!,
+  provider: 'OpenAI',
+  model: 'gpt-4',
+  chunksUsed: results.hits.length,
+  latencyMs: 1500
+});
+```
+
+## Gestão de Documentos
+
+```typescript
+// Listar documentos disponíveis
+const docs = await vg.listDocuments();
+for (const doc of docs.documents) {
+  console.log(`${doc.tipoDocumento} ${doc.numero}/${doc.ano}: ${doc.chunksCount} chunks`);
+}
+
+// Detalhes de um documento
+const doc = await vg.getDocument('LEI-14133-2021');
+
+// Verificar status de ingestão
+const status = await vg.getIngestStatus('task-id-123');
+
+// Iniciar enriquecimento
+await vg.startEnrichment('LEI-14133-2021');
+
+// Verificar status de enriquecimento
+const enrichStatus = await vg.getEnrichmentStatus('LEI-14133-2021');
+
+// Deletar documento
+await vg.deleteDocument('LEI-14133-2021');
+```
+
+## Logs de Auditoria
+
+```typescript
+// Listar logs de auditoria
+const logs = await vg.getAuditLogs({
+  limit: 50,
+  severity: 'warning',
+  eventType: 'pii_detected'
+});
+
+for (const log of logs.logs) {
+  console.log(`${log.createdAt}: ${log.eventType} - ${log.severity}`);
+}
+
+// Estatísticas de auditoria
+const stats = await vg.getAuditStats(30); // últimos 30 dias
+console.log(`Total eventos: ${stats.totalEvents}`);
+console.log(`Bloqueados: ${stats.blockedCount}`);
+```
+
 ## Tratamento de Erros
 
 ```typescript
@@ -229,7 +375,23 @@ const vg = new VectorGov({
 |--------|-----------|
 | `search(query, options?)` | Busca semântica |
 | `ask(query, options?)` | Pergunta com resposta IA |
+| `askStream(query, options?)` | Pergunta com streaming |
 | `feedback(queryId, like)` | Envia feedback |
+| `storeResponse(options)` | Armazena resposta do seu LLM |
+| `getSystemPrompt(style)` | Obtém system prompt |
+| `availablePrompts` | Lista prompts disponíveis |
+| `toOpenAITool()` | Ferramenta para OpenAI |
+| `toAnthropicTool()` | Ferramenta para Anthropic |
+| `toGoogleTool()` | Ferramenta para Google |
+| `executeToolCall(toolCall)` | Executa chamada de ferramenta |
+| `listDocuments(options?)` | Lista documentos |
+| `getDocument(documentId)` | Detalhes de documento |
+| `getIngestStatus(taskId)` | Status de ingestão |
+| `startEnrichment(documentId)` | Inicia enriquecimento |
+| `getEnrichmentStatus(documentId)` | Status de enriquecimento |
+| `deleteDocument(documentId)` | Remove documento |
+| `getAuditLogs(options?)` | Logs de auditoria |
+| `getAuditStats(days?)` | Estatísticas de auditoria |
 
 ### SearchOptions
 

package/dist/index.d.mts

@@ -213,6 +213,175 @@ interface AuditLogsOptions {
     /** Data final (ISO 8601) */
     endDate?: string;
 }
+/** Opções para armazenar resposta de LLM externo */
+interface StoreResponseOptions {
+    /** Pergunta original */
+    query: string;
+    /** Resposta gerada pelo LLM */
+    answer: string;
+    /** Provedor do LLM (ex: "OpenAI", "Google", "Anthropic") */
+    provider: string;
+    /** Modelo usado (ex: "gpt-4o", "gemini-2.0-flash") */
+    model: string;
+    /** Quantidade de chunks usados como contexto */
+    chunksUsed?: number;
+    /** Latência total em ms */
+    latencyMs?: number;
+    /** Tempo de busca em ms */
+    retrievalMs?: number;
+    /** Tempo de geração em ms */
+    generationMs?: number;
+}
+/** Resultado do armazenamento de resposta */
+interface StoreResponseResult {
+    /** Se foi armazenado com sucesso */
+    success: boolean;
+    /** Hash da query para uso em feedback */
+    queryHash: string;
+    /** Mensagem de status */
+    message: string;
+}
+/** Chunk de resposta em streaming */
+interface StreamChunk {
+    /** Tipo do chunk (start, token, complete, error) */
+    type: 'start' | 'token' | 'complete' | 'error';
+    /** Conteúdo do chunk (token ou mensagem) */
+    content?: string;
+    /** Query original (em start) */
+    query?: string;
+    /** Chunks usados (em start) */
+    chunks?: number;
+    /** Tempo em ms (em complete) */
+    timeMs?: number;
+    /** Citações (em complete) */
+    citations?: Citation[];
+    /** Hash da query (em complete) */
+    queryHash?: string;
+    /** Mensagem de erro (em error) */
+    message?: string;
+}
+/** Resumo de um documento */
+interface DocumentSummary {
+    /** ID único do documento */
+    documentId: string;
+    /** Tipo do documento (LEI, DECRETO, IN, etc) */
+    tipoDocumento: string;
+    /** Número do documento */
+    numero: string;
+    /** Ano do documento */
+    ano: number;
+    /** Título do documento */
+    titulo?: string;
+    /** Descrição/ementa */
+    descricao?: string;
+    /** Quantidade de chunks */
+    chunksCount: number;
+    /** Quantidade de chunks enriquecidos */
+    enrichedCount: number;
+}
+/** Resposta da listagem de documentos */
+interface DocumentsResponse {
+    /** Lista de documentos */
+    documents: DocumentSummary[];
+    /** Total de documentos */
+    total: number;
+    /** Página atual */
+    page: number;
+    /** Total de páginas */
+    pages: number;
+}
+/** Opções para listagem de documentos */
+interface ListDocumentsOptions {
+    /** Página (padrão: 1) */
+    page?: number;
+    /** Limite por página (padrão: 20) */
+    limit?: number;
+}
+/** Resposta de upload */
+interface UploadResponse {
+    /** Se foi iniciado com sucesso */
+    success: boolean;
+    /** Mensagem de status */
+    message: string;
+    /** ID do documento criado */
+    documentId: string;
+    /** ID da task de ingestão */
+    taskId: string;
+}
+/** Status de ingestão */
+interface IngestStatus {
+    /** ID da task */
+    taskId: string;
+    /** Status (pending, processing, completed, failed) */
+    status: string;
+    /** Progresso (0-100) */
+    progress: number;
+    /** Mensagem de status */
+    message: string;
+    /** ID do documento */
+    documentId?: string;
+    /** Chunks criados */
+    chunksCreated: number;
+}
+/** Status de enriquecimento */
+interface EnrichStatus {
+    /** ID da task */
+    taskId: string;
+    /** Status (pending, processing, completed, failed) */
+    status: string;
+    /** Progresso (0-100) */
+    progress: number;
+    /** Chunks enriquecidos */
+    chunksEnriched: number;
+    /** Chunks pendentes */
+    chunksPending: number;
+    /** Chunks com erro */
+    chunksFailed: number;
+    /** Lista de erros */
+    errors: string[];
+}
+/** Resposta de deleção */
+interface DeleteResponse {
+    /** Se foi deletado com sucesso */
+    success: boolean;
+    /** Mensagem de status */
+    message: string;
+}
+/** Definição de ferramenta para OpenAI */
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+}
+/** Definição de ferramenta para Anthropic */
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/** Definição de ferramenta para Google Gemini */
+interface GoogleTool {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/** Estilos de system prompt disponíveis */
+type SystemPromptStyle = 'default' | 'concise' | 'detailed' | 'chatbot';
 
 /**
  * VectorGov SDK Client
@@ -271,6 +440,25 @@ declare class VectorGov {
      * @returns Resposta com citações
      */
     ask(query: string, options?: AskOptions): Promise<AskResponse>;
+    /**
+     * Faz uma pergunta com resposta em streaming
+     *
+     * @param query - Pergunta do usuário
+     * @param options - Opções de busca
+     * @yields StreamChunk com cada parte da resposta
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of vg.askStream('O que é ETP?')) {
+     *   if (chunk.type === 'token') {
+     *     process.stdout.write(chunk.content || '');
+     *   } else if (chunk.type === 'complete') {
+     *     console.log(`\n\nFontes: ${chunk.citations?.length} citações`);
+     *   }
+     * }
+     * ```
+     */
+    askStream(query: string, options?: SearchOptions): AsyncGenerator<StreamChunk>;
     /**
      * Envia feedback (like/dislike) para uma resposta
      *
@@ -279,13 +467,174 @@ declare class VectorGov {
      */
     feedback(queryId: string, like: boolean): Promise<FeedbackResponse>;
     /**
-     * Converte hits para formato de mensagens de chat
+     * Armazena resposta de LLM externo no cache do VectorGov
+     *
+     * Use quando você gera uma resposta com seu próprio LLM e quer:
+     * 1. Habilitar o sistema de feedback (like/dislike)
+     * 2. Contribuir para melhorias futuras
+     *
+     * @param options - Dados da resposta
+     * @returns Resultado com queryHash para usar em feedback()
+     *
+     * @example
+     * ```typescript
+     * // 1. Busca no VectorGov
+     * const results = await vg.search('O que é ETP?');
+     *
+     * // 2. Gera resposta com seu LLM
+     * const answer = await openai.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: results.toMessages('O que é ETP?')
+     * });
+     *
+     * // 3. Salva no VectorGov
+     * const stored = await vg.storeResponse({
+     *   query: 'O que é ETP?',
+     *   answer: answer.choices[0].message.content,
+     *   provider: 'OpenAI',
+     *   model: 'gpt-4o',
+     *   chunksUsed: results.hits.length
+     * });
+     *
+     * // 4. Agora pode receber feedback
+     * await vg.feedback(stored.queryHash, true);
+     * ```
      */
-    private hitsToMessages;
+    storeResponse(options: StoreResponseOptions): Promise<StoreResponseResult>;
     /**
-     * Converte hits para texto de contexto
+     * Retorna um system prompt pré-definido
+     *
+     * @param style - Estilo do prompt (default, concise, detailed, chatbot)
+     * @returns String com o system prompt
+     *
+     * @example
+     * ```typescript
+     * const prompt = vg.getSystemPrompt('detailed');
+     * const messages = results.toMessages('query');
+     * messages[0].content = prompt; // Substitui o system prompt
+     * ```
      */
-    private hitsToContext;
+    getSystemPrompt(style?: SystemPromptStyle): string;
+    /**
+     * Lista os estilos de system prompt disponíveis
+     */
+    get availablePrompts(): SystemPromptStyle[];
+    /**
+     * Retorna a ferramenta VectorGov no formato OpenAI Function Calling
+     *
+     * @example
+     * ```typescript
+     * const response = await openai.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: [...],
+     *   tools: [vg.toOpenAITool()],
+     * });
+     * ```
+     */
+    toOpenAITool(): OpenAITool;
+    /**
+     * Retorna a ferramenta VectorGov no formato Anthropic Claude Tools
+     *
+     * @example
+     * ```typescript
+     * const response = await anthropic.messages.create({
+     *   model: 'claude-sonnet-4-20250514',
+     *   messages: [...],
+     *   tools: [vg.toAnthropicTool()],
+     * });
+     * ```
+     */
+    toAnthropicTool(): AnthropicTool;
+    /**
+     * Retorna a ferramenta VectorGov no formato Google Gemini
+     *
+     * @example
+     * ```typescript
+     * const model = genai.GenerativeModel({
+     *   model: 'gemini-2.0-flash',
+     *   tools: [vg.toGoogleTool()],
+     * });
+     * ```
+     */
+    toGoogleTool(): GoogleTool;
+    /**
+     * Executa uma chamada de ferramenta e retorna o resultado formatado
+     *
+     * @param toolCall - Objeto de tool_call do LLM (OpenAI, Anthropic ou dict)
+     * @param mode - Modo de busca opcional
+     * @returns String formatada com os resultados
+     *
+     * @example
+     * ```typescript
+     * // OpenAI
+     * if (response.choices[0].message.tool_calls) {
+     *   const toolCall = response.choices[0].message.tool_calls[0];
+     *   const result = await vg.executeToolCall(toolCall);
+     *   // Passa result de volta para o LLM
+     * }
+     *
+     * // Anthropic
+     * for (const block of response.content) {
+     *   if (block.type === 'tool_use') {
+     *     const result = await vg.executeToolCall(block);
+     *   }
+     * }
+     * ```
+     */
+    executeToolCall(toolCall: unknown, mode?: SearchOptions['mode']): Promise<string>;
+    /**
+     * Extrai argumentos de diferentes formatos de tool_call
+     */
+    private extractToolArguments;
+    /**
+     * Formata resultado da busca para retornar ao LLM
+     */
+    private formatToolResponse;
+    /**
+     * Lista os documentos disponíveis
+     *
+     * @param options - Opções de paginação
+     * @returns Lista paginada de documentos
+     */
+    listDocuments(options?: ListDocumentsOptions): Promise<DocumentsResponse>;
+    /**
+     * Obtém detalhes de um documento específico
+     *
+     * @param documentId - ID do documento
+     * @returns Detalhes do documento
+     */
+    getDocument(documentId: string): Promise<DocumentSummary>;
+    /**
+     * Obtém o status de uma ingestão
+     *
+     * @param taskId - ID da task de ingestão
+     * @returns Status da ingestão
+     */
+    getIngestStatus(taskId: string): Promise<IngestStatus>;
+    /**
+     * Inicia o enriquecimento de um documento
+     *
+     * @param documentId - ID do documento
+     * @returns ID da task de enriquecimento
+     */
+    startEnrichment(documentId: string): Promise<{
+        taskId: string;
+        message: string;
+    }>;
+    /**
+     * Obtém o status de um enriquecimento
+     *
+     * @param taskId - ID da task de enriquecimento
+     * @returns Status do enriquecimento
+     */
+    getEnrichmentStatus(taskId: string): Promise<EnrichStatus>;
+    /**
+     * Deleta um documento
+     *
+     * @param documentId - ID do documento
+     * @returns Resultado da deleção
+     */
+    deleteDocument(documentId: string): Promise<DeleteResponse>;
     /**
      * Obtém os logs de auditoria da conta
      *
@@ -342,6 +691,14 @@ declare class VectorGov {
      * ```
      */
     getAuditEventTypes(): Promise<string[]>;
+    /**
+     * Converte hits para formato de mensagens de chat
+     */
+    private hitsToMessages;
+    /**
+     * Converte hits para texto de contexto
+     */
+    private hitsToContext;
 }
 
-export { type AskMetadata, type AskOptions, type AskResponse, type AuditLog, type AuditLogsOptions, type AuditLogsResponse, type AuditStats, AuthenticationError, type ChatMessage, type Citation, type FeedbackResponse, RateLimitError, type SearchHit, type SearchMetadata, type SearchMode, type SearchOptions, type SearchResult, VectorGov, type VectorGovConfig, VectorGovError };
+export { type AnthropicTool, type AskMetadata, type AskOptions, type AskResponse, type AuditLog, type AuditLogsOptions, type AuditLogsResponse, type AuditStats, AuthenticationError, type ChatMessage, type Citation, type DeleteResponse, type DocumentSummary, type DocumentsResponse, type EnrichStatus, type FeedbackResponse, type GoogleTool, type IngestStatus, type ListDocumentsOptions, type OpenAITool, RateLimitError, type SearchHit, type SearchMetadata, type SearchMode, type SearchOptions, type SearchResult, type StoreResponseOptions, type StoreResponseResult, type StreamChunk, type SystemPromptStyle, type UploadResponse, VectorGov, type VectorGovConfig, VectorGovError };