vectorgov 0.3.0 → 0.5.0

package/README.md

@@ -145,6 +145,42 @@ const balanced = await vg.search('O que é ETP?', { mode: 'balanced' });
 const precise = await vg.search('O que é ETP?', { mode: 'precise' });
 ```
 
+> **Importante:** O modo de busca **não afeta** a quantidade de tokens enviados ao seu LLM. Todos os modos retornam o mesmo número de resultados (controlado por `topK`). A diferença está na **qualidade** dos resultados:
+> - **HyDE** (modo `precise`): Gera documentos hipotéticos para melhorar a busca - processamento extra no backend VectorGov
+> - **Reranker** (modos `balanced` e `precise`): Reordena resultados por relevância - processamento extra no backend VectorGov
+>
+> Ou seja: você recebe resultados **mais relevantes**, não **mais resultados**.
+
+## Estimativa de Tokens
+
+Planeje o uso de contexto com estimativa de tokens antes de enviar para seu LLM:
+
+```typescript
+const results = await vg.search('O que é ETP?', { topK: 5 });
+
+// Estima tokens do contexto
+const stats = await vg.estimateTokens(results);
+
+console.log(`Tokens de contexto: ${stats.contextTokens}`);
+console.log(`Tokens de sistema: ${stats.systemTokens}`);
+console.log(`Total: ${stats.totalTokens}`);
+console.log(`Caracteres: ${stats.charCount}`);
+console.log(`Encoding: ${stats.encoding}`);
+
+// Verificar se cabe no limite do modelo
+if (stats.totalTokens > 4000) {
+  // Reduzir contexto
+  const smaller = await vg.search('O que é ETP?', { topK: 3 });
+  const smallerStats = await vg.estimateTokens(smaller);
+  console.log(`Novo total: ${smallerStats.totalTokens}`);
+}
+
+// Com system prompt customizado
+const customStats = await vg.estimateTokens(results, {
+  systemPrompt: 'Você é um especialista jurídico...'
+});
+```
+
 ## Filtros
 
 ```typescript
@@ -155,20 +191,6 @@ const results = await vg.search('dispensa de licitação', {
 });
 ```
 
-## Perguntas com Resposta
-
-```typescript
-// Usa o LLM do VectorGov para gerar resposta
-const response = await vg.ask('O que é ETP?');
-
-console.log(response.answer);
-console.log(`Confiança: ${(response.confidence * 100).toFixed(1)}%`);
-
-for (const citation of response.citations) {
-  console.log(`  - ${citation.short}`);
-}
-```
-
 ## Feedback
 
 ```typescript
