Gemini API

# Option A: Via CLI interactive
vectora config set --key GEMINI_API_KEY

# Option B: Via .env
echo "GEMINI_API_KEY=sk-..." >> .env

# Option C: Via config.yaml
# vectora.config.yaml
providers:
  llm:
    name: "gemini"
    model: "gemini-3-flash"
    api_key: "${GEMINI_API_KEY}"

vectora config list
# Should show GEMINI_API_KEY: ••••••••••

# vectora.config.yaml
providers:
  llm:
    model: "gemini-3-flash"

    # Fallback if primary fails
    fallback_model: "gemini-pro"
    fallback_on:
      - "rate_limit_exceeded"
      - "timeout"

vectora review \
  --file src/cache/redis.ts \
  --context "cache patterns in project" \
  --criteria "security, performance, testability" \
  --model gemini-pro \
  --output review.md

# Code Review: src/cache/redis.ts

## Security

Redis PASSWORD in .env (not hardcoded)
TTL implemented (prevents stale cache)
No rate limiting for invalidation
Compared with: src/cache/memory.ts (better implemented)

## Performance

Cache hit rate 89% (project has 3 similar implementations)
Avoids N+1 queries (pattern followed in order.service.ts)

## Testability

Missing RedisClient mocks
See example at: src/**tests**/cache.mock.ts:23

## Recommendations

1. Add event-based invalidation
   (See patterns in src/events/cache-invalidator.ts)

2. Implement circuit breaker
   (Similar to: src/resilience/circuit-breaker.ts)

3. Add fallback tests when Redis fails
   Test example: src/**tests**/cache-fallback.test.ts

## Alignment

This code follows 95% of project patterns.
Ready to merge after feedback above.

vectora generate-docs \
  --from "src/routes/api.ts" \
  --type "openapi" \
  --llm gemini-3-flash \
  --output docs/api.openapi.yaml

openapi: 3.0.0
info:
  title: Vectora API
  version: 1.0.0

paths:
  /search:
    post:
      summary: "Semantic search (generated by Gemini + context)"
      description: |
        Search by semantic similarity using embeddings.
        Implementation: src/routes/search.ts
        Uses: Context Engine with Voyage 4
        Latency: ~230ms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "429":
          description: "Rate limited (see: src/middleware/rate-limit.ts)"

vectora analyze-performance \
  --query "Search is taking 2s. What's the problem?" \
  --include-logs "vectora.log" \
  --model gemini-pro \
  --output perf-report.md

# Performance Analysis Report

## Problem Identified

Search taking 2000ms when SLA is 300ms.

## Root Cause

Reranking via Voyage Rerank 2.5 taking 1.2s.

**Evidence in code:**

- src/context-engine.ts:145
  `const reranked = await reranker.rank(topK=100, maxTokens=2048)`

- Problem: maxTokens too high
- Comparison: another project uses maxTokens=512 (src/search/optimized.ts:23)
  Result: 180ms vs your 1200ms

## Solutions

1. **Quick win** (implement today)
   Reduce maxTokens from 2048 → 512
   Expected result: 1.8s → 0.8s

2. **Medium-term** (next sprint)
   Implement embedding cache
   See pattern at: src/cache/embedding-cache.ts

3. **Long-term**
   Use Gemini 3 Flash as reranker instead of Voyage
   Trade-off: faster but less precise
   Test: src/**tests**/reranker-comparison.ts

## Impact

- Current: p95=2000ms, p99=3000ms
- After fix #1: p95=800ms, p99=1500ms
- After fix #2: p95=400ms, p99=600ms

## Recommendation

Apply fix #1 today (10 min change), measure before #2.

vectora generate-types \
  --from "src/responses/" \
  --target "typescript" \
  --model gemini-3-flash \
  --output "src/types/generated.ts"

// src/types/generated.ts
// Auto-generated by Gemini via Vectora Context Engine

export interface SearchResponse {
  chunks: SearchChunk[];
  metadata: {
    retrieval_precision: number;
    latency_ms: number;
    total_searched: number;
  };
  // Pattern seen in src/types/search.ts
}

export interface SearchChunk {
  file: string;
  line_start: number;
  line_end: number;
  content: string;
  precision: number; // 0.0 - 1.0
  // Compatible with: src/__tests__/search.mock.ts
}

// Generated types 98% compatible with existing codebase
// Follows conventions from src/types/*
// Includes guardrail types (src/security/guardian.types.ts)

providers:
  llm:
    model: "gemini-3-flash"
    system_prompt: |
      You are an expert in TypeScript code.
      Always cite line numbers when responding.
      Keep explanations concise.
      Focus on security and performance.

providers:
  llm:
    model: "gemini-3-flash"
    temperature: 0.7 # 0=deterministic, 1=creative
    top_p: 0.95 # Nucleus sampling
    max_tokens: 2048
    stop_sequences:
      - "\n---\n"

vectora analyze \
  --query "Explain the authentication module" \
  --stream # Output in real-time
  --model gemini-pro

Your prompt: "Why is this test failing?"

Context sent to Gemini:
{
  "chunks": [
    {"file": "spec/auth.test.ts", "content": "..."},
    {"file": "src/auth/jwt.ts", "content": "..."},
    {"file": "src/auth/guards.ts", "content": "..."}
  ],
  "precision": 0.78,
  "retrieval_time_ms": 234
}

Gemini reads context + your prompt → response

providers:
  reranker:
    name: "gemini" # Instead of "voyage"
    model: "gemini-3-flash"
    # Gemini evaluates relevance of each chunk
    # More accurate, but slower

providers:
  llm:
    safety:
      block_on_sensitive_patterns:
        - "api_key"
        - "password"
        - "secret"

      block_keywords:
        - "exploit"
        - "malware"

VECTORA_LOG_LEVEL=debug vectora analyze "..."

# Logs include:
# [Gemini Request] tokens=500, prompt_hash=abc123
# [Gemini Response] tokens=200, safety_rating=safe

vectora cost-report --period month

# Output:
# Gemini API usage:
# gemini-3-flash: $0.00 (within free tier)
# Tokens: 1,234,567 / 1,500,000

# Check if key is configured
echo $GEMINI_API_KEY

# If empty, configure
export GEMINI_API_KEY="your-value"

# Test if valid
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash:generateContent" \
  -H "Content-Type: application/json" \
  -d "{\"contents\": [{\"parts\": [{\"text\": \"test\"}]}]}" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

providers:
  llm:
    name: "gemini"
    fallback_model: "local-mistral" # Ollama local

vectora models list
# Shows: gemini-3-flash, gemini-pro, ...