Humanidades Digitais |

tei-mcp v0.3: codificar em TEI sem reescrever a fonte

Tue, 05 May 2026 00:00:00 +0000

Quando , o objetivo era impedir os assistentes de IA de alucinar marcação TEI. A ancoragem no esquema resolveu parte do problema: com acesso direto, por ferramentas, à especificação P5, o modelo já não tem de adivinhar o que um elemento significa nem que atributos aceita. O resultado valida.

Mas a alucinação tem duas faces na codificação TEI, e o esquema só apanha uma delas. Validar contra a especificação diz-nos que a marcação está bem formada. Nada diz sobre o texto que essa marcação envolve. E é aí – no próprio texto – que vivem as alucinações mais nocivas. A composição por intervalos bloqueados, a grande novidade da v0.3, foi concebida especificamente para as impedir.

Lista de Conteúdos

A alucinação que o esquema não apanha

Peça-se a um modelo que codifique uma carta francesa do século XVI e receber-se-á muitas vezes um documento TEI de aspeto impecável. O cabeçalho está preenchido, as etiquetas <persName> estão bem colocadas, o <dateline> está bem formado. Passe-se pelo validate_document e ele passa.

Compare-se depois o corpo com a fonte.

mesme passou a même. Uma vírgula mudou de sítio. luy foi silenciosamente modernizado em lui. Uma oração de leitura difícil no manuscrito foi «corrigida» para algo mais limpo. Nenhuma destas alterações foi pedida. Nenhuma é assinalada. O documento é válido segundo o esquema e está discretamente errado.

Para um fluxo de trabalho de arquivo – em que o texto codificado se torna o registo permanente de que dependem leitores, índices de pesquisa e citações – é este o modo de falha que mais importa. Uma etiqueta malformada é um incómodo. Uma grafia modernizada de que ninguém dá conta durante cinco anos é uma corrupção.

A composição por intervalos bloqueados

A nova versão (v0.3) traz um mecanismo de prevenção de alucinações apontado diretamente a este modo de falha. O objetivo de design é tornar as alucinações no corpo do texto impossíveis por construção, e não apenas improváveis.

A ideia é simples: o modelo nunca escreve texto de corpo.

Em vez disso, o fluxo de trabalho é o seguinte:

O modelo chama get_source("letter_001") e recebe o texto simples da fonte como cadeia imutável.
Para cada etiqueta que queira aplicar, chama tag_span("letter_001", start, end, element_path, attrs) – registando um elemento TEI sobre um intervalo de caracteres da fonte.
Quando termina, chama compose("letter_001"). O servidor intercala as etiquetas registadas com o texto simples original, gera o TEI final e verifica depois, byte a byte, que o conteúdo textual plano do documento gerado é igual à fonte.

Se os bytes coincidem, o documento é devolvido. Se não coincidem – se as etiquetas do modelo implicarem de algum modo um corpo que difere da fonte num único caráter que seja –, compose() lança uma exceção em vez de devolver um documento corrompido.

Não há caminho, neste fluxo de trabalho, em que o modelo produza um documento TEI cujo corpo difira da fonte. O invariante é mecânico, não comportamental. Não é preciso confiar que o modelo não alucina; basta confiar numa comparação == entre duas cadeias de bytes.

O que isto é, e o que não é

A composição por intervalos bloqueados é complementar da ancoragem no esquema; não a substitui. As ferramentas de ancoragem no esquema (validate_document, lookup_element, valid_children e as restantes das dezasseis originais) ajudam o modelo a produzir TEI válida. A composição por intervalos bloqueados garante que o corpo do texto dentro dessa TEI é fiel à fonte. Um fluxo de codificação que se possa pôr em produção tem de satisfazer os dois eixos, e agora ambos ficam cobertos por um único servidor.

Também não é uma varinha mágica para tudo. compose() ainda não verifica se as etiquetas registadas são admissíveis segundo uma personalização ODD carregada – fica para uma próxima versão. As etiquetas registadas vivem na memória do processo e não sobrevivem a um reinício. E os ficheiros-fonte têm de ser legíveis a partir de onde quer que o servidor corra. Tudo isto tem solução; nada disto abala o invariante central.

