📐 Engineering-CAD-AI — de pedido em linguagem natural a revisão CAD verificada, com aprovação humana

Python · ezdxf · Pydantic · FastAPI · MCP · Claude (opcional) · pytest · GitHub Actions

🟡 Status

🟡 MVP técnico funcional — DXF → Engineering IR → plano tipado → aprovação → revisão nova verificada. O fluxo completo roda offline, sem licença de CAD e sem chave de API: 113 testes passam (1 teste opt-in com o Claude real fica pulado por custo) e a demo grava a revisão B com os 9 checks de releitura em PASS. AutoCAD, FreeCAD e Creo estão com contrato definido e marcados CAD_REAL_NOT_RUN (sem instalação licenciada); busca híbrida e similaridade ainda não foram iniciadas.

Related MCP server: AutoCAD MCP Pro

Descrição / Contexto

Em engenharia mecânica, boa parte do trabalho repetitivo é alterar desenhos: acrescentar um furo, mover uma feature, anotar uma revisão. Pedir isso direto a um modelo de linguagem é arriscado — o modelo erra geometria, não deixa rastro e pode sobrescrever o arquivo errado. OCR sobre o desenho também é o caminho errado quando o arquivo é vetorial: a geometria exata já está no DXF.

Este repositório implementa a alternativa: o modelo (opcional) só interpreta a intenção; código determinístico lê e calcula a geometria; um validador decide; um humano aprova o plano exato; o adaptador CAD grava uma revisão nova e o resultado é reaberto e conferido. Tudo com evidência (dxf:handle:<H>), hashes e trilha de auditoria.

Nome: Engineering Document & CAD Intelligence (EDCI) é o nome do escopo; o pacote Python é engcad.

🧭 Origem do Projeto

O projeto nasceu de uma pesquisa sobre como ligar agentes de IA a sistemas CAD (docs/research/integracao-agentes-cad.md): APIs do AutoCAD (.NET, AutoLISP/COM, Design Automation), Creo (VB API/J-Link/CREOSON), FreeCAD, CAD-como-código (ezdxf, CadQuery, build123d) e cerca de vinte servidores MCP comunitários conferidos no GitHub.

Conclusões que definiram o projeto:

1. O padrão que funciona é plano tipado + execução determinística + verificação, não "o LLM desenha por coordenadas".

2. CAD-como-código / arquivo neutro é o caminho mais robusto para começar: headless, versionável, testável e sem licença.

3. Vários servidores MCP de CAD expõem execute_lisp/execute_python — na prática, um shell. As anotações MCP são dicas, não controle: a segurança tem de morar no servidor.

4. Texto de desenho (carimbo, notas) é dado não confiável e pode conter prompt injection.

5. Integração com CAD comercial só se declara pronta depois de testada na instalação real.

Plano com gates de evidência: F0 base → F1 IR → F3 plano → F4 execução segura (MVP estrito, concluído) → F2 conhecimento → F5 similaridade → F8 adaptadores comerciais (ROADMAP.md).

🎯 Objetivo

• Ler DXF sem perder nada: entidades suportadas viram IR tipado; as demais ficam registradas.

• Nunca inventar: unidade desconhecida, campo ausente ou pedido ambíguo resultam em None, UNITS_UNKNOWN ou NEEDS_CLARIFICATION.

• Converter pedido → operações de uma allowlist fechada, validadas por geometria determinística.

• Exigir aprovação humana vinculada ao hash do plano e ao SHA da fonte.

• Gravar sempre em arquivo novo e provar por releitura que só mudou o que foi aprovado.

• Expor tudo por CLI, API e MCP sem dar ao agente ferramentas de aprovação ou execução de código.

🔬 Linha de Pesquisa / Desenvolvimento

• Representação intermediária de desenho técnico com proveniência por entidade.

• Planejamento de alterações CAD por LLM com saída estruturada e abstenção.

