Claimify

Extrai alegações factuais de texto usando a metodologia Claimify. Requer uma chave de API da OpenAI.

GitHub
18
Experimente este MCPPatrocinado

Documentação

Claimify: Extração de Alegações Baseada em Pesquisa via MCP

Uma implementação da metodologia "Claimify" para extração de alegações factuais, entregue como um servidor local do Model Context Protocol (MCP). Esta ferramenta implementa a abordagem de extração de alegações em múltiplas etapas detalhada no artigo acadêmico "Towards Effective Extraction and Evaluation of Factual Claims" de Metropolitansky & Larson (2025).

Leia o artigo aqui

Os prompts do artigo foram modificados para uso com Structured Outputs. ESTA NÃO É UMA IMPLEMENTAÇÃO OFICIAL.

Visão Geral

O Claimify extrai alegações factuais verificáveis e descontextualizadas de textos usando um pipeline sofisticado de quatro etapas:

  1. Divisão de Frases: Divide o texto em frases individuais com contexto circundante
  2. Seleção: Filtra frases que contêm proposições verificáveis, excluindo opiniões e especulações
  3. Desambiguação: Resolve ambiguidades ou descarta frases que não podem ser esclarecidas
  4. Decomposição: Divide frases em alegações factuais atômicas e autossuficientes

A ferramenta usa exclusivamente o recurso de structured outputs da OpenAI para maior confiabilidade e expõe sua funcionalidade através do Model Context Protocol, tornando-a disponível para clientes compatíveis com MCP, como Cursor e Claude Desktop.

Recursos

  • Metodologia baseada em pesquisa: Implementa a abordagem Claimify revisada por pares
  • Structured outputs: Usa structured outputs da OpenAI para respostas confiáveis e type-safe
  • Integração MCP: Integra-se perfeitamente com ambientes de desenvolvimento
  • Análise robusta: Lida com vários formatos de texto, incluindo listas e parágrafos
  • Consciente do contexto: Usa frases circundantes para resolver ambiguidades
  • Suporte a múltiplos idiomas: Preserva o idioma original ao extrair alegações
  • Armazenamento de recursos: Armazena automaticamente alegações extraídas como recursos MCP para fácil recuperação
  • Registro abrangente: Registro detalhado de todas as chamadas LLM, respostas e etapas do pipeline
  • Pronto para produção: Inclui tratamento de erros, monitoramento e gerenciamento de configuração

Requisitos

  • API OpenAI: Requer uma chave de API da OpenAI (se o seu host MCP não suportar sampling (Github Copilot no vsCode não suporta))
  • Modelo compatível: Deve usar um modelo que suporte structured outputs:
    • gpt-4o (recomendado)
    • gpt-4o-mini (mais rápido e barato)
  • Python 3.10+: Para type hints adequados e suporte a Pydantic

Início Rápido

1. Instalação

# Clone the repository
git clone <repository-url>
cd ClaimsMCP

# Create and activate a virtual environment
python -m venv claimify-env
source claimify-env/bin/activate  # On Windows: claimify-env\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download required NLTK data (done automatically on first run)
python -c "import nltk; nltk.download('punkt_tab')"

2. Configuração

Crie um arquivo .env na raiz do projeto:

# Copy the example file
cp env.example .env

Edite .env e adicione sua chave de API:

# API Keys
OPENAI_API_KEY="your-openai-api-key-here"

# LLM Configuration
LLM_MODEL="gpt-4o-2024-08-06"  # Model that supports structured outputs

# Logging Configuration
LOG_LLM_CALLS="true"   # Set to "false" to disable logging
LOG_OUTPUT="stderr"    # "stderr" or "file" - where to send logs
LOG_FILE="claimify_llm.log"  # Used only if LOG_OUTPUT="file"

Configuração do Cliente MCP

Para Cursor

  1. Abra o Cursor e navegue até Settings > MCP
  2. Clique em "Add a New Global MCP Server"
  3. Adicione a seguinte configuração ao seu arquivo de configurações MCP (geralmente ~/.cursor/mcp.json):
{
  "mcpServers": {
    "claimify-local": {
      "command": "/path/to/your/claimify-env/bin/python",
      "args": [
        "/path/to/your/project/claimify_server.py"
      ]
    }
  }
}
  1. Substitua os caminhos pelos caminhos absolutos do seu executável Python e do script do servidor

O "Claimify Extraction Server" deve aparecer agora como uma ferramenta conectada no seu chat habilitado para MCP.

Exemplos de Uso

Uma vez configurado, você pode usar a ferramenta no seu cliente MCP:

Usando a Ferramenta Extract Claims

Usando os Prompts

O servidor expõe dois prompts para ajudar a verificar e documentar alegações extraídas:

1. Verificar Alegação Individual (verify_claim)

Fornece um prompt pré-construído que instrui o LLM a verificar uma alegação factual individual contra fontes externas.

Argumentos:

  • claim_text (obrigatório): A alegação factual descontextualizada a ser verificada.

Comportamento:

  1. O LLM é instruído a pesquisar fontes autoritativas (publicações acadêmicas, veículos de notícias respeitáveis, organizações oficiais).
  2. Retorna um de três status:
    • VERIFIED: A alegação é claramente apoiada por fontes confiáveis (fornece pelo menos 3 referências com URLs + justificativa)
    • UNCERTAIN: A alegação pode estar correta, mas carece de precisão, tem ambiguidade ou evidências limitadas/conflitantes
    • DISPUTED: A alegação é comprovadamente falsa ou contradita por fontes confiáveis
  3. As fontes não devem ser fabricadas; preferência por referências primárias.

Exemplo de recuperação (conceitual – a chamada real depende da API do cliente):

get_prompt(name="verify_claim", arguments={"claim_text": "Python was first publicly released in 1991."})

Exemplo de formato de resposta esperado do LLM:

**Claim:** Python was first publicly released in 1991.

**Status:** IN_PROGRESS

[After research...]

**Claim:** Python was first publicly released in 1991.

**Status:** VERIFIED