Porque é que isto importa para lá da TEI

O padrão generaliza-se. Sempre que se pede a um modelo que anote, transforme ou envolva um pedaço de texto – e sempre que a integridade do texto subjacente importa mais do que a capacidade do modelo para o «melhorar» –, aplica-se a mesma forma de solução. Não peça ao modelo que reescreva o texto. Peça-lhe que produza instruções sobre o texto, e deixe que um compositor determinista as aplique sob um invariante de igualdade.

Para as edições digitais em particular, isto muda o que se pode pedir a um modelo com responsabilidade. A codificação torna-se de repente uma tarefa delegável sem ter de comparar à mão cada resultado com a fonte. A máquina faz o caminho enfadonho; o editor revê a marcação, não a ortografia.

Obter a atualização

Se já tem o tei-mcp instalado:

uvx tei-mcp@latest

Ou de raiz:

pip install tei-mcp

Para usar a composição por intervalos bloqueados, aponte o servidor para uma diretoria de ficheiros-fonte em texto simples:

export TEI_MCP_SPAN_SOURCE_ROOT=/path/to/sources
uvx tei-mcp

O radical do nome de cada ficheiro passa a ser o seu identificador de documento (letter_001.txt → letter_001).

Código-fonte, documentação completa e notas de design do invariante:

Uma edição digital de outro tipo

Tue, 24 Mar 2026 00:00:00 +0000

A maior parte das fontes primárias nunca chega a ser publicada. O modelo em que confiamos para remediar isso, a edição digital financiada por bolsas, é demasiado caro, demasiado centralizado e demasiado frágil para funcionar em escala. Acabo de publicar em que explico por que estou a construir de outra maneira a edição crítica das cartas de Cavriana: fontes primárias digitalizadas que crescem organicamente, com infraestrutura mínima, manutenção automatizada, abertas à colaboração e tão baratas que nem sequer precisam de bolsas. É um argumento a favor de umas humanidades digitais que funcionam com ou sem apoio institucional.

tei-mcp: a TEI P5 ao alcance dos agentes de IA

Sun, 15 Mar 2026 00:00:00 +0000

Quem já tenha usado um assistente de programação por IA para escrever XML TEI terá reparado que ele se engana. Aparecem elementos onde não deviam. Inventam-se atributos. Ignoram-se as regras de aninhamento. O modelo tem uma ideia vaga do aspeto da TEI, mas nenhum conhecimento fiável da especificação.

O tei-mcp resolve o problema dando aos agentes de IA acesso direto, por meio de ferramentas, às Guidelines da TEI P5.

Lista de Conteúdos

O que é o MCP?

O (MCP) é uma norma aberta que permite às aplicações de IA ligar-se a fontes de dados e ferramentas externas. Pense-se nele como uma porta USB para a IA: um protocolo único que permite a qualquer cliente compatível – Claude, Cursor, Windsurf e outros – ligar-se a serviços especializados.

Um servidor MCP expõe ferramentas que a IA pode invocar durante uma conversa. Em vez de se fiar em dados de treino memorizados, o modelo pode consultar uma fonte viva e autorizada.

O que faz o tei-mcp

O tei-mcp analisa a especificação ODD da TEI P5 e expõe 16 ferramentas que cobrem as perguntas mais frequentes de um editor ou codificador:

O que é este elemento? Consultar qualquer elemento, classe, macro ou módulo pelo nome, sem distinção de maiúsculas e com sugestões em caso de gralha.
Que atributos aceita? Resolver os atributos ao longo de toda a hierarquia de classes – primeiro os locais, depois os herdados, por ordem.
O que pode conter? Expandir os modelos de conteúdo em árvores estruturadas, ou obter uma lista simples dos filhos válidos.
Este elemento pode ir aqui? Verificar o aninhamento pai-filho, ou seguir a acessibilidade através de toda a hierarquia de elementos.
O meu documento é válido? Validar um ficheiro XML TEI contra a especificação: modelos de conteúdo, valores de atributos, listas fechadas de valores, integridade das referências e avisos de depreciação.
E o esquema do meu projeto? Carregar um ficheiro de personalização ODD para restringir tudo o que precede ao subconjunto de TEI próprio do seu projeto.

