abnt-mcp 0.2.0__py3-none-any.whl

abnt_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""ABNT Copilot MCP - Servidor Model Context Protocol definitivo para trabalhos acadêmicos no padrão ABNT."""
+
+from abnt_mcp.server import mcp, main
+
+__version__ = "0.2.0"
+__all__ = ["mcp", "main", "__version__"]

abnt_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Ponto de entrada quando executado via `python -m abnt_mcp`."""
+
+from abnt_mcp.server import main
+
+if __name__ == "__main__":
+    main()

abnt_mcp/config.py

@@ -0,0 +1,266 @@
+"""Configurações, padrões de regex e constantes para o ABNT Copilot MCP."""
+
+from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+import re
+
+SERVER_NAME = "abnt-mcp"
+SERVER_VERSION = "0.1.0"
+DEFAULT_USER_AGENT = f"{SERVER_NAME}/{SERVER_VERSION} (mailto:abnt-copilot@example.com)"
+
+
+def get_current_year() -> int:
+    """Retorna o ano corrente dinamicamente (evita datas hardcoded)."""
+    return datetime.now().year
+
+
+def get_default_author_source() -> str:
+    """Retorna a indicação de fonte autoral padrão com o ano corrente."""
+    return f"Elaborado pelo autor ({get_current_year()})."
+
+
+def validate_safe_path(target_path: str | Path, base_dir: str | Path | None = None) -> Path:
+    """
+    Valida caminhos de arquivo contra caracteres nulos e path traversal fora de base_dir.
+    """
+    raw_str = str(target_path)
+    if "\x00" in raw_str or not raw_str.strip():
+        raise ValueError(f"Caminho inválido ou malformado: '{target_path}'")
+
+    resolved = Path(target_path).expanduser().resolve()
+    if base_dir is not None:
+        base_resolved = Path(base_dir).expanduser().resolve()
+        try:
+            resolved.relative_to(base_resolved)
+        except ValueError as exc:
+            raise ValueError(
+                f"Operação bloqueada por segurança (Path Traversal): '{resolved}' está fora do diretório base '{base_resolved}'."
+            ) from exc
+    return resolved
+
+# Catálogo de Regras Normativas Canônicas (Spec-Driven Development)
+# Sincronizado com specs/01-normative-catalog.spec.md
+NORMATIVE_RULES: dict[str, dict[str, str]] = {
+    "NBR14724-R01": {
+        "standard": "ABNT NBR 14724:2011",
+        "clause": "Seção 4.2",
+        "title": "Elementos pré-textuais, textuais e pós-textuais obrigatórios de monografias",
+        "severity": "error",
+    },
+    "NBR14724-R02": {
+        "standard": "ABNT NBR 14724:2011",
+        "clause": "Seção 5.3",
+        "title": "Paginação física: contagem na Folha de Rosto e impressão arábica a partir da Introdução",
+        "severity": "critical",
+    },
+    "NBR14724-R03": {
+        "standard": "ABNT NBR 14724:2011",
+        "clause": "Seção 5.8",
+        "title": "Ilustrações com título superior, chamada textual prévia e fonte inferior",
+        "severity": "warning",
+    },
+    "NBR6022-R01": {
+        "standard": "ABNT NBR 6022:2018",
+        "clause": "Seção 5",
+        "title": "Estrutura de artigo científico periódico (título, resumo, introdução, desenvolvimento, conclusão e referências)",
+        "severity": "error",
+    },
+    "NBR10520-R01": {
+        "standard": "ABNT NBR 10520:2023",
+        "clause": "Seção 4.2",
+        "title": "Sistema autor-data entre parênteses em caixa mista (Silva, 2023), vedada CAIXA ALTA",
+        "severity": "error",
+    },
+    "NBR10520-R02": {
+        "standard": "ABNT NBR 10520:2023",
+        "clause": "Seção 7.1",
+        "title": "Consistência cruzada estrita entre citações no texto e referências no arquivo .bib",
+        "severity": "error",
+    },
+    "NBR10520-R03": {
+        "standard": "ABNT NBR 10520:2023",
+        "clause": "Seções 5.2 / 5.3",
+        "title": "Formatação de citações diretas curtas (<=3 linhas, aspas) e longas (>3 linhas, recuo de 4 cm, fonte 10)",
+        "severity": "error",
+    },
+    "NBR6023-R01": {
+        "standard": "ABNT NBR 6023:2018",
+        "clause": "Anexo A (A.1)",
+        "title": "Abreviatura padronizada de meses (três caracteres com ponto, exceto 'maio' por extenso sem ponto)",
+        "severity": "warning",
+    },
+    "NBR6023-R02": {
+        "standard": "ABNT NBR 6023:2018",
+        "clause": "Seção 6.2",
+        "title": "Alinhamento à margem esquerda e destaque tipográfico exclusivo no título principal",
+        "severity": "error",
+    },
+    "NBR6024-R01": {
+        "standard": "ABNT NBR 6024:2012",
+        "clause": "Seção 4.1",
+        "title": "Numeração progressiva das seções sem ponto final após o último algarismo",
+        "severity": "warning",
+    },
+    "NBR6027-R01": {
+        "standard": "ABNT NBR 6027:2012",
+        "clause": "Seção 4",
+        "title": "Sumário restrito aos elementos textuais e pós-textuais (vedada inclusão de elementos pré-textuais)",
+        "severity": "error",
+    },
+    "NBR6028-R01": {
+        "standard": "ABNT NBR 6028:2021",
+        "clause": "Seção 3.3",
+        "title": "Resumo em parágrafo único contínuo na 3ª pessoa e palavras-chave separadas por ponto e vírgula",
+        "severity": "warning",
+    },
+    "IBGE1993-R01": {
+        "standard": "Normas Tabulares IBGE (1993)",
+        "clause": "Seção 3.1",
+        "title": "Distinção entre Tabela (dados quantitativos, laterais abertas) e Quadro (dados qualitativos, bordas fechadas)",
+        "severity": "error",
+    },
+}
+
+# Abreviatura oficial de meses segundo a NBR 6023:2018 (atenção ao 'maio' sem ponto!)
+ABNT_MONTHS: dict[str, str] = {
+    "1": "jan.",
+    "01": "jan.",
+    "jan": "jan.",
+    "january": "jan.",
+    "janeiro": "jan.",
+    "2": "fev.",
+    "02": "fev.",
+    "feb": "fev.",
+    "february": "fev.",
+    "fevereiro": "fev.",
+    "3": "mar.",
+    "03": "mar.",
+    "mar": "mar.",
+    "march": "mar.",
+    "março": "mar.",
+    "4": "abr.",
+    "04": "abr.",
+    "apr": "abr.",
+    "april": "abr.",
+    "abril": "abr.",
+    "5": "maio",
+    "05": "maio",
+    "may": "maio",
+    "mai": "maio",
+    "maio": "maio",
+    "6": "jun.",
+    "06": "jun.",
+    "jun": "jun.",
+    "june": "jun.",
+    "junho": "jun.",
+    "7": "jul.",
+    "07": "jul.",
+    "jul": "jul.",
+    "july": "jul.",
+    "julho": "jul.",
+    "8": "ago.",
+    "08": "ago.",
+    "aug": "ago.",
+    "august": "ago.",
+    "agosto": "ago.",
+    "9": "set.",
+    "09": "set.",
+    "sep": "set.",
+    "september": "set.",
+    "setembro": "set.",
+    "10": "out.",
+    "oct": "out.",
+    "october": "out.",
+    "outubro": "out.",
+    "11": "nov.",
+    "november": "nov.",
+    "novembro": "nov.",
+    "12": "dez.",
+    "dec": "dez.",
+    "december": "dez.",
+    "dezembro": "dez.",
+}
+
+# Regex para detectar autores em CAIXA ALTA entre parênteses (norma antiga NBR 10520:2002)
+# Na norma 2023, deve ser (Silva, 2021) e não (SILVA, 2021)
+RE_UPPERCASE_CITATION = re.compile(
+    r"\(([A-ZÁÉÍÓÚÂÊÔÃÕÇ]{2,}(?:\s+[A-ZÁÉÍÓÚÂÊÔÃÕÇ]{2,})*(?:;\s*[A-ZÁÉÍÓÚÂÊÔÃÕÇ]{2,}(?:\s+[A-ZÁÉÍÓÚÂÊÔÃÕÇ]{2,})*)*),\s*(\d{4}[^\)]*)\)"
+)
+
+# Regex para ponto final indevido no indicativo numérico de seções (NBR 6024:2012)
+# Incorreto: "1.1. Introdução" ou "# 1.1. Introdução"
+# Correto: "1.1 Introdução" ou "# 1.1 Introdução"
+RE_INVALID_SECTION_DOT = re.compile(
+    r"^[ \t]*(?:#+\s*)?(\d+(?:\.\d+)*)\.\s+([A-ZÁÉÍÓÚÂÊÔÃÕÇ].*)$", re.MULTILINE
+)
+
+# Regex para maio com ponto (incorreto pela NBR 6023)
+RE_MAI_WITH_DOT = re.compile(r"\bmai\.(?!\w)", re.IGNORECASE)
+
+# Lista de termos e pronomes em 1ª pessoa
+FIRST_PERSON_PRONOUNS: set[str] = {
+    "eu", "me", "mim", "comigo", "meu", "minha", "meus", "minhas",
+    "nós", "nos", "conosco", "nosso", "nossa", "nossos", "nossas"
+}
+
+# Verbos comuns em 1ª pessoa do singular e plural (passado, presente, futuro)
+FIRST_PERSON_VERBS: set[str] = {
+    # Singular
+    "fiz", "faço", "farei", "analisei", "analiso", "analisarei",
+    "observei", "observo", "observarei", "concluo", "concluí", "concluirei",
+    "acredito", "acreditei", "acreditarei", "percebo", "percebi", "perceberei",
+    "verifico", "verifiquei", "verificarei", "identifico", "identifiquei", "identificarei",
+    "utilizei", "utilizo", "utilizarei", "propus", "proponho", "proporei",
+    "desenvolvi", "desenvolvo", "desenvolverei", "notei", "noto", "notarei",
+    "considerei", "considero", "considerarei", "estudei", "estudo", "estudarei",
+    "pretendo", "pretendi", "pretenderei", "apresento", "apresentei",
+    # Plural
+    "fizemos", "faremos", "analisamos", "analisaremos",
+    "observamos", "observaremos", "concluímos", "concluiremos",
+    "acreditamos", "acreditaremos", "percebemos", "perceberemos",
+    "verificamos", "verificaremos", "identificamos", "identificaremos",
+    "utilizamos", "utilizaremos", "propusemos", "proporemos",
+    "desenvolvemos", "desenvolveremos", "notamos", "notaremos",
+    "consideramos", "consideraremos", "estudamos", "estudaremos",
+    "pretendemos", "pretenderemos", "apresentamos", "apresentaremos",
+}
+
+# Juízos de valor sem fundamentação e termos dogmáticos
+VALUE_JUDGMENTS: list[tuple[str, str]] = [
+    ("obviamente", "Substitua por dados empíricos ou referência; o que é 'óbvio' requer demonstração na ciência."),
+    ("claramente", "Evite advérbios opinativos. Deixe que os dados demonstrem a conclusão."),
+    ("sem dúvida", "Na ciência impera a dúvida metódica; utilize 'evidências apontam' ou cite a fonte."),
+    ("sem sombra de dúvida", "Afirmação categórica sem rigor científico."),
+    ("indubitavelmente", "Evite certezas absolutas sem citação ou prova matemática."),
+    ("com certeza", "Linguagem informal e assertiva sem respaldo."),
+    ("é evidente", "Se fosse evidente não necessitaria de fundamentação; apresente a fonte."),
+    ("notoriamente", "Apelo ao senso comum; fundamente com citação bibliográfica."),
+    ("comprovadamente", "Só utilize se acompanhar a citação comprobatória direta."),
+    ("perfeito", "Juízo de valor qualitativo excessivo."),
+    ("maravilhoso", "Termo emotivo/qualificativo inadequado ao texto científico."),
+    ("fantástico", "Tom hiperbólico desprovido de rigor técnico."),
+    ("inquestionável", "No método científico, hipóteses são sempre falseáveis."),
+    ("na minha opinião", "Trabalho científico fundamenta-se em fatos e literatura, não em opinião pessoal."),
+    ("no meu ponto de vista", "Substitua pela constatação dos dados ou fundamentação teórica."),
+    ("a meu ver", "Substitua por constatações impessoais."),
+]
+
+# Expressões coloquiais
+COLLOQUIALISMS: list[tuple[str, str]] = [
+    ("a gente", "Substitua pelo pronome impessoal 'se' ou terceira pessoa ('observa-se')."),
+    ("pra caramba", "Expressão de gíria/informal inadequada."),
+    ("bater o martelo", "Metáfora informal; use 'decidir', 'definir' ou 'concluir'."),
+    ("dar um jeito", "Expressão informal; use 'solucionar' ou 'contornar a limitação'."),
+    ("rolar", "Gíria informal; utilize 'ocorrer', 'acontecer' ou 'suceder'."),
+    ("rolou", "Gíria informal; utilize 'ocorreu' ou 'aconteceu'."),
+    ("ficar de olho", "Linguagem coloquial; utilize 'monitorar' ou 'acompanhar atentamente'."),
+    ("por aí vai", "Expressão vaga; use 'entre outros' ou cite os itens pertinentes."),
+    ("mais ou menos", "Imprecisão; forneça valores, faixas de incerteza ou margem de erro."),
+    ("coisa", "Substantivo genérico vago; especifique o objeto, variável, fenômeno ou elemento."),
+    ("coisas", "Termo genérico vago; especifique os elementos ou variáveis."),
+    ("tipo assim", "Cacoete de linguagem coloquial."),
+    ("troço", "Gíria genérica inadequada."),
+    ("pegar pesado", "Metáfora coloquial; use 'ser rigoroso'."),
+    ("tirar de letra", "Expressão coloquial inadequada."),
+]