@@ -181,19 +203,6 @@ 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
@@ -374,9 +383,8 @@ const vg = new VectorGov({
 | Método | Descrição |
 |--------|-----------|
 | `search(query, options?)` | Busca semântica |
-| `ask(query, options?)` | Pergunta com resposta IA |
-| `askStream(query, options?)` | Pergunta com streaming |
 | `feedback(queryId, like)` | Envia feedback |
+| `estimateTokens(content, options?)` | Estima tokens para LLM |
 | `storeResponse(options)` | Armazena resposta do seu LLM |
 | `getSystemPrompt(style)` | Obtém system prompt |
 | `availablePrompts` | Lista prompts disponíveis |

package/dist/index.d.mts

@@ -86,39 +86,6 @@ interface Citation {
     /** Número do artigo */
     article?: string;
 }
-/** Metadados da resposta de pergunta */
-interface AskMetadata {
-    /** Modelo usado */
-    model: string;
-    /** Tempo total em ms */
-    latencyMs: number;
-    /** Tempo de busca em ms */
-    retrievalMs?: number;
-    /** Tempo de geração em ms */
-    generationMs?: number;
-    /** Chunks usados */
-    chunksUsed: number;
-    /** Tokens usados */
-    tokens?: number;
-    /** Hash da query (para feedback) */
-    queryHash?: string;
-}
-/** Resposta de uma pergunta */
-interface AskResponse {
-    /** Resposta gerada */
-    answer: string;
-    /** Citações */
-    citations: Citation[];
-    /** Confiança (0-1) */
-    confidence: number;
-    /** Metadados */
-    metadata: AskMetadata;
-}
-/** Opções para perguntar */
-interface AskOptions extends SearchOptions {
-    /** Usar cache semântico */
-    useCache?: boolean;
-}
 /** Resposta de feedback */
 interface FeedbackResponse {
     success: boolean;
@@ -128,16 +95,16 @@ interface FeedbackResponse {
 }
 /** Erros da API */
 declare class VectorGovError extends Error {
-    statusCode?: number | undefined;
-    code?: string | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
+    statusCode?: number;
+    code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
 }
 declare class AuthenticationError extends VectorGovError {
     constructor(message?: string);
 }
 declare class RateLimitError extends VectorGovError {
-    retryAfter?: number | undefined;
-    constructor(message?: string, retryAfter?: number | undefined);
+    retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
 }
 /** Registro de evento de auditoria */
 interface AuditLog {
@@ -241,25 +208,6 @@ interface StoreResponseResult {
     /** 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 */
@@ -382,6 +330,30 @@ interface GoogleTool {
 }
 /** Estilos de system prompt disponíveis */
 type SystemPromptStyle = 'default' | 'concise' | 'detailed' | 'chatbot';
+/** Estatísticas de tokens para planejamento de contexto LLM */
+interface TokenStats {
+    /** Tokens do contexto (hits formatados) */
+    contextTokens: number;
+    /** Tokens do system prompt */
+    systemTokens: number;
+    /** Tokens da query do usuário */
+    queryTokens: number;
+    /** Total de tokens (context + system + query) */
+    totalTokens: number;
+    /** Quantidade de hits no contexto */
+    hitsCount: number;
+    /** Número total de caracteres */
+    charCount: number;
+    /** Encoding utilizado (cl100k_base compatível com GPT-4/Claude) */
+    encoding: string;
+}
+/** Opções para estimativa de tokens */
+interface EstimateTokensOptions {
+    /** System prompt customizado (opcional) */
+    systemPrompt?: string;
+    /** Query do usuário (obrigatório quando content é string) */
+    query?: string;
+}
 
 /**
  * VectorGov SDK Client
@@ -432,33 +404,6 @@ declare class VectorGov {
      * ```
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
-    /**
-     * Faz uma pergunta e recebe uma resposta gerada por IA
-     *
-     * @param query - Pergunta
-     * @param options - Opções
-     * @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
      *
@@ -691,6 +636,40 @@ declare class VectorGov {
      * ```
      */
     getAuditEventTypes(): Promise<string[]>;
+    /**
+     * Estima a quantidade de tokens que serão usados com um LLM
+     *
+     * Use para planejar o contexto antes de enviar para seu LLM:
+     * - Verificar se cabe no limite do modelo
+     * - Calcular custos estimados
+     * - Ajustar top_k se necessário
+     *
+     * @param content - SearchResult ou string de contexto
+     * @param options - Opções (systemPrompt customizado, query)
+     * @returns Estatísticas de tokens
+     *
+     * @example
+     * ```typescript
+     * // Com SearchResult
+     * const results = await vg.search('O que é ETP?');
+     * const stats = await vg.estimateTokens(results);
+     * console.log(`Total de tokens: ${stats.totalTokens}`);
+     *
+     * if (stats.totalTokens > 4000) {
+     *   // Reduzir contexto
+     *   const smaller = await vg.search('O que é ETP?', { topK: 3 });
+     * }
+     *
+     * // Com string direta
+     * const stats2 = await vg.estimateTokens('Texto de contexto...');
+     *
+     * // Com system prompt customizado
+     * const stats3 = await vg.estimateTokens(results, {
+     *   systemPrompt: 'Você é um especialista jurídico...'
+     * });
+     * ```
+     */
+    estimateTokens(content: SearchResult | string, options?: EstimateTokensOptions): Promise<TokenStats>;
     /**
      * Converte hits para formato de mensagens de chat
      */
@@ -701,4 +680,4 @@ declare class VectorGov {
     private hitsToContext;
 }
 
-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 };
+export { type AnthropicTool, type AuditLog, type AuditLogsOptions, type AuditLogsResponse, type AuditStats, AuthenticationError, type ChatMessage, type Citation, type DeleteResponse, type DocumentSummary, type DocumentsResponse, type EnrichStatus, type EstimateTokensOptions, 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 SystemPromptStyle, type TokenStats, type UploadResponse, VectorGov, type VectorGovConfig, VectorGovError };

package/dist/index.d.ts

@@ -86,39 +86,6 @@ interface Citation {
     /** Número do artigo */
     article?: string;
 }
-/** Metadados da resposta de pergunta */
-interface AskMetadata {
-    /** Modelo usado */
-    model: string;
-    /** Tempo total em ms */
-    latencyMs: number;
-    /** Tempo de busca em ms */
-    retrievalMs?: number;
-    /** Tempo de geração em ms */
-    generationMs?: number;
-    /** Chunks usados */
-    chunksUsed: number;
-    /** Tokens usados */
-    tokens?: number;
-    /** Hash da query (para feedback) */
-    queryHash?: string;
-}
-/** Resposta de uma pergunta */
-interface AskResponse {
-    /** Resposta gerada */
-    answer: string;
-    /** Citações */
-    citations: Citation[];
-    /** Confiança (0-1) */
-    confidence: number;
-    /** Metadados */
-    metadata: AskMetadata;
-}
-/** Opções para perguntar */
-interface AskOptions extends SearchOptions {
-    /** Usar cache semântico */
-    useCache?: boolean;
-}
 /** Resposta de feedback */
 interface FeedbackResponse {
     success: boolean;
@@ -128,16 +95,16 @@ interface FeedbackResponse {
 }
 /** Erros da API */
 declare class VectorGovError extends Error {
-    statusCode?: number | undefined;
-    code?: string | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
+    statusCode?: number;
+    code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
 }
 declare class AuthenticationError extends VectorGovError {
     constructor(message?: string);
 }
 declare class RateLimitError extends VectorGovError {
-    retryAfter?: number | undefined;
-    constructor(message?: string, retryAfter?: number | undefined);
+    retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
 }
 /** Registro de evento de auditoria */
 interface AuditLog {
@@ -241,25 +208,6 @@ interface StoreResponseResult {
     /** 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 */
@@ -382,6 +330,30 @@ interface GoogleTool {
 }
 /** Estilos de system prompt disponíveis */
 type SystemPromptStyle = 'default' | 'concise' | 'detailed' | 'chatbot';
+/** Estatísticas de tokens para planejamento de contexto LLM */
+interface TokenStats {
+    /** Tokens do contexto (hits formatados) */
+    contextTokens: number;
+    /** Tokens do system prompt */
+    systemTokens: number;
+    /** Tokens da query do usuário */
+    queryTokens: number;
+    /** Total de tokens (context + system + query) */
+    totalTokens: number;
+    /** Quantidade de hits no contexto */
+    hitsCount: number;
+    /** Número total de caracteres */
+    charCount: number;
+    /** Encoding utilizado (cl100k_base compatível com GPT-4/Claude) */
+    encoding: string;
+}
+/** Opções para estimativa de tokens */
+interface EstimateTokensOptions {
+    /** System prompt customizado (opcional) */
+    systemPrompt?: string;
+    /** Query do usuário (obrigatório quando content é string) */
+    query?: string;
+}
 
 /**
  * VectorGov SDK Client
@@ -432,33 +404,6 @@ declare class VectorGov {
      * ```
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
-    /**
-     * Faz uma pergunta e recebe uma resposta gerada por IA
-     *
-     * @param query - Pergunta
-     * @param options - Opções
-     * @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
      *
@@ -691,6 +636,40 @@ declare class VectorGov {
      * ```
      */
     getAuditEventTypes(): Promise<string[]>;
+    /**
+     * Estima a quantidade de tokens que serão usados com um LLM
+     *
+     * Use para planejar o contexto antes de enviar para seu LLM:
+     * - Verificar se cabe no limite do modelo
+     * - Calcular custos estimados
+     * - Ajustar top_k se necessário
+     *
+     * @param content - SearchResult ou string de contexto
+     * @param options - Opções (systemPrompt customizado, query)
+     * @returns Estatísticas de tokens
+     *
+     * @example
+     * ```typescript
+     * // Com SearchResult
+     * const results = await vg.search('O que é ETP?');
+     * const stats = await vg.estimateTokens(results);
+     * console.log(`Total de tokens: ${stats.totalTokens}`);
+     *
+     * if (stats.totalTokens > 4000) {
+     *   // Reduzir contexto
+     *   const smaller = await vg.search('O que é ETP?', { topK: 3 });
+     * }
+     *
+     * // Com string direta
+     * const stats2 = await vg.estimateTokens('Texto de contexto...');
+     *
+     * // Com system prompt customizado
+     * const stats3 = await vg.estimateTokens(results, {
+     *   systemPrompt: 'Você é um especialista jurídico...'
+     * });
+     * ```
+     */
+    estimateTokens(content: SearchResult | string, options?: EstimateTokensOptions): Promise<TokenStats>;
     /**
      * Converte hits para formato de mensagens de chat
      */
@@ -701,4 +680,4 @@ declare class VectorGov {
     private hitsToContext;
 }
 
-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 };
+export { type AnthropicTool, type AuditLog, type AuditLogsOptions, type AuditLogsResponse, type AuditStats, AuthenticationError, type ChatMessage, type Citation, type DeleteResponse, type DocumentSummary, type DocumentsResponse, type EnrichStatus, type EstimateTokensOptions, 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 SystemPromptStyle, type TokenStats, type UploadResponse, VectorGov, type VectorGovConfig, VectorGovError };

package/dist/index.js

@@ -1,4 +1,3 @@
-"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -104,6 +103,9 @@ var TOOL_SCHEMA = {
   }
 };
 var VectorGov = class {
+  apiKey;
+  baseUrl;
+  timeout;
   constructor(config) {
     if (!config.apiKey) {
       throw new AuthenticationError("API key is required");
@@ -221,130 +223,6 @@ var VectorGov = class {
       toContext: () => this.hitsToContext(hits)
     };
   }
-  /**
-   * Faz uma pergunta e recebe uma resposta gerada por IA
-   *
-   * @param query - Pergunta
-   * @param options - Opções
-   * @returns Resposta com citações
-   */
-  async ask(query, options = {}) {
-    const {
-      topK = 5,
-      mode = "balanced",
-      useCache = true,
-      tipoDocumento,
-      ano
-    } = options;
-    const response = await this.request("/sdk/ask", {
-      method: "POST",
-      body: JSON.stringify({
-        query,
-        top_k: topK,
-        mode,
-        use_cache: useCache,
-        tipo_documento: tipoDocumento,
-        ano
-      })
-    });
-    return {
-      answer: response.data.answer,
-      citations: response.data.citations.map((c) => ({
-        text: c.text,
-        short: c.short,
-        documentType: c.document_type,
-        documentNumber: c.document_number,
-        year: c.year,
-        article: c.article
-      })),
-      confidence: response.data.confidence,
-      metadata: {
-        model: response.metadata.model,
-        latencyMs: response.metadata.latency_ms,
-        retrievalMs: response.metadata.retrieval_ms,
-        generationMs: response.metadata.generation_ms,
-        chunksUsed: response.metadata.chunks_used,
-        tokens: response.metadata.tokens,
-        queryHash: response.metadata.query_hash
-      }
-    };
-  }
-  /**
-   * 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`);
-   *   }
-   * }
-   * ```
-   */
-  async *askStream(query, options = {}) {
-    const { topK = 5, mode = "balanced" } = options;
-    const url = `${this.baseUrl}/sdk/ask/stream`;
-    const response = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-API-Key": this.apiKey
-      },
-      body: JSON.stringify({
-        query,
-        top_k: topK,
-        mode
-      })
-    });
-    if (!response.ok) {
-      throw new VectorGovError(`Stream request failed: ${response.status}`);
-    }
-    if (!response.body) {
-      throw new VectorGovError("No response body for streaming");
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
-        for (const line of lines) {
-          if (line.startsWith("data: ")) {
-            const data = line.slice(6);
-            if (data === "[DONE]") return;
-            try {
-              const event = JSON.parse(data);
-              const chunk = {
-                type: event.type || "token",
-                content: event.content,
-                query: event.query,
-                chunks: event.chunks,
-                timeMs: event.time_ms,
-                citations: event.citations,
-                queryHash: event.query_hash,
-                message: event.message
-              };
-              yield chunk;
-              if (event.type === "error") return;
-            } catch {
-            }
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
   /**
    * Envia feedback (like/dislike) para uma resposta
    *
@@ -811,6 +689,71 @@ ${parts.join("\n\n---\n\n")}`;
     return response.event_types;
   }
   // ===========================================================================
+  // CONTAGEM DE TOKENS
+  // ===========================================================================
+  /**
+   * Estima a quantidade de tokens que serão usados com um LLM
+   *
+   * Use para planejar o contexto antes de enviar para seu LLM:
+   * - Verificar se cabe no limite do modelo
+   * - Calcular custos estimados
+   * - Ajustar top_k se necessário
+   *
+   * @param content - SearchResult ou string de contexto
+   * @param options - Opções (systemPrompt customizado, query)
+   * @returns Estatísticas de tokens
+   *
+   * @example
+   * ```typescript
+   * // Com SearchResult
+   * const results = await vg.search('O que é ETP?');
+   * const stats = await vg.estimateTokens(results);
+   * console.log(`Total de tokens: ${stats.totalTokens}`);
+   *
+   * if (stats.totalTokens > 4000) {
+   *   // Reduzir contexto
+   *   const smaller = await vg.search('O que é ETP?', { topK: 3 });
+   * }
+   *
+   * // Com string direta
+   * const stats2 = await vg.estimateTokens('Texto de contexto...');
+   *
+   * // Com system prompt customizado
+   * const stats3 = await vg.estimateTokens(results, {
+   *   systemPrompt: 'Você é um especialista jurídico...'
+   * });
+   * ```
+   */
+  async estimateTokens(content, options = {}) {
+    let context;
+    let query = options.query || "";
+    let hitsCount = 0;
+    if (typeof content === "string") {
+      context = content;
+    } else {
+      context = content.toContext();
+      hitsCount = content.hits.length;
+    }
+    const systemPrompt = options.systemPrompt || SYSTEM_PROMPTS.default;
+    const response = await this.request("/sdk/tokens", {
+      method: "POST",
+      body: JSON.stringify({
+        context,
+        query,
+        system_prompt: systemPrompt
+      })
+    });
+    return {
+      contextTokens: response.context_tokens,
+      systemTokens: response.system_tokens,
+      queryTokens: response.query_tokens,
+      totalTokens: response.total_tokens,
+      hitsCount,
+      charCount: response.char_count,
+      encoding: response.encoding
+    };
+  }
+  // ===========================================================================
   // MÉTODOS AUXILIARES
   // ===========================================================================
   /**

package/dist/index.mjs

@@ -75,6 +75,9 @@ var TOOL_SCHEMA = {
   }
 };
 var VectorGov = class {
+  apiKey;
+  baseUrl;
+  timeout;
   constructor(config) {
     if (!config.apiKey) {
       throw new AuthenticationError("API key is required");
@@ -192,130 +195,6 @@ var VectorGov = class {
       toContext: () => this.hitsToContext(hits)
     };
   }
-  /**
-   * Faz uma pergunta e recebe uma resposta gerada por IA
-   *
-   * @param query - Pergunta
-   * @param options - Opções
-   * @returns Resposta com citações
-   */
-  async ask(query, options = {}) {
-    const {
-      topK = 5,
-      mode = "balanced",
-      useCache = true,
-      tipoDocumento,
-      ano
-    } = options;
-    const response = await this.request("/sdk/ask", {
-      method: "POST",
-      body: JSON.stringify({
-        query,
-        top_k: topK,
-        mode,
-        use_cache: useCache,
-        tipo_documento: tipoDocumento,
-        ano
-      })
-    });
-    return {
-      answer: response.data.answer,
-      citations: response.data.citations.map((c) => ({
-        text: c.text,
-        short: c.short,
-        documentType: c.document_type,
-        documentNumber: c.document_number,
-        year: c.year,
-        article: c.article
-      })),
-      confidence: response.data.confidence,
-      metadata: {
-        model: response.metadata.model,
-        latencyMs: response.metadata.latency_ms,
-        retrievalMs: response.metadata.retrieval_ms,
-        generationMs: response.metadata.generation_ms,
-        chunksUsed: response.metadata.chunks_used,
-        tokens: response.metadata.tokens,
-        queryHash: response.metadata.query_hash
-      }
-    };
-  }
-  /**
-   * 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`);
-   *   }
-   * }
-   * ```
-   */
-  async *askStream(query, options = {}) {
-    const { topK = 5, mode = "balanced" } = options;
-    const url = `${this.baseUrl}/sdk/ask/stream`;
-    const response = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-API-Key": this.apiKey
-      },
-      body: JSON.stringify({
-        query,
-        top_k: topK,
-        mode
-      })
-    });
-    if (!response.ok) {
-      throw new VectorGovError(`Stream request failed: ${response.status}`);
-    }
-    if (!response.body) {
-      throw new VectorGovError("No response body for streaming");
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
-        for (const line of lines) {
-          if (line.startsWith("data: ")) {
-            const data = line.slice(6);
-            if (data === "[DONE]") return;
-            try {
-              const event = JSON.parse(data);
-              const chunk = {
-                type: event.type || "token",
-                content: event.content,
-                query: event.query,
-                chunks: event.chunks,
-                timeMs: event.time_ms,
-                citations: event.citations,
-                queryHash: event.query_hash,
-                message: event.message
-              };
-              yield chunk;
-              if (event.type === "error") return;
-            } catch {
-            }
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
   /**
    * Envia feedback (like/dislike) para uma resposta
    *
@@ -782,6 +661,71 @@ ${parts.join("\n\n---\n\n")}`;
     return response.event_types;
   }
   // ===========================================================================
+  // CONTAGEM DE TOKENS
+  // ===========================================================================
+  /**
+   * Estima a quantidade de tokens que serão usados com um LLM
+   *
+   * Use para planejar o contexto antes de enviar para seu LLM:
+   * - Verificar se cabe no limite do modelo
+   * - Calcular custos estimados
+   * - Ajustar top_k se necessário
+   *
+   * @param content - SearchResult ou string de contexto
+   * @param options - Opções (systemPrompt customizado, query)
+   * @returns Estatísticas de tokens
+   *
+   * @example
+   * ```typescript
+   * // Com SearchResult
+   * const results = await vg.search('O que é ETP?');
+   * const stats = await vg.estimateTokens(results);
+   * console.log(`Total de tokens: ${stats.totalTokens}`);
+   *
+   * if (stats.totalTokens > 4000) {
+   *   // Reduzir contexto
+   *   const smaller = await vg.search('O que é ETP?', { topK: 3 });
+   * }
+   *
+   * // Com string direta
+   * const stats2 = await vg.estimateTokens('Texto de contexto...');
+   *
+   * // Com system prompt customizado
+   * const stats3 = await vg.estimateTokens(results, {
+   *   systemPrompt: 'Você é um especialista jurídico...'
+   * });
+   * ```
+   */
+  async estimateTokens(content, options = {}) {
+    let context;
+    let query = options.query || "";
+    let hitsCount = 0;
+    if (typeof content === "string") {
+      context = content;
+    } else {
+      context = content.toContext();
+      hitsCount = content.hits.length;
+    }
+    const systemPrompt = options.systemPrompt || SYSTEM_PROMPTS.default;
+    const response = await this.request("/sdk/tokens", {
+      method: "POST",
+      body: JSON.stringify({
+        context,
+        query,
+        system_prompt: systemPrompt
+      })
+    });
+    return {
+      contextTokens: response.context_tokens,
+      systemTokens: response.system_tokens,
+      queryTokens: response.query_tokens,
+      totalTokens: response.total_tokens,
+      hitsCount,
+      charCount: response.char_count,
+      encoding: response.encoding
+    };
+  }
+  // ===========================================================================
   // MÉTODOS AUXILIARES
   // ===========================================================================
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorgov",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SDK TypeScript para a API VectorGov - Busca semântica em legislação brasileira",
   "main": "dist/index.js",
   "module": "dist/index.mjs",