Porque é que isto importa

Codificar em TEI exige consultar as Guidelines a toda a hora. Os codificadores experientes interiorizam os padrões mais comuns, mas até eles têm de verificar a especificação quando se trata de elementos menos familiares ou de modelos de conteúdo complexos. Para os assistentes de IA, que não têm esse conhecimento interiorizado, o problema é pior: alucinam marcação de aspeto plausível, mas incorreta.

Com o tei-mcp, a IA não tem de adivinhar. Pode procurar a resposta na especificação antes de escrever um único parêntese angular. O resultado é marcação conforme à TEI P5 – ou à personalização ODD do seu projeto.

Primeiros passos

Instale a partir do PyPI:

pip install tei-mcp

Depois, acrescente-o à configuração do seu cliente MCP:

{
 "mcpServers": {
 "tei": {
 "command": "uvx",
 "args": ["tei-mcp"]
 }
 }
}

O servidor descarrega a especificação TEI na primeira execução e funciona com qualquer cliente compatível com MCP.

Código-fonte e documentação completa:

Ensinar o binário com o emulador de telégrafo ITA2

Thu, 13 Feb 2025 00:00:00 +0000

Tornar tangível o abstrato

Este emulador ITA2 é um auxiliar pedagógico de uso prático. Ao dar forma visível e interativa a conceitos abstratos de codificação, introduz os estudantes numa noção central da informática e das telecomunicações: a representação binária – ou seja, como um texto se converte em sequências de uns e zeros. Costumamos ensiná-la em abstrato; ora, ver os furos aparecerem na fita ajuda os estudantes a perceber como um sistema físico pode representar informação digital.

ITA2 (Baudot-Murray) Telegraph Type Emulator

Type a word in the input below to see its representation on the ITA2 tape.

Type word:

Contexto histórico: do telégrafo à informática

O código ITA2 (International Telegraph Alphabet No. 2), também conhecido como código Baudot-Murray, foi desenvolvido nos anos 1920 como aperfeiçoamento do código telegráfico original de Émile Baudot, que datava da década de 1870. Estes primeiros sistemas de telecomunicação influenciaram diretamente a informática que se lhes seguiu:

O esquema de codificação em 5 bits foi um dos primeiros exemplos de codificação de caracteres
As limitações do conjunto de caracteres (apenas 32 combinações possíveis com 5 bits) deram origem ao engenhoso mecanismo de comutação LETTERS/FIGURES (letras/algarismos)
O sistema continuou a ser usado nos teleimpressores até bem entrado o século XX

Aprender as máquinas de estados a brincar

O mecanismo de comutação LETTERS/FIGURES introduz as máquinas de estados com toda a naturalidade. Experimentando, os estudantes descobrem que o mesmo padrão pode representar caracteres diferentes consoante o modo ativo. Esta experiência direta da codificação dependente de um estado prepara-os para conceitos informáticos mais complexos. Por exemplo, o padrão de bits 00011 representa:

A letra «A» em modo LETTERS
O algarismo «1» em modo FIGURES Esta dupla interpretação em função do estado está na base da maneira como os computadores lidam com os dados.

Atividades para a sala de aula

Eis algumas maneiras de integrar o emulador ITA2 no ensino:

Desafio de descodificação: pedir aos estudantes que decifrem mensagens codificadas em padrões ITA2
Codificação eficiente: discutir por que razão o mecanismo de comutação era importante para poupar largura de banda
Evolução da codificação: comparar o código de 5 bits do ITA2 com o ASCII (7 bits) e o Unicode
Computação física: ligar este sistema histórico aos microcontroladores modernos, como o Arduino

Vantagens em matéria de acessibilidade

Para além do interesse histórico, esta abordagem serve estudantes com estilos de aprendizagem diversos:

Os visuais veem os padrões
Os cinestésicos interagem diretamente com o processo de codificação
Os de pendor conceptual podem explorar a vertente matemática da teoria da informação

Pormenores de implementação

O emulador está escrito em JavaScript e integra-se facilmente em qualquer plataforma de ensino em linha. O código é modular e adaptável a diferentes contextos pedagógicos. O código-fonte está disponível, e o emulador pode ser experimentado, no