abnt_mcp/models.py

@@ -0,0 +1,344 @@
+"""Modelos de dados Pydantic para validações e tipagem do ABNT Copilot MCP."""
+
+from __future__ import annotations
+from typing import Any, Literal
+from pydantic import BaseModel, Field
+
+
+class Author(BaseModel):
+    """Representação estruturada de autor."""
+    first_name: str = Field(default="", description="Prenome(s) do autor (ex: 'Maria Aparecida')")
+    last_name: str = Field(..., description="Sobrenome do autor (ex: 'Silva')")
+
+
+class CitationInput(BaseModel):
+    """Parâmetros de formatação de citação conforme a NBR 10520:2023."""
+    authors: list[str] = Field(
+        ...,
+        description="Lista de sobrenomes dos autores (ex: ['Silva', 'Santos'])",
+        min_length=1
+    )
+    year: str | int = Field(..., description="Ano da publicação (ex: 2023)")
+    page: str | None = Field(
+        default=None,
+        description="Página ou localizador (ex: '45', '12-15', 'local. 340')"
+    )
+    style: Literal["in_parentheses", "in_text"] = Field(
+        default="in_parentheses",
+        description="in_parentheses: (Silva, 2023, p. 10) | in_text: Silva (2023, p. 10)"
+    )
+    quote_type: Literal["direct_short", "direct_long", "indirect"] = Field(
+        default="indirect",
+        description="Tipo de citação: direta curta (<=3 linhas), direta longa (>3 linhas) ou indireta"
+    )
+    quote_text: str | None = Field(
+        default=None,
+        description="Texto citado na íntegra (necessário para citações diretas)"
+    )
+    target_format: Literal["markdown", "latex", "typst", "text"] = Field(
+        default="markdown",
+        description="Formato de saída gerado"
+    )
+
+
+class ReferenceInput(BaseModel):
+    """Parâmetros para referência bibliográfica conforme a NBR 6023:2018."""
+    entry_type: Literal[
+        "book", "book_chapter", "journal_article", "website",
+        "thesis", "legislation", "conference", "software"
+    ] = Field(..., description="Tipo de documento referenciado")
+    title: str = Field(..., description="Título principal da obra (receberá destaque)")
+    subtitle: str | None = Field(default=None, description="Subtítulo (não recebe destaque)")
+    authors: list[Author] | None = Field(default=None, description="Lista de autores")
+    edition: str | None = Field(default=None, description="Ex: '3. ed.'")
+    city: str | None = Field(default=None, description="Cidade de publicação")
+    publisher: str | None = Field(default=None, description="Editora ou instituição")
+    year: str | int = Field(..., description="Ano de publicação")
+    journal_name: str | None = Field(default=None, description="Nome da revista ou periódico")
+    volume: str | None = Field(default=None, description="Volume do periódico")
+    number: str | None = Field(default=None, description="Número/fascículo do periódico")
+    pages: str | None = Field(default=None, description="Páginas (ex: '45-60')")
+    url: str | None = Field(default=None, description="Endereço eletrônico")
+    access_date: str | None = Field(default=None, description="Data de acesso (ex: '24 out. 2026')")
+    degree: str | None = Field(default=None, description="Grau acadêmico para teses/dissertações")
+    institution: str | None = Field(default=None, description="Instituição de ensino para teses")
+    emphasis_style: Literal["bold", "italic"] = Field(
+        default="bold",
+        description="Estilo de destaque do título (negrito ou itálico)"
+    )
+
+
+class DiagnosticItem(BaseModel):
+    """Modelo unificado de diagnóstico (diferencia regra normativa estrita de heurística editorial)."""
+    rule_id: str = Field(..., description="ID canônico (ex: 'NBR10520-R01') ou código heurístico ('HEURISTIC-TONE-01')")
+    nature: Literal["normative", "heuristic", "institutional"] = Field(
+        default="normative",
+        description="Natureza do diagnóstico: normative (ABNT/IBGE), heuristic (editorial/IA) ou institutional"
+    )
+    severity: Literal["info", "warning", "error", "critical"] = "warning"
+    confidence: Literal["high", "medium", "low"] = "high"
+    message: str
+    suggestion: str = ""
+    file: str | None = None
+    line: int | None = None
+    human_review_required: bool = False
+
+
+class ToneIssue(BaseModel):
+    """Registro de inadequação de tom científico."""
+    category: Literal["first_person", "value_judgment", "colloquialism", "ungrounded_paragraph"]
+    term: str
+    context: str
+    line_number: int | None = None
+    suggestion: str
+
+
+class ToneAnalysisResult(BaseModel):
+    """Resultado da análise de tom e rigor científico."""
+    score: int = Field(..., ge=0, le=100, description="Nota de rigor científico (0 a 100)")
+    is_acceptable: bool = Field(..., description="Se o texto atende ao padrão científico")
+    total_words: int
+    issues_count: int
+    issues: list[ToneIssue]
+    diagnostics: list[DiagnosticItem] = Field(
+        default_factory=list,
+        description="Diagnósticos unificados marcados como heuristic (requerem revisão humana)"
+    )
+    summary: str
+    suggested_rewrites: list[dict[str, str]]
+
+
+class StructureCheckResult(BaseModel):
+    """Resultado da validação estrutural da NBR 14724 / NBR 6022."""
+    standard: str = "NBR 14724:2011"
+    is_valid: bool
+    compliance_score: int = Field(..., ge=0, le=100)
+    document_type: str = "TCC/Monografia/Dissertação"
+    missing_mandatory: list[str]
+    optional_elements_present: list[str]
+    elements_found: list[str]
+    section_warnings: list[str]
+    rule_violations: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="Lista de violações rastreáveis por ID canônico (ex: NBR14724-R01)"
+    )
+    diagnostics: list[DiagnosticItem] = Field(
+        default_factory=list,
+        description="Lista de diagnósticos unificados"
+    )
+    recommendations: list[str]
+
+
+class CitationValidationResult(BaseModel):
+    """Resultado da validação de citações vs referências."""
+    total_citations_in_text: int
+    total_references_in_bib: int
+    orphan_citations: list[dict[str, str | int]] = Field(
+        description="Citações presentes no texto mas ausentes no .bib"
+    )
+    unused_references: list[str] = Field(
+        description="Chaves do .bib que nunca foram citadas no texto"
+    )
+    uppercase_violations: list[dict[str, str | int]] = Field(
+        description="Citações em caixa alta no texto violando a NBR 10520:2023"
+    )
+    diagnostics: list[DiagnosticItem] = Field(
+        default_factory=list,
+        description="Lista de diagnósticos normativos de citações e referências"
+    )
+    is_consistent: bool
+
+
+class IllustrationAuditResult(BaseModel):
+    """Resultado da auditoria de figuras, tabelas e quadros (NBR 14724 item 5.8 e IBGE 1993)."""
+    is_valid: bool
+    total_figures: int = 0
+    total_tables: int = 0
+    total_quadros: int = 0
+    unreferenced_items: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Ilustrações, tabelas ou quadros declarados sem chamada prévia no texto"
+    )
+    missing_sources: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Itens sem indicação obrigatória de 'Fonte:' na parte inferior"
+    )
+    broken_image_paths: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Caminhos de arquivos de imagem referenciados que não existem no disco"
+    )
+    numbering_issues: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Numeração fora de ordem sequencial ou duplicada"
+    )
+    quadro_vs_tabela_warnings: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Alertas de confusão conceitual entre Tabela (quantitativo) e Quadro (qualitativo)"
+    )
+    diagnostics: list[DiagnosticItem] = Field(
+        default_factory=list,
+        description="Lista de diagnósticos unificados"
+    )
+
+
+class AcademicPaper(BaseModel):
+    """Metadados de um artigo científico retornado por APIs de busca."""
+    title: str
+    authors: list[str]
+    year: str | int | None = None
+    journal: str | None = None
+    doi: str | None = None
+    url: str | None = None
+    abstract: str | None = None
+    source: str
+
+
+# ==============================================================================
+# MODELOS DE SPEC-DRIVEN ACADEMIC WRITING (SDD)
+# ==============================================================================
+
+class NormativeProfile(BaseModel):
+    """Camada 1: Perfil normativo e institucional da especificação acadêmica."""
+    document_type: Literal["tcc", "dissertacao", "tese", "artigo"] = "tcc"
+    standard: Literal["ABNT_14724", "ABNT_6022"] = "ABNT_14724"
+    institution: str | None = None
+    course: str | None = None
+    department: str | None = None
+    advisor: str | None = None
+    cover_header_lines: list[str] = Field(
+        default_factory=list,
+        description="Linhas superiores do cabeçalho da capa na ordem institucional"
+    )
+    has_cover_logo: bool = Field(
+        default=False,
+        description="Se a capa institucional utiliza logotipo/brasão"
+    )
+    cover_logo_path: str | None = Field(
+        default=None,
+        description="Caminho relativo da imagem da logo da instituição no projeto"
+    )
+    preamble_text: str | None = Field(
+        default=None,
+        description="Preâmbulo institucional completo da Folha de Rosto"
+    )
+    required_pre_textual: list[str] = Field(
+        default_factory=list,
+        description="Elementos pré-textuais adicionais exigidos pela instituição"
+    )
+    conclusion_label: str = Field(
+        default="Conclusão",
+        description="Rótulo adotado para a seção conclusiva ('Conclusão' ou 'Considerações Finais')"
+    )
+    inferred_from_pdf: bool = Field(
+        default=False,
+        description="Se os padrões institucionais foram extraídos automaticamente de um PDF modelo"
+    )
+    emphasis_style: Literal["bold", "italic"] = "bold"
+    min_references: int = Field(default=15, ge=1)
+    min_scientific_tone_score: int = Field(default=80, ge=0, le=100)
+
+
+class SpecificObjective(BaseModel):
+    """Camada 2: Objetivo específico rastreável na matriz científica."""
+    id: str = Field(..., description="Identificador canônico, ex: 'OBJ-01'")
+    description: str = Field(..., description="Enunciado formal do objetivo específico")
+    keywords: list[str] = Field(
+        default_factory=list,
+        description="Termos/conceitos-chave que comprovam discussão e resolução do objetivo"
+    )
+    target_section: str | None = Field(
+        default=None,
+        description="Seção ou capítulo responsável por desenvolver este objetivo"
+    )
+
+
+class PlannedChapter(BaseModel):
+    """Camada 3: Capítulo ou seção planejada na estrutura do manuscrito."""
+    number: str = Field(..., description="Indicativo numérico (ex: '1', '2', '2.1')")
+    title: str = Field(..., description="Título planejado do capítulo/seção")
+    min_words: int = Field(default=200, ge=0)
+    min_citations: int = Field(default=1, ge=0)
+
+
+class ResearchSpec(BaseModel):
+    """Manifesto de Especificação Científica (abnt.spec.json)."""
+    spec_version: str = "1.0"
+    title: str
+    author: str | None = None
+    research_problem: str = Field(..., description="Pergunta de partida / problema de pesquisa")
+    general_objective: str = Field(..., description="Objetivo geral do estudo")
+    methodology_summary: str = Field(..., description="Abordagem, método e procedimentos")
+    specific_objectives: list[SpecificObjective] = Field(..., min_length=1)
+    profile: NormativeProfile = Field(default_factory=NormativeProfile)
+    planned_chapters: list[PlannedChapter] = Field(default_factory=list)
+
+
+class ObjectiveAuditItem(BaseModel):
+    """Resultado de auditoria individual de um objetivo específico (OBJ-XX)."""
+    id: str
+    description: str
+    status: Literal["fulfilled", "partial", "missing"]
+    covered_in_body: bool
+    answered_in_conclusion: bool
+    matched_keywords: list[str] = Field(default_factory=list)
+    missing_keywords: list[str] = Field(default_factory=list)
+    feedback: str
+
+
+class ChapterAuditItem(BaseModel):
+    """Resultado de auditoria de um capítulo planejado."""
+    number: str
+    title: str
+    found_in_document: bool
+    feedback: str
+
+
+class SpecAuditResult(BaseModel):
+    """Relatório consolidado de auditoria orientada a especificação (SDD)."""
+    spec_path: str
+    title: str
+    document_type: str
+    standard_applied: str
+    is_compliant: bool
+    submission_readiness: Literal["READY", "READY_WITH_WARNINGS", "NOT_READY"] = "NOT_READY"
+    spec_compliance_score: int = Field(..., ge=0, le=100)
+    structure_score: int = Field(..., ge=0, le=100)
+    objectives_fulfillment_rate: int = Field(..., ge=0, le=100)
+    tone_score: int = Field(..., ge=0, le=100)
+    references_count: int
+    min_references_required: int
+    institutional_compliance: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Status de conformidade com as exigências específicas da universidade/periódico"
+    )
+    illustrations_summary: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Resumo da auditoria de figuras, tabelas e quadros"
+    )
+    objectives_audit: list[ObjectiveAuditItem]
+    chapters_audit: list[ChapterAuditItem]
+    normative_issues: list[dict[str, str]]
+    diagnostics: list[DiagnosticItem] = Field(
+        default_factory=list,
+        description="Lista consolidada de diagnósticos (normativos, institucionais e heurísticos)"
+    )
+    recommendations: list[str]
+    saved_report_paths: dict[str, str] = Field(
+        default_factory=dict,
+        description="Caminhos dos relatórios persistidos em .abnt-mcp/ (JSON e Markdown)"
+    )
+
+
+class ProjectScaffoldResult(BaseModel):
+    """Resultado do scaffolding estrutural de um projeto acadêmico SDD."""
+    success: bool
+    project_path: str
+    format: Literal["typst", "latex", "markdown"]
+    main_file: str
+    bib_file: str
+    spec_json_path: str
+    spec_md_path: str
+    cover_logo_path: str | None = None
+    created_files: list[str] = Field(default_factory=list)
+    inferred_institutional_profile: dict[str, Any] | None = None
+    message: str

abnt_mcp/parsers/__init__.py

@@ -0,0 +1,32 @@
+"""Módulos de parsing de documentos, citações, BibTeX e PDFs."""
+
+from abnt_mcp.parsers.citations import (
+    extract_citations_from_latex,
+    extract_citations_from_markdown,
+    extract_citations_from_typst,
+    extract_citations_from_project,
+    detect_uppercase_citations,
+)
+from abnt_mcp.parsers.bibtex import (
+    clean_latex_accents,
+    extract_bib_keys_and_dois,
+    sanitize_bibtex_string,
+    append_entry_if_absent,
+    normalize_abnt_month,
+)
+from abnt_mcp.parsers.pdf_reader import extract_pdf_section, audit_pdf_pagination
+
+__all__ = [
+    "extract_citations_from_latex",
+    "extract_citations_from_markdown",
+    "extract_citations_from_typst",
+    "extract_citations_from_project",
+    "detect_uppercase_citations",
+    "clean_latex_accents",
+    "extract_bib_keys_and_dois",
+    "sanitize_bibtex_string",
+    "append_entry_if_absent",
+    "normalize_abnt_month",
+    "extract_pdf_section",
+    "audit_pdf_pagination",
+]