**Evidence:**
- Source 1: [Python.org Release History](https://www.python.org/doc/versions/) - Official Python release history page confirms the initial public release year
- Source 2: [Computer History Museum](https://www.computerhistory.org/collections/catalog/102726710) - Archive referencing Python's early development
- Source 3: [Wikipedia - Python](https://en.wikipedia.org/wiki/Python_(programming_language)) - Encyclopedia entry citing original release year

Se incerto:

**Claim:** Stockholm has 800,000 inhabitants.

**Status:** UNCERTAIN

**Evidence:**
- Source 1: [Statistics Sweden](https://www.scb.se/en/) - Reports varying population figures depending on whether measuring city proper, municipality, or metropolitan area

**Analysis:**
The claim lacks specificity about which definition of "Stockholm" is being referenced (city proper ~975k, municipality ~975k, or urban area ~1.6M as of 2023). The figure of 800,000 may have been accurate for certain definitions at specific time periods, but without temporal and geographic context, full verification is not possible.

Se disputado:

**Claim:** The Earth is flat.

**Status:** DISPUTED

**Analysis:**
This claim contradicts overwhelming scientific evidence. The Earth's spherical shape has been confirmed by satellite imagery, space missions, and centuries of astronomical observations. Reliable sources universally reject this claim.

2. Criar Relatório de Alegações (create_claims_report)

Gera um arquivo CLAIMS.md inicial com todas as alegações marcadas como TODO. As alegações podem então ser verificadas incrementalmente, atualizando seu status através do fluxo de trabalho: TODO → IN_PROGRESS → VERIFIED/UNCERTAIN/DISPUTED.

Fluxo de trabalho:

  1. Criação inicial: Todas as alegações começam com status TODO
  2. Durante a verificação: Atualize alegações individuais para IN_PROGRESS
  3. Após a verificação: Atualize para VERIFIED, UNCERTAIN ou DISPUTED com evidências

Argumentos:

  • Nenhum (anexe o recurso de extração ao contexto no VS Code)

Comportamento:

  1. Analisa todas as alegações do recurso de extração anexado ao contexto
  2. Cria CLAIMS.md com todas as alegações marcadas como TODO
  3. Fornece uma estrutura de modelo pronta para verificação incremental

Exemplo de uso: Ao visualizar um recurso de extração no VS Code, anexe-o ao contexto do prompt. O prompt gerará um arquivo CLAIMS.md inicial pronto para verificação.

Estrutura inicial do CLAIMS.md:

# Claims Report

**Extraction ID:** extraction_1_1730678400
**Generated:** 2025-11-03
**Total Claims:** 5
**TODO:** 5
**In Progress:** 0
**Verified:** 0
**Uncertain:** 0
**Disputed:** 0

---

## Claims

### Claim 1
**Text:** Apple Inc. was founded in 1976.

**Status:** TODO

---

### Claim 2
**Text:** Steve Jobs co-founded Apple Inc.

**Status:** TODO

---
...

Após atualizações de verificação:

### Claim 1
**Text:** Apple Inc. was founded in 1976.

**Status:** VERIFIED

**Evidence:**
- Source 1: [Wikipedia - Apple Inc.](https://en.wikipedia.org/wiki/Apple_Inc.) - States company was founded in 1976
- Source 2: [Apple Official](https://www.apple.com/about/) - Corporate history confirms 1976 founding
- Source 3: [Britannica](https://www.britannica.com/topic/Apple-Inc) - Encyclopedia entry validates founding year

---

### Claim 2
**Text:** Stockholm has 800,000 inhabitants.

**Status:** UNCERTAIN

**Evidence:**
- Source 1: [Statistics Sweden](https://www.scb.se/en/) - Reports varying figures depending on definition

**Analysis:**
The claim lacks specificity about which geographic definition and time period. Population varies significantly between city proper (~975k), municipality (~975k), and metropolitan area (~1.6M) as of 2023. The 800k figure may have been accurate historically for certain definitions.

---

### Claim 3
**Text:** The company invented smartphones.

**Status:** DISPUTED

**Analysis:**
While Apple popularized smartphones with the iPhone in 2007, they did not invent smartphones. Earlier devices like the IBM Simon (1994) and BlackBerry devices (early 2000s) preceded the iPhone. The claim conflates innovation/popularization with invention.

---
...

Nota: O servidor apenas fornece os prompts; a pesquisa externa depende das capacidades do cliente/modelo.

Exemplo 1: Texto Factual Simples

Input: "The American flag contains 50 stars and 13 stripes."
Output: [
  "The American flag contains 50 stars [representing the 50 states] and 13 stripes [representing the original 13 colonies].",
  "The American flag was designed in 1777",
  "The American flag has been modified 27 times"
]

Exemplo 2: Mistura de Fato e Opinião

Input: "Apple Inc. was founded in 1976 by Steve Jobs, Steve Wozniak, and Ronald Wayne. The company is incredibly innovative and has the best products in the world."
Output: [
  "Apple Inc. was founded in 1976 by Steve Jobs, Steve Wozniak, and Ronald Wayne."
]

(Nota: O conteúdo subjetivo sobre ser "incrivelmente inovador" e ter "os melhores produtos" é filtrado)

Exemplo 3: Suporte a Múltiplos Idiomas

Input: "String-systemet är en prisbelönt ikon som kombinerar elegant och minimalistisk design med ett brett utbud av färger och storlekar. Nisse Strinning skapade första hyllan redan 1949."
Output: [
  "String-systemet [ett hyllsystem] är en prisbelönt ikon [inom design]",
  "String-systemet kombinerar elegant och minimalistisk design med ett brett utbud av färger och storlekar",
  "Nisse Strinning skapade den första String-hyllan [String-systemet] 1949"
]

(Nota: Conteúdo preservado em sueco original, com esclarecimentos contextuais adicionados entre colchetes)

Acessando Alegações Extraídas como Recursos

Cada extração gera dois tipos de recursos:

  1. Recurso de Extração Agregado (claim://extraction_<n>_<timestamp>)
    • Contém metadados (timestamp, pré-visualização, pergunta) e a lista completa de alegações
    • Retorna formato JSON
  2. Recursos de Alegação Individual (claim://<slug>)
    • Cada alegação é acessível através de um slug único (identificador seguro para URL derivado do texto da alegação)
    • Retorna texto simples (a própria alegação)

Exemplo de JSON de Extração Agregada

{
  "id": "extraction_1_1730678400",
  "timestamp": "2025-11-03T14:30:00.123456",
  "question": "What is the history of Apple?",
  "text_preview": "Apple Inc. was founded in 1976 by Steve Jobs...",
  "claims": [
    "Apple Inc. was founded in 1976 by Steve Jobs, Steve Wozniak, and Ronald Wayne."
  ],
  "claim_count": 1
}

URI: claim://apple-inc-was-founded-in-1976-by-steve-jobs

Exemplos de Recursos de Alegação Individual

Padrão de URI: claim://<slug>

Exemplos:

  • claim://apple-inc-was-founded-in-1976-by-steve-jobs-steve-wozniak-and-ronald
  • claim://stockholm-is-the-capital-of-sweden
  • claim://python-was-first-publicly-released-in-1991

Conteúdo: Texto simples da alegação (sem wrapper JSON)

Benefícios dos recursos por alegação:

  • Acesso direto: Recupere qualquer alegação pelo seu slug
  • Formato simples: Texto simples, sem necessidade de análise
  • Identificadores únicos: Cada alegação tem um URI estável e legível
  • Citação fácil: Vincule diretamente a alegações individuais

Estrutura do Projeto

ClaimsMCP/
├── README.md                    # This file
├── requirements.txt             # Python dependencies
├── env.example                  # Environment configuration template
├── claimify_server.py          # Main MCP server script
├── llm_client.py               # LLM client with structured outputs support
├── pipeline.py                 # Core claim extraction pipeline
├── structured_models.py        # Pydantic models for structured outputs
├── structured_prompts.py       # Optimized prompts for structured outputs
├── setup.py                    # Package setup configuration
├── test_claimify.py            # Test suite for the claim extraction pipeline
└── LICENSE                     # Apache 2.0 license

Arquitetura

O sistema segue uma arquitetura modular com structured outputs:

  • Servidor MCP: Expõe a extração de alegações como uma ferramenta via Model Context Protocol
  • ClaimifyPipeline: Orquestra o processo de extração em múltiplas etapas usando structured outputs
  • LLMClient: Gerencia a comunicação com a API da OpenAI usando structured outputs e modelos Pydantic
  • Modelos Estruturados: Modelos Pydantic que definem o formato de resposta esperado para cada etapa
  • Funções de Etapa: Funções individuais para Seleção, Desambiguação e Decomposição
  • Gerenciamento de Prompts: Prompts simplificados otimizados para structured outputs

Benefícios dos Structured Outputs

A implementação usa o recurso de structured outputs da OpenAI, que fornece:

  • Type Safety: As respostas são automaticamente validadas contra modelos Pydantic
  • Confiabilidade: Sem mais falhas de análise de regex ou JSON malformado
  • Recusas Explícitas: Recusas baseadas em segurança são programaticamente detectáveis
  • Consistência: Adesão garantida ao esquema de resposta esperado
  • Desempenho: Redução da necessidade de lógica de repetição e tratamento de erros

Opções de Configuração

Variável de AmbienteDescriçãoPadrãoOpções
LLM_MODELModelo específico a usargpt-4o-2024-08-06Modelos que suportam structured outputs
OPENAI_API_KEYChave de API da OpenAINenhumSua chave de API
LOG_LLM_CALLSAtivar registro detalhado de todas as interações LLMtruetrue, false
LOG_OUTPUTOnde enviar a saída do registrostderrstderr, file
LOG_FILENome do arquivo de registro (usado quando LOG_OUTPUT=file)claimify_llm.logQualquer nome de arquivo

Solução de Problemas

Problemas Comuns

  1. Erro "Model does not support structured outputs"

    • Certifique-se de usar um modelo compatível: gpt-4o-2024-08-06, gpt-4o-mini ou gpt-4o
    • Atualize seu arquivo .env: LLM_MODEL=gpt-4o-2024-08-06

  2. Erro "API key not set"

    • Certifique-se de que seu arquivo .env existe e contém a chave de API correta da OpenAI
    • Verifique se a chave começa com sk-

  3. "NLTK punkt tokenizer not found"

    • Execute: python -c "import nltk; nltk.download('punkt_tab')" ou python -c "import nltk; nltk.download('punkt')"

  4. Cliente MCP não consegue conectar

    • Verifique se os caminhos na sua configuração MCP são absolutos e corretos
    • Certifique-se de que seu ambiente virtual Python está ativado
    • Verifique se o script do servidor é executável: chmod +x claimify_server.py

  5. Nenhuma alegação extraída

    • Verifique os registros para informações detalhadas sobre cada etapa do pipeline
    • Certifique-se de que o texto de entrada contém declarações factuais verificáveis
    • Tente primeiro com frases factuais mais simples e diretas

Desenvolvimento

Para estender ou modificar o sistema:

  1. Adicionando novos campos de resposta: Atualize os modelos Pydantic em structured_models.py
  2. Modificando prompts: Edite os prompts em structured_prompts.py
  3. Adicionando novas etapas: Crie novas funções em pipeline.py seguindo o padrão existente
  4. Testes: Use o registro integrado para depurar o comportamento do pipeline

A abordagem de structured outputs torna o sistema muito mais confiável e mais fácil de depurar em comparação com métodos tradicionais de análise de texto.

Licença

Este projeto é licenciado sob a Apache License 2.0 - veja o arquivo LICENSE para detalhes.

Referências

Metropolitansky & Larson (2025). "Towards Effective Extraction and Evaluation of Factual Claims"

Suporte

Para problemas relacionados a:

  • Configuração e instalação: Consulte este README e a seção de solução de problemas
  • Integração MCP: Consulte a documentação do Model Context Protocol
  • Metodologia de pesquisa: Consulte o artigo original do Claimify