Terraform RAG

Base de conhecimento com inteligência artificial para seus módulos Terraform. Indexe, pesquise, componha e audite - tudo em um só lugar.

GitHub
5

Documentação

⬡

Terraform RAG

Base de conhecimento com IA para seus módulos Terraform.
Indexe, pesquise, componha e audite - tudo em um só lugar.

Demonstração ao vivo - Arquitetura - Início rápido - Servidor MCP

Python 3.12 FastAPI pgvector MCP License

Experimente a demonstração ao vivo

Interface web - navegue por mais de 2700 módulos em mais de 175 repositórios (AWS / Azure / GCP):

https://terraform-rag.io

Login: demo@terraform-rag.io / demo (somente leitura)

MCP - conecte sua IDE à base de conhecimento:

{
  "mcpServers": {
    "terraform-rag": {
      "type": "http",
      "url": "https://terraform-rag.io/mcp",
      "headers": {
        "Authorization": "Bearer trag_6c495d7a027369cb5d324d877626c272"
      }
    }
  }
}

9 ferramentas disponíveis: query_modules, pick_modules, list_modules, get_module_details, get_dependencies, get_module_usage, find_similar_usages, fetch_example_code, get_stats (list_modules também aceita semantic_query para busca em linguagem natural).

O que faz

Aponte-o para seus repositórios de módulos Terraform. Ele os clona, analisa cada arquivo HCL, gera embeddings e constrói uma base de conhecimento pesquisável em PostgreSQL + pgvector. Em seguida, ele aprende como esses módulos são realmente usados em seus repositórios consumidores - padrões de nomenclatura, convenções de variáveis, estratégias de marcação, layouts de implantação - e destila isso em orientações autoritativas.

Um pipeline agêntico (Claude, Bedrock ou qualquer modelo compatível com OpenAI) explora a base de conhecimento em múltiplas etapas de uso de ferramentas para montar respostas fundamentadas e revisáveis - recuperação assistiva com um humano no circuito, não um gerador de código autônomo. Consulte pela interface web, pela API REST ou diretamente da sua IDE via MCP.

Veja em ação

Module browser
Navegador de Módulos - mais de 2700 módulos em mais de 175 repositórios 		Agentic query
Composição Agêntica - chamadas de ferramentas e raciocínio em tempo real
Generated HCL
HCL Gerado - saída com realce de sintaxe 		Knowledge browser
Navegador de Conhecimento - convenções e padrões de uso
Index jobs
Trabalhos de Indexação - painel de indexação de repositórios 		Audit logs
Registros de Auditoria - trilha completa de chamadas LLM, MCP e API

Recursos

Pipeline de Consulta Agêntica - mais do que uma única busca RAG. O LLM navega pelos módulos, verifica detalhes, lê convenções e busca exemplos de código em múltiplas etapas de uso de ferramentas antes de compor uma resposta para você revisar. Quatro modos de consulta: compor, buscar, otimizar e auditar.

Camada de Conhecimento - indexa repositórios consumidores para aprender padrões de uso do mundo real. Destila convenções em seis dimensões (nomenclatura, variáveis, marcação, layout, versões, implantação) e as trata como orientação autoritativa em todos os prompts.

Servidor MCP - endpoint HTTP Streamable funciona com Claude Code, Cursor, Windsurf e qualquer cliente compatível com MCP. Consulte sua base de conhecimento de módulos diretamente da sua IDE.

Grafo de Dependências - CTEs recursivos do PostgreSQL mapeiam a árvore completa de dependências entre módulos. Descubra o que depende do quê, rastreie impactos e visualize relacionamentos com um grafo direcionado por força D3.

Rastreamento de Versões - descoberta automática de tags git com histórico de versões por módulo. Cache de hash de código evita chamadas redundantes de LLM/embedding na reindexação.

Backend LLM Flexível - Anthropic (direto ou Bedrock), OpenRouter, Ollama ou qualquer endpoint compatível com OpenAI. Troque de modelo sem alterar o código.

Integração CI/CD - fluxo de trabalho do GitHub Actions e endpoints de webhook para reindexação automática quando os arquivos .tf mudam.

Autenticação - desativada (padrão), e-mail/senha local com JWT ou SSO encerrado por ALB via AWS Identity Center / OIDC.

Início Rápido

# 1. Clone and configure
git clone https://github.com/krzysztofgawrys/rag-for-terraform.git
cd rag-for-terraform
cp .env.example .env
# Edit .env - set POSTGRES_PASSWORD, JWT_SECRET, and your LLM API key

# 2. Start everything
docker compose up -d

# 3. Index your first repo
curl -X POST http://localhost:8000/index/ \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "git@github.com:org/tf-modules.git", "branch": "main"}'
ServiçoURL
Frontendhttp://localhost:3000
Documentação da APIhttp://localhost:8000/docs
Endpoint MCPhttp://localhost:8000/mcp/

Para repositórios privados, coloque sua chave de implantação SSH em ./worker_deploy_key (ou defina SSH_KEY_PATH em .env).

Servidor MCP

Conecte qualquer cliente compatível com MCP a http://localhost:8000/mcp/.

Claude Code (.mcp.json):

{
  "mcpServers": {
    "terraform-rag": {
      "type": "http",
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Ferramentas disponíveis: query_modules, pick_modules, list_modules, get_module_details, get_dependencies, get_module_usage, find_similar_usages, fetch_example_code, get_stats.

Configuração do LLM

ModoLLM_BASE_URLExemplo de LLM_MODEL
Anthropic (direto)(vazio)claude-sonnet-4-6
AWS Bedrock(defina AWS_BEDROCK_REGION)us.anthropic.claude-sonnet-4-6-20250514-v1:0
OpenRouterhttps://openrouter.ai/api/v1anthropic/claude-sonnet-4-6
Ollama (local)http://ollama:11434/v1qwen2.5-coder:32b

Um modelo separado e barato pode ser usado para descrições de módulos durante a indexação (variáveis DESCRIPTION_LLM_*).

Arquitetura

  Browser         AI Agent / IDE
     |               |
+---------+      +--------+      +----------------+
| Frontend|----->|  API   |----->| PostgreSQL 16  |
| (Vite)  |      | FastAPI|      | + pgvector     |
+---------+      +---+----+      +----------------+
                     |
                +----+----+
                | Worker  |      +-------+
                | (Celery)|----->| Redis |
                +---------+      +-------+

Para o mergulho técnico completo - detalhes da pilha, estrutura de diretórios, endpoints de API, internals do agente, pipeline da camada de conhecimento, limitações conhecidas e notas de implantação - consulte docs/ARCHITECTURE.md.

Licença

Business Source License 1.1 - consulte LICENSE para detalhes.

  • Uso não produtivo (avaliação, testes, desenvolvimento) é permitido
  • Uso produtivo requer uma licença comercial do autor
  • Em 2029-05-25 a licença converte para AGPL-3.0