• Validação geométrica 2D (ponto-em-polígono, folga ao contorno, colisão de furos).

• Segurança de agentes com ferramentas (MCP fechado, prompt injection em artefatos, aprovação humana).

• Verificação pós-escrita por oráculo independente (readback + invariantes).

🏗️ Arquitetura

 DXF ─► sniff de formato ─► parser ezdxf ─► Engineering IR v1 ─────────────┐
 PDF/imagem ─► ponte ocr_core (opcional) ─► evidências de carimbo          │
                                                                           ▼
 pedido ─► planner ├─ determinístico (regex pt/en)                 ActionPlan (allowlist)
                   └─ Claude (opcional, desligado por padrão) ──►  plan_hash · base_sha
                                                                           │
                         validador determinístico + invariantes ◄──────────┤
                         simulação ─► diff de entidades ─► preview SVG     │
                                                                           ▼
                         aprovação humana (HMAC local, CLI/API) ─► APPROVED
                                                                           │
                         revalida a fonte (TOCTOU) ─► adaptador CAD ─► arquivo staging
                                                                           │
                         readback independente ─► 9 checks ─► rename atômico
                                                                           ▼
                         manifest.json · report.md · audit.jsonl · nova revisão no workspace

Estados do plano: PROPOSED → APPROVED → EXECUTING → COMPLETED, com NEEDS_CLARIFICATION, REJECTED e FAILED terminais. Transições fora da tabela são recusadas (INVALID_STATE).

⚙️ Funcionamento

1. Ingestão — o arquivo é identificado pelo conteúdo, copiado como somente leitura para sources/<rev>/ e convertido em IR (rev-<sha16>).

2. Plano — o pedido vira operações tipadas; faltando diâmetro, posição, layer ou alvo, o plano fica NEEDS_CLARIFICATION.

3. Validação — contorno com folga de 0,1 mm, colisão com furos existentes e novos, layer existente, handle existente, contorno protegido; os invariantes são calculados aqui, não pelo modelo.

4. Preview — simulação em memória, diff por handle e SVG (verde = novo, vermelho = removido, laranja = movido).

5. Aprovação — humano aprova o plano exato; o registro assina plan_id|plan_hash|base_sha|aprovador|data.

6. Execução — confere aprovação e SHA, re-lê a fonte, revalida, grava em staging pelo adaptador, reabre o arquivo e checa os invariantes; só então renomeia para o nome final.

7. Evidência — manifest, relatório Markdown e eventos de auditoria ligam fonte, plano, aprovação e saída.

"adicione furo central Ø10 em (60,40)"
  → add_circle{center_mm:(60,40), diameter_mm:10, layer:HOLES}   (layer herdado dos furos existentes)
  → valid: dentro do contorno, sem colisão → invariantes: 11 preservadas, +1, CIRCLE 4→5
  → aprovado por humano → plate_revA__<plan>.dxf → readback 9/9 PASS → fonte com o mesmo SHA

🧠 Verificação / Modelagem

O oráculo de readback é independente do caminho de escrita: o arquivo final é reaberto pelo parser e comparado com a simulação por assinatura geométrica (tipo, layer, geometria arredondada a 1e-6 mm), não pelo retorno da função que gravou.

🧪 Desenvolvimento Experimental

pesquisa → ADR → fixtures + golden → parser → plano/validador → execução + readback → interfaces → demo

Achados reais (não plantados)

Detalhes em WORKLOG.md; decisões em ADR 0001.

🛠️ Tecnologias

Linguagens: Python 3.10+ CAD: ezdxf 1.4.5 (DXF R12–R2018) Contratos: Pydantic 2 (schemas com extra=forbid), JSON Schema exportado Interfaces: FastAPI, SDK mcp 2.x (MCPServer, stdio), argparse IA (opcional): SDK anthropic — planner Claude com saída JSON validada Integração: ocr_core do repositório OCR para PDF/imagem Qualidade: pytest, GitHub Actions (Linux/Windows × 3.10/3.12)

