vectorgov 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# VectorGov SDK for TypeScript/JavaScript
+
+SDK oficial para a API VectorGov - Busca semântica em legislação brasileira.
+
+## Instalação
+
+```bash
+npm install vectorgov
+# ou
+yarn add vectorgov
+# ou
+pnpm add vectorgov
+```
+
+## Uso Rápido
+
+```typescript
+import { VectorGov } from 'vectorgov';
+
+const vg = new VectorGov({ apiKey: 'vg_sua_chave' });
+
+// Busca simples
+const results = await vg.search('O que é ETP?');
+
+for (const hit of results.hits) {
+  console.log(`${hit.source}: ${hit.text.slice(0, 100)}...`);
+}
+```
+
+## Integração com LLMs
+
+### OpenAI
+
+```typescript
+import { VectorGov } from 'vectorgov';
+import OpenAI from 'openai';
+
+const vg = new VectorGov({ apiKey: 'vg_sua_chave' });
+const openai = new OpenAI();
+
+// Busca contexto relevante
+const results = await vg.search('Quais os critérios de julgamento?');
+
+// Gera resposta com GPT-4
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: results.toMessages('Quais os critérios de julgamento?')
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### Anthropic Claude
+
+```typescript
+import { VectorGov } from 'vectorgov';
+import Anthropic from '@anthropic-ai/sdk';
+
+const vg = new VectorGov({ apiKey: 'vg_sua_chave' });
+const anthropic = new Anthropic();
+
+const results = await vg.search('Quando o ETP pode ser dispensado?');
+const messages = results.toMessages('Quando o ETP pode ser dispensado?');
+
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  system: messages[0].content,
+  messages: [{ role: 'user', content: messages[1].content }]
+});
+
+console.log(response.content[0].text);
+```
+
+### Google Gemini
+
+```typescript
+import { VectorGov } from 'vectorgov';
+import { GoogleGenerativeAI } from '@google/generative-ai';
+
+const vg = new VectorGov({ apiKey: 'vg_sua_chave' });
+const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!);
+
+const results = await vg.search('O que é pesquisa de preços?');
+const messages = results.toMessages('O que é pesquisa de preços?');
+
+const model = genAI.getGenerativeModel({
+  model: 'gemini-2.0-flash',
+  systemInstruction: messages[0].content
+});
+
+const response = await model.generateContent(messages[1].content);
+console.log(response.response.text());
+```
+
+## Modos de Busca
+
+```typescript
+// Fast (~2s) - Busca direta, sem reranking
+const fast = await vg.search('O que é ETP?', { mode: 'fast' });
+
+// Balanced (~5s) - Com reranking (padrão)
+const balanced = await vg.search('O que é ETP?', { mode: 'balanced' });
+
+// Precise (~15s) - HyDE + reranking para máxima precisão
+const precise = await vg.search('O que é ETP?', { mode: 'precise' });
+```
+
+## Filtros
+
+```typescript
+// Filtrar por tipo de documento
+const results = await vg.search('dispensa de licitação', {
+  tipoDocumento: 'lei',
+  ano: 2021
+});
+```
+
+## 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
+const results = await vg.search('O que é ETP?');
+
+// Enviar feedback positivo
+await vg.feedback(results.metadata.queryId, true);
+
+// Ou negativo
+await vg.feedback(results.metadata.queryId, false);
+```
+
+## Tratamento de Erros
+
+```typescript
+import { VectorGov, AuthenticationError, RateLimitError, VectorGovError } from 'vectorgov';
+
+try {
+  const results = await vg.search('query');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('API key inválida');
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limit. Retry após ${error.retryAfter}s`);
+  } else if (error instanceof VectorGovError) {
+    console.error(`Erro: ${error.message} (${error.statusCode})`);
+  }
+}
+```
+
+## Configuração
+
+```typescript
+const vg = new VectorGov({
+  apiKey: 'vg_sua_chave',
+  baseUrl: 'https://vectorgov.io/api/v1', // opcional
+  timeout: 30000 // opcional, em ms
+});
+```
+
+## Variáveis de Ambiente
+
+```bash
+export VECTORGOV_API_KEY="vg_sua_chave"
+```
+
+```typescript
+const vg = new VectorGov({
+  apiKey: process.env.VECTORGOV_API_KEY!
+});
+```
+
+## API Reference
+
+### VectorGov
+
+| Método | Descrição |
+|--------|-----------|
+| `search(query, options?)` | Busca semântica |
+| `ask(query, options?)` | Pergunta com resposta IA |
+| `feedback(queryId, like)` | Envia feedback |
+
+### SearchOptions
+
+| Campo | Tipo | Padrão | Descrição |
+|-------|------|--------|-----------|
+| `topK` | number | 5 | Número de resultados |
+| `mode` | 'fast' \| 'balanced' \| 'precise' | 'balanced' | Modo de busca |
+| `tipoDocumento` | string | - | Filtro por tipo |
+| `ano` | number | - | Filtro por ano |
+
+### SearchResult
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `hits` | SearchHit[] | Resultados |
+| `total` | number | Total encontrado |
+| `metadata` | SearchMetadata | Metadados |
+| `toMessages(query)` | ChatMessage[] | Formato para LLMs |
+| `toContext()` | string | Contexto em texto |
+
+## Links
+
+- [Documentação](https://vectorgov.io/documentacao)
+- [GitHub](https://github.com/euteajudo/vectorgov-sdk-ts)
+- [npm](https://www.npmjs.com/package/vectorgov)
+
+## Licença
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,217 @@
+/**
+ * VectorGov SDK Types
+ */
+/** Modos de busca disponíveis */
+type SearchMode = 'fast' | 'balanced' | 'precise';
+/** Configuração do cliente VectorGov */
+interface VectorGovConfig {
+    /** API key para autenticação */
+    apiKey: string;
+    /** URL base da API (padrão: https://vectorgov.io/api/v1) */
+    baseUrl?: string;
+    /** Timeout em milissegundos (padrão: 30000) */
+    timeout?: number;
+}
+/** Opções de busca */
+interface SearchOptions {
+    /** Número de resultados (padrão: 5) */
+    topK?: number;
+    /** Modo de busca (padrão: 'balanced') */
+    mode?: SearchMode;
+    /** Tipo de documento para filtrar */
+    tipoDocumento?: string;
+    /** Ano do documento para filtrar */
+    ano?: number;
+}
+/** Hit individual de busca */
+interface SearchHit {
+    /** Texto do trecho encontrado */
+    text: string;
+    /** Número do artigo */
+    articleNumber?: string;
+    /** ID do documento */
+    documentId?: string;
+    /** Tipo do documento (LEI, DECRETO, IN, etc) */
+    documentType?: string;
+    /** Número do documento */
+    documentNumber?: string;
+    /** Ano do documento */
+    year?: number;
+    /** Score de relevância */
+    score: number;
+    /** Score final após reranking */
+    finalScore?: number;
+    /** Fonte formatada */
+    source?: string;
+}
+/** Metadados da busca */
+interface SearchMetadata {
+    /** Tempo total em milissegundos */
+    latencyMs: number;
+    /** Se a resposta veio do cache */
+    cached: boolean;
+    /** ID único da query (para feedback) */
+    queryId: string;
+}
+/** Resultado da busca */
+interface SearchResult {
+    /** Lista de resultados */
+    hits: SearchHit[];
+    /** Total de resultados encontrados */
+    total: number;
+    /** Metadados da busca */
+    metadata: SearchMetadata;
+    /** Converte para formato de mensagens (OpenAI, Claude, etc) */
+    toMessages(query: string): ChatMessage[];
+    /** Converte para contexto de texto */
+    toContext(): string;
+}
+/** Mensagem de chat (formato OpenAI) */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** Citação em uma resposta */
+interface Citation {
+    /** Texto completo da citação */
+    text: string;
+    /** Versão curta (ex: "Art. 5, I") */
+    short: string;
+    /** Tipo do documento */
+    documentType?: string;
+    /** Número do documento */
+    documentNumber?: string;
+    /** Ano */
+    year?: number;
+    /** 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;
+    message: string;
+    newLikes?: number;
+    newDislikes?: number;
+}
+/** Erros da API */
+declare class VectorGovError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
+}
+declare class AuthenticationError extends VectorGovError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends VectorGovError {
+    retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+
+/**
+ * VectorGov SDK Client
+ */
+
+/**
+ * Cliente para a API VectorGov
+ *
+ * @example
+ * ```typescript
+ * import { VectorGov } from 'vectorgov';
+ *
+ * const vg = new VectorGov({ apiKey: 'vg_sua_chave' });
+ *
+ * // Busca
+ * const results = await vg.search('O que é ETP?');
+ *
+ * // Para usar com OpenAI
+ * const messages = results.toMessages('O que é ETP?');
+ * ```
+ */
+declare class VectorGov {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: VectorGovConfig);
+    /**
+     * Faz uma requisição para a API
+     */
+    private request;
+    /**
+     * Busca semântica em documentos legais
+     *
+     * @param query - Pergunta ou texto para buscar
+     * @param options - Opções de busca
+     * @returns Resultado da busca com métodos auxiliares
+     *
+     * @example
+     * ```typescript
+     * const results = await vg.search('O que é ETP?', {
+     *   topK: 5,
+     *   mode: 'balanced'
+     * });
+     *
+     * for (const hit of results.hits) {
+     *   console.log(`${hit.source}: ${hit.text.slice(0, 100)}...`);
+     * }
+     * ```
+     */
+    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>;
+    /**
+     * Envia feedback (like/dislike) para uma resposta
+     *
+     * @param queryId - ID da query (de SearchMetadata ou AskMetadata)
+     * @param like - true para like, false para dislike
+     */
+    feedback(queryId: string, like: boolean): Promise<FeedbackResponse>;
+    /**
+     * 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, AuthenticationError, type ChatMessage, type Citation, type FeedbackResponse, RateLimitError, type SearchHit, type SearchMetadata, type SearchMode, type SearchOptions, type SearchResult, VectorGov, type VectorGovConfig, VectorGovError };

package/dist/index.d.ts

@@ -0,0 +1,217 @@
+/**
+ * VectorGov SDK Types
+ */
+/** Modos de busca disponíveis */
+type SearchMode = 'fast' | 'balanced' | 'precise';
+/** Configuração do cliente VectorGov */
+interface VectorGovConfig {
+    /** API key para autenticação */
+    apiKey: string;
+    /** URL base da API (padrão: https://vectorgov.io/api/v1) */
+    baseUrl?: string;
+    /** Timeout em milissegundos (padrão: 30000) */
+    timeout?: number;
+}
+/** Opções de busca */
+interface SearchOptions {
+    /** Número de resultados (padrão: 5) */
+    topK?: number;
+    /** Modo de busca (padrão: 'balanced') */
+    mode?: SearchMode;
+    /** Tipo de documento para filtrar */
+    tipoDocumento?: string;
+    /** Ano do documento para filtrar */
+    ano?: number;
+}
+/** Hit individual de busca */
+interface SearchHit {
+    /** Texto do trecho encontrado */
+    text: string;
+    /** Número do artigo */
+    articleNumber?: string;
+    /** ID do documento */
+    documentId?: string;
+    /** Tipo do documento (LEI, DECRETO, IN, etc) */
+    documentType?: string;
+    /** Número do documento */
+    documentNumber?: string;
+    /** Ano do documento */
+    year?: number;
+    /** Score de relevância */
+    score: number;
+    /** Score final após reranking */
+    finalScore?: number;
+    /** Fonte formatada */
+    source?: string;
+}
+/** Metadados da busca */
+interface SearchMetadata {
+    /** Tempo total em milissegundos */
+    latencyMs: number;
+    /** Se a resposta veio do cache */
+    cached: boolean;
+    /** ID único da query (para feedback) */
+    queryId: string;
+}
+/** Resultado da busca */
+interface SearchResult {
+    /** Lista de resultados */
+    hits: SearchHit[];
+    /** Total de resultados encontrados */
+    total: number;
+    /** Metadados da busca */
+    metadata: SearchMetadata;
+    /** Converte para formato de mensagens (OpenAI, Claude, etc) */
+    toMessages(query: string): ChatMessage[];
+    /** Converte para contexto de texto */
+    toContext(): string;
+}
+/** Mensagem de chat (formato OpenAI) */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** Citação em uma resposta */
+interface Citation {
+    /** Texto completo da citação */
+    text: string;
+    /** Versão curta (ex: "Art. 5, I") */
+    short: string;
+    /** Tipo do documento */
+    documentType?: string;
+    /** Número do documento */
+    documentNumber?: string;
+    /** Ano */
+    year?: number;
+    /** 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;
+    message: string;
+    newLikes?: number;
+    newDislikes?: number;
+}
+/** Erros da API */
+declare class VectorGovError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
+}
+declare class AuthenticationError extends VectorGovError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends VectorGovError {
+    retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+
+/**
+ * VectorGov SDK Client
+ */
+
+/**
+ * Cliente para a API VectorGov
+ *
+ * @example
+ * ```typescript
+ * import { VectorGov } from 'vectorgov';
+ *
+ * const vg = new VectorGov({ apiKey: 'vg_sua_chave' });
+ *
+ * // Busca
+ * const results = await vg.search('O que é ETP?');
+ *
+ * // Para usar com OpenAI
+ * const messages = results.toMessages('O que é ETP?');
+ * ```
+ */
+declare class VectorGov {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: VectorGovConfig);
+    /**
+     * Faz uma requisição para a API
+     */
+    private request;
+    /**
+     * Busca semântica em documentos legais
+     *
+     * @param query - Pergunta ou texto para buscar
+     * @param options - Opções de busca
+     * @returns Resultado da busca com métodos auxiliares
+     *
+     * @example
+     * ```typescript
+     * const results = await vg.search('O que é ETP?', {
+     *   topK: 5,
+     *   mode: 'balanced'
+     * });
+     *
+     * for (const hit of results.hits) {
+     *   console.log(`${hit.source}: ${hit.text.slice(0, 100)}...`);
+     * }
+     * ```
+     */
+    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>;
+    /**
+     * Envia feedback (like/dislike) para uma resposta
+     *
+     * @param queryId - ID da query (de SearchMetadata ou AskMetadata)
+     * @param like - true para like, false para dislike
+     */
+    feedback(queryId: string, like: boolean): Promise<FeedbackResponse>;
+    /**
+     * 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, AuthenticationError, type ChatMessage, type Citation, type FeedbackResponse, RateLimitError, type SearchHit, type SearchMetadata, type SearchMode, type SearchOptions, type SearchResult, VectorGov, type VectorGovConfig, VectorGovError };

package/dist/index.js

@@ -0,0 +1,286 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  RateLimitError: () => RateLimitError,
+  VectorGov: () => VectorGov,
+  VectorGovError: () => VectorGovError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var VectorGovError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.name = "VectorGovError";
+  }
+};
+var AuthenticationError = class extends VectorGovError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, 401, "AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends VectorGovError {
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, 429, "RATE_LIMIT_ERROR");
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://vectorgov.io/api/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var SYSTEM_PROMPT = `Voc\xEA \xE9 um assistente jur\xEDdico especializado em legisla\xE7\xE3o brasileira de licita\xE7\xF5es e contratos administrativos.
+
+Use APENAS as informa\xE7\xF5es fornecidas no contexto para responder. Se a informa\xE7\xE3o n\xE3o estiver no contexto, diga que n\xE3o encontrou.
+
+Ao citar artigos, use o formato: [Art. X] ou [Art. X, \xA7Y] ou [Art. X, inciso Y].
+
+Responda de forma clara, objetiva e em portugu\xEAs brasileiro.`;
+var VectorGov = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new AuthenticationError("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Faz uma requisição para a API
+   */
+  async request(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...options.headers
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        if (response.status === 401) {
+          throw new AuthenticationError(errorData.detail || "Invalid API key");
+        }
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("Retry-After");
+          throw new RateLimitError(
+            errorData.detail || "Rate limit exceeded",
+            retryAfter ? parseInt(retryAfter, 10) : void 0
+          );
+        }
+        throw new VectorGovError(
+          errorData.detail || `Request failed with status ${response.status}`,
+          response.status
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof VectorGovError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new VectorGovError("Request timeout", 408, "TIMEOUT");
+      }
+      throw new VectorGovError(
+        error instanceof Error ? error.message : "Unknown error"
+      );
+    }
+  }
+  /**
+   * Busca semântica em documentos legais
+   *
+   * @param query - Pergunta ou texto para buscar
+   * @param options - Opções de busca
+   * @returns Resultado da busca com métodos auxiliares
+   *
+   * @example
+   * ```typescript
+   * const results = await vg.search('O que é ETP?', {
+   *   topK: 5,
+   *   mode: 'balanced'
+   * });
+   *
+   * for (const hit of results.hits) {
+   *   console.log(`${hit.source}: ${hit.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const {
+      topK = 5,
+      mode = "balanced",
+      tipoDocumento,
+      ano
+    } = options;
+    const response = await this.request("/sdk/search", {
+      method: "POST",
+      body: JSON.stringify({
+        query,
+        top_k: topK,
+        mode,
+        tipo_documento: tipoDocumento,
+        ano
+      })
+    });
+    const hits = response.hits.map((hit) => ({
+      text: hit.text,
+      articleNumber: hit.article_number,
+      documentId: hit.document_id,
+      documentType: hit.document_type,
+      documentNumber: hit.document_number,
+      year: hit.year,
+      score: hit.score,
+      finalScore: hit.final_score,
+      source: hit.document_type && hit.document_number && hit.year ? `${hit.document_type} ${hit.document_number}/${hit.year}, Art. ${hit.article_number || "N/A"}` : void 0
+    }));
+    const metadata = {
+      latencyMs: response.latency_ms,
+      cached: response.cached,
+      queryId: response.query_id
+    };
+    return {
+      hits,
+      total: response.total,
+      metadata,
+      toMessages: (q) => this.hitsToMessages(hits, q),
+      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
+      }
+    };
+  }
+  /**
+   * Envia feedback (like/dislike) para uma resposta
+   *
+   * @param queryId - ID da query (de SearchMetadata ou AskMetadata)
+   * @param like - true para like, false para dislike
+   */
+  async feedback(queryId, like) {
+    const response = await this.request("/cache/feedback", {
+      method: "POST",
+      body: JSON.stringify({
+        query_hash: queryId,
+        is_like: like
+      })
+    });
+    return {
+      success: response.success,
+      message: response.message,
+      newLikes: response.new_likes,
+      newDislikes: response.new_dislikes
+    };
+  }
+  /**
+   * Converte hits para formato de mensagens de chat
+   */
+  hitsToMessages(hits, query) {
+    const context = this.hitsToContext(hits);
+    return [
+      {
+        role: "system",
+        content: SYSTEM_PROMPT
+      },
+      {
+        role: "user",
+        content: `Contexto:
+${context}
+
+Pergunta: ${query}`
+      }
+    ];
+  }
+  /**
+   * Converte hits para texto de contexto
+   */
+  hitsToContext(hits) {
+    return hits.map((hit, i) => {
+      const source = hit.source || `Resultado ${i + 1}`;
+      return `[${source}]
+${hit.text}`;
+    }).join("\n\n---\n\n");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  RateLimitError,
+  VectorGov,
+  VectorGovError
+});

package/dist/index.mjs

@@ -0,0 +1,256 @@
+// src/types.ts
+var VectorGovError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.name = "VectorGovError";
+  }
+};
+var AuthenticationError = class extends VectorGovError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, 401, "AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends VectorGovError {
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, 429, "RATE_LIMIT_ERROR");
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://vectorgov.io/api/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var SYSTEM_PROMPT = `Voc\xEA \xE9 um assistente jur\xEDdico especializado em legisla\xE7\xE3o brasileira de licita\xE7\xF5es e contratos administrativos.
+
+Use APENAS as informa\xE7\xF5es fornecidas no contexto para responder. Se a informa\xE7\xE3o n\xE3o estiver no contexto, diga que n\xE3o encontrou.
+
+Ao citar artigos, use o formato: [Art. X] ou [Art. X, \xA7Y] ou [Art. X, inciso Y].
+
+Responda de forma clara, objetiva e em portugu\xEAs brasileiro.`;
+var VectorGov = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new AuthenticationError("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Faz uma requisição para a API
+   */
+  async request(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...options.headers
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        if (response.status === 401) {
+          throw new AuthenticationError(errorData.detail || "Invalid API key");
+        }
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("Retry-After");
+          throw new RateLimitError(
+            errorData.detail || "Rate limit exceeded",
+            retryAfter ? parseInt(retryAfter, 10) : void 0
+          );
+        }
+        throw new VectorGovError(
+          errorData.detail || `Request failed with status ${response.status}`,
+          response.status
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof VectorGovError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new VectorGovError("Request timeout", 408, "TIMEOUT");
+      }
+      throw new VectorGovError(
+        error instanceof Error ? error.message : "Unknown error"
+      );
+    }
+  }
+  /**
+   * Busca semântica em documentos legais
+   *
+   * @param query - Pergunta ou texto para buscar
+   * @param options - Opções de busca
+   * @returns Resultado da busca com métodos auxiliares
+   *
+   * @example
+   * ```typescript
+   * const results = await vg.search('O que é ETP?', {
+   *   topK: 5,
+   *   mode: 'balanced'
+   * });
+   *
+   * for (const hit of results.hits) {
+   *   console.log(`${hit.source}: ${hit.text.slice(0, 100)}...`);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const {
+      topK = 5,
+      mode = "balanced",
+      tipoDocumento,
+      ano
+    } = options;
+    const response = await this.request("/sdk/search", {
+      method: "POST",
+      body: JSON.stringify({
+        query,
+        top_k: topK,
+        mode,
+        tipo_documento: tipoDocumento,
+        ano
+      })
+    });
+    const hits = response.hits.map((hit) => ({
+      text: hit.text,
+      articleNumber: hit.article_number,
+      documentId: hit.document_id,
+      documentType: hit.document_type,
+      documentNumber: hit.document_number,
+      year: hit.year,
+      score: hit.score,
+      finalScore: hit.final_score,
+      source: hit.document_type && hit.document_number && hit.year ? `${hit.document_type} ${hit.document_number}/${hit.year}, Art. ${hit.article_number || "N/A"}` : void 0
+    }));
+    const metadata = {
+      latencyMs: response.latency_ms,
+      cached: response.cached,
+      queryId: response.query_id
+    };
+    return {
+      hits,
+      total: response.total,
+      metadata,
+      toMessages: (q) => this.hitsToMessages(hits, q),
+      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
+      }
+    };
+  }
+  /**
+   * Envia feedback (like/dislike) para uma resposta
+   *
+   * @param queryId - ID da query (de SearchMetadata ou AskMetadata)
+   * @param like - true para like, false para dislike
+   */
+  async feedback(queryId, like) {
+    const response = await this.request("/cache/feedback", {
+      method: "POST",
+      body: JSON.stringify({
+        query_hash: queryId,
+        is_like: like
+      })
+    });
+    return {
+      success: response.success,
+      message: response.message,
+      newLikes: response.new_likes,
+      newDislikes: response.new_dislikes
+    };
+  }
+  /**
+   * Converte hits para formato de mensagens de chat
+   */
+  hitsToMessages(hits, query) {
+    const context = this.hitsToContext(hits);
+    return [
+      {
+        role: "system",
+        content: SYSTEM_PROMPT
+      },
+      {
+        role: "user",
+        content: `Contexto:
+${context}
+
+Pergunta: ${query}`
+      }
+    ];
+  }
+  /**
+   * Converte hits para texto de contexto
+   */
+  hitsToContext(hits) {
+    return hits.map((hit, i) => {
+      const source = hit.source || `Resultado ${i + 1}`;
+      return `[${source}]
+${hit.text}`;
+    }).join("\n\n---\n\n");
+  }
+};
+export {
+  AuthenticationError,
+  RateLimitError,
+  VectorGov,
+  VectorGovError
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "vectorgov",
+  "version": "0.1.0",
+  "description": "SDK TypeScript para a API VectorGov - Busca semântica em legislação brasileira",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vectorgov",
+    "legal",
+    "legislation",
+    "semantic-search",
+    "rag",
+    "licitacao",
+    "brazil",
+    "sdk"
+  ],
+  "author": "VectorGov <contato@vectorgov.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/euteajudo/vectorgov-sdk-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/euteajudo/vectorgov-sdk-ts/issues"
+  },
+  "homepage": "https://vectorgov.io",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}