Pipeline de 10 fases para geração automática de mapas conceituais usando LLMs.
Conceitos transforma texto, PDFs, URLs, imagens, áudio, vídeo, código, schemas de banco e conversações em mapas conceituais estruturados no formato JSON-LD.
O pipeline combina extração heurística com validação por LLM, scoring automático baseado em Novak, classificação estrutural de Kinchin, e métricas de complexidade de Freeman — produzindo mapas que são tanto produto quanto contribuição de pesquisa.
Para quem:
- Estudantes — scaffolding, feedback formativo, comparação com mapas de especialistas
- Professores — processamento em lote, métricas de turma, detecção de misconceptions
- Analistas — elicitação de stakeholders, export para requisitos, integração Jira
- Pesquisadores — revisão de literatura, citações, proveniência, benchmark mode
- APIs — machine-readable, integração com Knowledge Graphs, sem prompts interativos
- Novak & Cañas (2006) — Teoria de mapas conceituais
- Ausubel (1968) — Teoria da aprendizagem significativa
- Kinchin et al. (2000) — Classificação de tipos estruturais (spoke, chain, net)
- Freeman (2004) — Métricas de complexidade estrutural
- Ruiz-Primo & Shavelson (1996) — Metodologia de avaliação
- 10 fases orquestradas com criticidade, timeout e cache configuráveis
- 9 modalidades de input (texto, URL, PDF, áudio, vídeo, imagem, código, DB schema, conversação)
- 4 topologias (hierarquia, rede, loop causal, temporal)
- 5 perfis de usuário que adaptam todas as fases do pipeline
- JSON-LD nativo com ontologia SKOS para interoperabilidade
- Scoring Novak automático (proposições, níveis, cross-links, exemplos)
- Classificação Kinchin (spoke / chain / net)
- Validação semântica contra knowledge base (LLM, Wikidata, custom)
- Refinamento self-healing com sugestão de cross-links
- Síntese multi-perspectiva (consenso/divergência entre mapas)
- Downstream generation (quiz, currículo, narrativa, ontologia, documentação)
- Export para JSON-LD, CXL, Mermaid, OWL/TTL, SVG, HTML, DOT, CSV
- Benchmark mode para avaliação contra gold standards de especialistas
- Feedback loop (meta-learning) — glossários crescem por domínio
- State persistence — resume de qualquer fase após interrupção
- Cost tracking por fase e acumulado
flowchart LR
P0[0 Multimodal\nIngestion] --> P1[1 Context\nConfig]
P1 --> P2[2 Concept\nExtraction]
P2 --> P3[3 Relation\nMapping]
P3 --> P4[4 Structure\nBuild]
P4 --> P5[5 Quality\nEval]
P5 --> P6[6 Refinement]
P6 --> P7[7 Perspective\nSynthesis]
P7 --> P8[8 Downstream\nGeneration]
P8 --> P9[9 Export\nRender]
style P0 fill:#e74c3c,color:#fff
style P1 fill:#e74c3c,color:#fff
style P2 fill:#e74c3c,color:#fff
style P3 fill:#e74c3c,color:#fff
style P4 fill:#e74c3c,color:#fff
style P5 fill:#3498db,color:#fff
style P6 fill:#3498db,color:#fff
style P7 fill:#3498db,color:#fff
style P8 fill:#3498db,color:#fff
style P9 fill:#e74c3c,color:#fff
| Fase | Nome | Critica | Timeout | Cache | Descricao |
|---|---|---|---|---|---|
| 0 | multimodal-ingestion | Sim | 5 min | Sim | Aquisicao de fonte com proveniencia |
| 1 | context-config | Sim | 2 min | Nao | Perfil, topologia, glossario, focus question |
| 2 | concept-extraction | Sim | 10 min | Sim | LLM extrai conceitos com confianca |
| 3 | relation-mapping | Sim | 10 min | Nao | LLM constroi proposicoes (first-class) |
| 4 | structure-build | Sim | 5 min | Nao | Construcao topology-aware, JSON-LD |
| 5 | quality-eval | Nao | 5 min | Nao | Novak scoring, Kinchin type, validacao semantica |
| 6 | refinement | Nao | 10 min | Nao | Self-healing, sugestao de cross-links |
| 7 | perspective-synthesis | Nao | 10 min | Nao | Consenso/divergencia multi-perspectiva |
| 8 | downstream-generation | Nao | 10 min | Nao | Quiz, curriculo, narrativa, ontologia |
| 9 | export-render | Sim | 5 min | Sim | JSON-LD, CXL, Mermaid, SVG, HTML |
Fases criticas (vermelho) interrompem o pipeline em caso de falha. Fases opcionais (azul) logam warning e continuam.
pip install anthropic richcp .env.example .env
# Editar .env e adicionar sua ANTHROPIC_API_KEYpython test_pipeline_llm.pyimport asyncio
from lib.phase_runner import get_phase_definitions, PhaseRunner
from lib.models import UserProfile
from lib.llm_client import AnthropicLLMClient
async def generate_map():
# Inicializar LLM client
llm = AnthropicLLMClient(model="claude-haiku-4-5-20251001", max_tokens=4096)
# Carregar definicoes das 10 fases
phases = get_phase_definitions()
runner = PhaseRunner(phases=phases, verbose=True)
# Metadata do input
metadata = {
"input_type": "text",
"source_content": "A fotossintese e o processo...",
"domain": "biologia",
"profile": "student",
}
# Executar pipeline
result = await runner.run(
item_id="meu-mapa",
metadata=metadata,
profile=UserProfile.STUDENT,
llm_client=llm,
)
print(f"Sucesso: {result.success}")
print(f"Fases: {result.completed_phases}/{result.total_phases}")
print(f"Custo: ${llm.cost_usd:.4f}")
asyncio.run(generate_map())from lib.pipeline_state import load_or_create_state
from pathlib import Path
state_mgr, resumed = load_or_create_state(
item_id="meu-mapa",
state_dir=Path("state/meu-mapa"),
metadata={"domain": "biologia"},
)
runner = PhaseRunner(phases=phases, state_manager=state_mgr, verbose=True)
result = await runner.run(item_id="meu-mapa", ...)O pipeline adapta todas as fases com base no perfil selecionado:
| Perfil | Scaffolding | Focus Q | Refinement | Downstream | Benchmark | Exports |
|---|---|---|---|---|---|---|
student |
Alto (3) | 3 opcoes | 2 iter. | quiz, narrative | Nao | jsonld, mermaid, html |
teacher |
Nenhum | 2 opcoes | Nao | quiz, curriculum, rubric | Nao | jsonld, mermaid, csv |
analyst |
Baixo (1) | 3 opcoes | 2 iter. | documentation, requirements | Nao | jsonld, mermaid, svg |
researcher |
Nenhum | 3 opcoes | 3 iter. | ontology, narrative, bibliography | Sim | jsonld, owl, mermaid, cxl |
api |
Nenhum | Nao | 2 iter. | Nao | Nao | jsonld |
Nem todo conhecimento e hierarquico. O pipeline suporta 4 topologias:
| Topologia | Quando usar | Exemplo |
|---|---|---|
hierarchy |
Relacoes geral → especifico (Novak classico) | Taxonomia biologica |
network |
Grafo plano, sem topo/base | Ecossistemas, politica |
causal-loop |
Feedback loops, dinamica de sistemas | Ciclo economico, homeostase |
temporal |
Evolucao no tempo, etapas de processo | Historia, metodologia agil |
| Modalidade | Enum | Descricao |
|---|---|---|
| Texto | text |
Texto livre em qualquer idioma |
| URL | url |
Pagina web (scraping automatico) |
pdf |
Documentos PDF | |
| Audio | audio |
Transcricao automatica |
| Video | video |
Transcricao + frames-chave |
| Imagem | image |
OCR + descricao visual |
| Codigo | code |
Repositorios, arquivos fonte |
| DB Schema | db-schema |
Schemas de banco de dados |
| Conversacao | conversation |
Dialogos, entrevistas, chats |
Artefatos gerados a partir do mapa conceitual:
| Tipo | Descricao | Perfis |
|---|---|---|
quiz |
Questoes de multipla escolha | student, teacher |
curriculum |
Plano curricular | teacher |
narrative |
Texto explicativo | student, researcher |
ontology |
OWL/TTL formal | researcher |
documentation |
Documentacao tecnica | analyst |
requirements |
Requisitos de sistema | analyst |
bibliography |
Referencias bibliograficas | researcher |
rubric |
Rubrica de avaliacao | teacher |
| Formato | Extensao | Descricao |
|---|---|---|
| JSON-LD | .jsonld |
Formato nativo, SKOS ontology |
| JSON-LD Compact | .compact.jsonld |
Versao compacta |
| Mermaid | .md |
Diagrama renderizavel no GitHub |
| CXL | .cxl |
CmapTools XML format |
| OWL/TTL | .owl.ttl |
Web Ontology Language (Turtle) |
| HTML | .html |
Visualizacao standalone |
| DOT | .dot |
Graphviz format |
| SVG | .svg |
Vetor escalavel |
| CSV | .csv |
Tabular para spreadsheets |
from lib.config import PipelineSettings
settings = PipelineSettings(
max_concepts_per_map=50, # Limite de conceitos
max_propositions_per_map=100, # Limite de proposicoes
min_confidence_threshold=0.5, # Confianca minima LLM
max_refinement_iterations=2, # Iteracoes de refinamento
default_model="claude-sonnet-4-20250514",
enable_cost_tracking=True,
cost_alert_threshold_usd=1.0,
output_dir="output",
)Glossarios de predicados por categoria semantica (causal, structural, functional, comparative, temporal) com suporte a glossarios por dominio em data/glossaries/.
from lib.config import DEFAULT_PREDICATES, DOMAIN_GLOSSARIES
# Predicados causais disponiveis
print(DEFAULT_PREDICATES["causal"])
# ["causa", "provoca", "resulta em", "leva a", ...]Conceitos/
├── lib/ # Biblioteca principal
│ ├── __init__.py # Exports publicos
│ ├── models.py # Modelos de dados (JSON-LD native)
│ ├── config.py # Configuracoes e perfis
│ ├── phase_runner.py # Orquestrador de 10 fases
│ ├── llm_client.py # Client Anthropic async
│ ├── pipeline_state.py # State persistence (resume)
│ ├── progress.py # Progress tracker (Rich)
│ ├── benchmark.py # Benchmark mode (research)
│ └── handlers/ # Handlers por fase
│ ├── phase_0_multimodal_ingestion.py
│ ├── phase_1_context_config.py
│ ├── phase_2_concept_extraction.py
│ ├── phase_3_relation_mapping.py
│ ├── phase_4_structure_build.py
│ ├── phase_5_quality_eval.py
│ ├── phase_6_refinement.py
│ ├── phase_7_perspective_synthesis.py
│ ├── phase_8_downstream_generation.py
│ └── phase_9_export_render.py
├── data/
│ ├── benchmarks/ # Gold standards e resultados
│ └── glossaries/ # Glossarios por dominio
├── output/
│ ├── maps/ # Mapas JSON-LD (versionados)
│ ├── exports/ # Formatos de exportacao
│ └── artifacts/ # Artefatos downstream
├── state/ # State persistence (resume)
├── test_pipeline_llm.py # Teste end-to-end com LLM
├── .env.example # Template de configuracao
└── MAPAS-CONCEITUAIS-PESQUISA.md # Pesquisa teorica completa
O pipeline implementa rigorosamente a teoria de mapas conceituais:
Score = proposicoes * 1 + niveis_hierarquia * 5 + crosslinks * 10 + exemplos * 1
| Tipo | Padrao | Indica |
|---|---|---|
| Spoke | Tudo conectado ao centro | Aprendizagem superficial |
| Chain | Sequencia linear | Procedural, nao relacional |
| Net | Multiplas interconexoes | Compreensao genuina |
- Density — edges / (nodes * (nodes-1))
- Complexity ratio — edges / nodes
- Hierarchy index — longest path / (nodes-1)
- Crosslink ratio — crosslinks / total edges
- Degree centrality e Betweenness centrality por conceito
Seguindo Novak: conceito + frase de ligacao + conceito = proposicao. Cada proposicao possui proveniencia, confianca e flag de cross-link (reconciliacao integrativa).
O benchmark mode transforma o pipeline de produto em contribuicao de pesquisa.
from lib.benchmark import ConceptMapBenchmark
benchmark = ConceptMapBenchmark(
gold_dir="data/benchmarks/gold-standards",
results_dir="data/benchmarks/results",
)
# Avaliar mapa gerado contra gold standard
result = benchmark.evaluate(generated_map, gold_standard)
benchmark.save_result(result)Metricas:
- Precision / Recall / F1 de conceitos
- Precision / Recall / F1 de proposicoes (matching semantico)
- Similaridade estrutural (metricas de grafo)
- Eficiencia custo-qualidade (qualidade por dolar)
O sistema aprende com cada mapa gerado:
from lib.benchmark import FeedbackCollector
feedback = FeedbackCollector(feedback_dir="data/feedback")
# Registrar predicados aprendidos
feedback.record_predicates("biologia", ["causa", "regula", "inibe"])
# Registrar misconceptions detectadas
feedback.record_misconception(
domain="biologia",
misconception="Plantas nao respiram",
correction="Plantas realizam respiracao celular e fotossintese",
)Templates para especialistas criarem ground truth:
from lib.benchmark import create_gold_standard_template
create_gold_standard_template(
domain="fotossintese",
focus_question="Como a energia luminosa e convertida em energia quimica?",
)MIT
- Fork o repositorio
- Crie uma branch para sua feature (
git checkout -b feature/nome) - Siga os padroes existentes no codebase
- Adicione testes para novas funcionalidades
- Abra um Pull Request