📊 Resultados

Limites: são fixtures sintéticas de uma peça simples; não há benchmark de desenhos reais nem medida de desempenho. Não foi medida taxa de acerto de LLM (EX-04 da pesquisa está planejado).

🖼️ Evidências

• Relatório da demo — pedido, plano, hashes, aprovação e os 9 checks.

• Manifest da demo — mesmo conteúdo em JSON.

• JSON Schemas — engineering_ir.schema.json e cad_action_plan.schema.json.

🚀 Aplicações

• Alterações repetitivas em desenhos 2D de chapas, suportes e gabinetes com trilha de aprovação.

• Camada de ferramentas segura para assistentes (Claude Desktop/Code via MCP) em ambiente de engenharia.

• Base para comparar revisões (engcad compare) e auditar o que mudou entre arquivos.

• Ponto de partida para adaptadores de CAD comercial com contrato e testes já definidos.

🔭 Visão de Longo Prazo

DXF 2D verificado (hoje)
   ↓
code-CAD 3D (build123d/CadQuery → STEP + vistas DXF, checagem de volume/sólido)
   ↓
conhecimento: busca híbrida com citação por source_anchor e filtro de revisão
   ↓
similaridade explicável entre projetos (geometria + texto + regras, com benchmark rotulado)
   ↓
adaptadores licenciados (AutoCAD .NET / APS, Creo, FreeCAD) passando nos mesmos contratos
   ↓
identidade real, RBAC e observabilidade de custo/latência por pedido

🗺️ Roadmap

• F0 — Base ✅ Concluída — pacote, CI, ADRs, fixtures e golden.

• F1 — Parse + IR ✅ Concluída — test_parser.py (14 testes).

• F3 — Plano ✅ Concluída — allowlist, validador e intenção (35 testes).

• F4 — Execução segura ✅ Concluída — aprovação, copy-on-write, readback (27 + 14 testes).

• F6 — Agente 🟡 Parcial — MCP fechado testado; Claude real não executado.

• F7 — Interface 🟡 Parcial — API e CLI; sem dashboard web.

• F2 — Conhecimento ⏳ Planejada — busca híbrida com citação.

• F5 — Similaridade ⏳ Planejada — depende de pares rotulados.

• F8 — CAD comercial ⛔ Bloqueada — depende de licença/instalação.

Detalhe em ROADMAP.md.

🕓 Histórico e Mudanças

CHANGELOG.md · WORKLOG.md

🔮 Próximos Passos

Concluídos nesta versão ✅ — fluxo DXF ponta a ponta com aprovação e readback; MCP sem ferramentas de aprovação/execução de código; ponte com o motor documental do OCR.

Dependem de terceiros — instalação/licença de AutoCAD ou Creo para os adaptadores reais; chave de API e autorização de dados para medir o planner Claude real.

Próximos técnicos (v0.2) — adaptador build123d para 3D; índice híbrido com citação por source_anchor; benchmark de 100 pedidos (EX-04) comparando determinístico × Claude × modelo local; dashboard web de revisão/aprovação.

▶️ Como rodar localmente

Pré-requisitos: Python 3.10+.

pip install "ezdxf==1.4.5" "pydantic>=2.7,<3" fastapi httpx "mcp>=2.0" pytest   # ou: pip install -e ".[api,mcp,dev]"

python -m pytest -q                                   # 113 passam, 1 opt-in pulado

# demo ponta a ponta (gera a placa, planeja, mostra preview e para pedindo aprovação)
PYTHONPATH=src python -m engcad demo -w demo-ws
PYTHONPATH=src python -m engcad demo -w demo-ws --approve     # aprovação DEMO rotulada

# fluxo manual
PYTHONPATH=src python -m engcad fixtures --out fixtures
PYTHONPATH=src python -m engcad ingest fixtures/plate_revA.dxf -w ws
PYTHONPATH=src python -m engcad plan <revision_id> "adicione furo central Ø10 em (60,40)" -w ws
PYTHONPATH=src python -m engcad preview <plan_id> -w ws
PYTHONPATH=src python -m engcad approve <plan_id> --approver "Seu Nome" --reason "revisado" -w ws
PYTHONPATH=src python -m engcad apply <plan_id> -w ws
PYTHONPATH=src python -m engcad compare fixtures/plate_revA.dxf ws/outputs/<plan_id>/plate_revA__*.dxf

# interfaces
PYTHONPATH=src python -m engcad serve-api -w ws      # http://127.0.0.1:8077/docs
PYTHONPATH=src python -m engcad serve-mcp -w ws      # MCP stdio

📁 Estrutura do repositório

Engineering-CAD-AI/
├── src/engcad/
│   ├── ir.py, parser_dxf.py, units.py, geometry.py   # leitura e contrato do IR
│   ├── plan.py, intent.py, llm.py, validate.py        # planejamento e validação
│   ├── diff.py, render.py, verify.py, report.py       # diff, preview, readback, relatório
│   ├── approval.py, service.py                        # aprovação, estados, workspace, auditoria
│   ├── adapters/ (base, ezdxf, mock, commercial)      # protocolo por capacidade
│   ├── api.py, mcp_server.py, cli.py, ocr_bridge.py   # interfaces e integrações
│   └── fixtures.py                                    # peças sintéticas
├── tests/ (7 arquivos, 114 testes) + fixtures/golden/
├── schemas/                                           # JSON Schema do IR e do plano
├── docs/ adr/ · research/ · evidence/ · TEST_MATRIX.md
├── .github/workflows/ci.yml
└── CHANGELOG.md · ROADMAP.md · WORKLOG.md · LICENSE

Não versionado: workspaces (*-ws/, engcad-workspace/), que contêm fontes, aprovações e a chave HMAC local do aprovador.

📚 Documentação

⚠️ Limitações

• Somente DXF 2D. DWG, STEP e feature tree nativa exigem adaptadores licenciados (não executados).

• Geometria interpretada por regra simples: contorno = maior LWPOLYLINE fechada sem bulge; furo = CIRCLE dentro do contorno. Polilinhas com arcos, blocos (INSERT não é explodido) e espaço de papel não entram na validação.

• Sem GD&T e sem tolerâncias: o IR registra tolerância como desconhecida; nada é inferido.

• Aprovação demo (HMAC com chave local) não é autenticação corporativa; não há RBAC nem multiusuário.

• Planner Claude só testado com cliente falso; qualidade real não medida.

• PDF/imagem: a ponte só extrai campos de carimbo literais; cotas a partir de raster não existem.

• Sem validação de engenharia: saídas são R&D / NOT FOR MANUFACTURE.

• Persistência em arquivos JSON no workspace (sem banco, sem fila); adequado a uso local.

Status

🟡 MVP técnico funcional — v0.1.0. Fluxo DXF ponta a ponta implementado e testado (113 testes passam, readback 9/9 na demo); adaptadores de CAD comercial e planner Claude real ainda não executados.

Contexto / Observações

Peça de portfólio e laboratório de P&D, sem afiliação com fornecedores de CAD. Todas as peças são sintéticas e geradas por código; nenhum desenho industrial real foi usado. Contagens de estrelas na pesquisa são instantâneos de 2026-10-20. Nenhuma métrica de produção é alegada.

🔗 Projetos Relacionados

🤖 Autor

Yuri Fernando Dubbern

Engenharia Elétrica · Ciência da Computação · Inteligência Artificial · Sistemas Embarcados · Projeto de Hardware · Pesquisa e Desenvolvimento

LinkedIn · GitHub · Lattes · Linktree

Licença

MIT — ver LICENSE.