IAdetector

Detecta si un texto fue generado por IA, 100% local: sin llamar a ninguna API externa de pago (OpenAI, GPTZero, Originality.ai, etc.). Combina señales estadísticas/estilométricas puras con dos modelos ONNX pequeños que corren localmente (un clasificador RoBERTa y un modelo de perplexity DistilGPT-2), calibradas mediante regresión logística sobre datos reales (HC3).

Consumible de dos formas sobre el mismo motor:

• Servidor MCP (IAdetector.Mcp) — tools para que un agente (Claude Code, VS Code Copilot, etc.) analice texto.
• CLI (IAdetector.Cli, comando iadetector) — para uso directo en terminal o scripts.

Qué puedes preguntarle

Pregunta	Herramienta que responde
"¿Este texto lo escribió una IA?"	detect_text
"Analiza este archivo"	detect_file
"Revisa los 500 documentos de esta carpeta"	batch_detect_directory
"¿Por qué dio ese veredicto?"	explain_detection

Todo ocurre en tu máquina. No hay API externa, no hay clave, y el texto analizado nunca sale del equipo. Es la diferencia esencial frente a GPTZero, Originality.ai o cualquier detector en la nube: puedes analizar un manuscrito inédito o un documento confidencial sin entregárselo a nadie.

[!IMPORTANT] Un resultado es evidencia, nunca prueba. La detección de texto generado por IA es probabilística y tiene falsos positivos reales, que además afectan de forma desproporcionada a quien escribe en un idioma que no es el suyo y a la prosa técnica muy formulaica.

No uses esta herramienta como única base para acusar a un estudiante o a un trabajador. Sirve para priorizar qué revisar con criterio humano, no para decidir por ti.

Arquitectura

Clean Architecture pragmática, 4 proyectos productivos:

src/
  IAdetector.Core/            Dominio + casos de uso. Cero dependencias externas.
  IAdetector.Infrastructure/  Señales (estadísticas + ONNX), ensemble calibrado, descarga de modelos.
  IAdetector.Mcp/             Servidor MCP (stdio), vía ModelContextProtocol C# SDK.
  IAdetector.Cli/             CLI (comando `iadetector`), vía System.CommandLine.
tools/
  IAdetector.Calibration/     Herramienta de desarrollo: extrae features para recalibrar el ensemble.
tests/                        xUnit: Core, Infrastructure, e integración end-to-end (corpus HC3 held-out).
scripts/calibration/          Dataset de calibración + script Python (scikit-learn) que ajusta los pesos.

Siete señales combinadas en CalibratedEnsembleScorer: burstiness, type-token ratio, entropía léxica, ratio de compresión, repetición de n-gramas, clasificador ONNX (RoBERTa) y perplexity (DistilGPT-2). Ver EnsembleWeights.json para los coeficientes calibrados.

Requisitos

• .NET 10 SDK
• Para publicar binarios Native AOT en Windows: Visual Studio Build Tools con el workload de C++ (vswhere.exe debe estar accesible; normalmente en C:\Program Files (x86)\Microsoft Visual Studio\Installer\).

Instalación

CLI

Opción A — dotnet tool desde NuGet (un solo comando, requiere el runtime .NET):

dotnet tool install --global IAdetector.Cli
iadetector detect ejemplo.txt

(Para instalar desde el código fuente en vez de NuGet: dotnet pack src/IAdetector.Cli -c Release -o ./nupkg y luego dotnet tool install --global --add-source ./nupkg IAdetector.Cli.)

Opción B — binario nativo standalone (sin necesidad de instalar .NET):

dotnet publish src/IAdetector.Cli -c Release -r win-x64 -p:PublishAot=true -o ./publish/cli
./publish/cli/IAdetector.Cli.exe detect ejemplo.txt

Cambiar win-x64 por linux-x64 según la plataforma.

Servidor MCP

Opción A — paquete NuGet con dnx (sin clonar el repo ni instalar nada antes):

Configurar el host MCP (ej. .vscode/mcp.json) y dnx descarga y ejecuta el servidor desde NuGet:

{
  "servers": {
    "IAdetector": {
      "type": "stdio",
      "command": "dnx",
      "args": ["IAdetector.Mcp", "--version", "1.0.1", "--yes"]
    }
  }
}

Opción B — binario nativo standalone apuntado directamente:

dotnet publish src/IAdetector.Mcp -c Release -r win-x64 -p:PublishAot=true -o ./publish/mcp

{
  "servers": {
    "IAdetector": {
      "type": "stdio",
      "command": "C:/ruta/a/publish/mcp/IAdetector.Mcp.exe"
    }
  }
}

Modelos ONNX

Los modelos (clasificador RoBERTa ~126MB, DistilGPT-2 ~237MB) no se descargan automáticamente durante una detección — hay que descargarlos explícitamente una vez:

iadetector models download --model roberta-openai-detector
iadetector models download --model distilgpt2-perplexity
iadetector models list

Se cachean en %LOCALAPPDATA%\IAdetector\models (Windows) con verificación de integridad SHA-256. Sin ellos, esas dos señales quedan neutrales (peso reducido) y el resto del ensemble sigue funcionando.

Uso de la CLI

iadetector detect archivo.txt [--json] [--verbose] [--no-color]
iadetector detect --text "texto a analizar" [--verbose]
cat archivo.txt | iadetector detect               # también lee de stdin si no hay archivo ni --text
iadetector batch <directorio> [--pattern *.txt] [--recursive] [--max-files 1000] [--output resultados.csv]
iadetector models download --model <id> [--force]
iadetector models list
iadetector models verify [--model <id>]

Tools MCP

• detect_text(text, verbose) — texto inline (máx. 20 000 caracteres).
• detect_file(path, verbose) — archivo local (máx. 5MB; fragmenta automáticamente textos largos, muestreando si son muy grandes).
• batch_detect_directory(path, pattern, recursive, maxFiles) — varios archivos a la vez.
• explain_detection(text) — explicación prescriptiva: por señal, si midió, cuánto empuja el resultado (contribución al logit), su rango típico en texto humano de referencia y qué cambiar si está fuera de rango, con acciones priorizadas.
• compare_versions(originalText, rewrittenText) — compara una reescritura con su original (sin estado): cambio de probabilidad y por señal, con salvaguarda de significado (si la reescritura pierde el vocabulario de contenido del original, el resultado es no_concluyente aunque la probabilidad baje). Ver docs/AGENT_LOOP.md.

Para agentes que consumen estas tools: el contrato completo (campos, semántica, protocolo del bucle, fiabilidad por idioma y límites) está en docs/AGENT_GUIDE.md.

Skills para agentes (Claude Code)

skills/ (layout plano estándar skills/<nombre>/SKILL.md, el mismo que usan proyectos como Vercel o Supabase para distribuir sus propias skills) incluye dos skills instalables con npx skills:

• iadetector-setup — instalar, publicar y configurar el CLI/MCP, descargar los modelos ONNX, registrar el servidor en .mcp.json.
• iadetector-usage — interpretar los resultados (veredicto, probabilidad, confianza) y comunicarlos sin sobre-afirmar certeza.

Nota: viven en skills/ (rastreado por git) y no en .claude/skills/ (ignorado — es estado local por sesión/máquina). Cada usuario materializa las que quiera usar en su propio .claude/skills/ local corriendo el comando de instalación de abajo; no se commitea esa copia.

Para instalarlas en otro proyecto una vez este repo esté en GitHub:

npx skills add <usuario>/IAdetector-mcp --skill iadetector-setup --skill iadetector-usage

O directamente desde una copia local del repo (sin necesidad de GitHub):

npx skills add /ruta/a/IAdetector-mcp --skill '*'

Desarrollo

dotnet build
dotnet test tests/IAdetector.Core.Tests
dotnet test tests/IAdetector.Infrastructure.Tests   # requiere modelos descargados para las señales ONNX
dotnet test tests/IAdetector.Integration.Tests       # requiere modelos + scripts/calibration/data/open_qa.jsonl

Recalibrar el ensemble

dotnet run --project tools/IAdetector.Calibration -- <dataset.jsonl formato HC3> scripts/calibration/data/features.csv
python scripts/calibration/fit_logistic_regression.py scripts/calibration/data/features.csv src/IAdetector.Infrastructure/Ensemble/EnsembleWeights.json

Limitaciones conocidas

• Los umbrales de las señales estadísticas puras (Fase 1) son heurísticos iniciales; solo el ensemble completo está formalmente calibrado.
• El clasificador RoBERTa fue entrenado para detectar salidas de GPT-2 (2019); generaliza de forma imperfecta a estilos de LLMs más recientes — de ahí el ensemble con señales complementarias.
• La señal de perplexity es una versión simplificada (un solo modelo) de la idea de Fast-DetectGPT/Binoculars, no la razón completa entre dos modelos.
• Calibrado sobre un subconjunto de HC3 (inglés); no validado específicamente en español u otros idiomas.

CLI for agents

Authorship screening that never leaves the machine — no text is sent anywhere.

This CLI follows ARSENAL-SPEC.md, the contract every research tool in this workspace shares: an agent that can drive one can drive all of them.

Discover it without reading this file

iadetector describe --json          # every command, argument, row field and example
iadetector describe <command> --json

The manifest is derived from the parser itself, so it cannot drift out of date.

Output

-f, --format accepts table, json, jsonl, csv, md; -o FILE writes to a file; -q silences notes. Data goes to stdout, notes and progress to stderr — piping to jq always yields parseable JSON.

--format json returns the standard envelope:

{
  "ok": true,
  "command": "detect",
  "source": "iadetector",
  "fetched_at": "2026-08-21T14:03:11Z",
  "cached": false,
  "count": 10,
  "meta": {},
  "data": {},
  "rows": []
}

count always equals len(rows). An empty result is exit 0, not an error. Failures return an error envelope carrying error.code, error.message and an actionable error.hint, printed to stdout in machine formats so a pipeline can inspect it.

Exit codes

Code	Meaning
0	Éxito, incluido un resultado vacío.
1	El análisis falló o devolvió algo inesperado (modelo corrupto, error interno).
2	Error de uso: flag desconocido, formato inválido, argumentos incompatibles.
3	No se encontró el archivo, directorio o modelo indicado.
4	No aplica: la detección es 100% local, no hay API key ni credenciales.
5	No aplica: no hay servicio externo con cuota.
6	Fallo de red o timeout — solo alcanzable en 'models download'.

Cache

Results are cached on disk and survive between invocations, so a repeated query is instant. --refresh refetches and rewrites; --no-cache skips it entirely; the envelope reports cached.

iadetector cache stats -f json
iadetector cache clear

Recipes

iadetector detect informe.txt -f json
iadetector detect --text "un párrafo cualquiera" --verbose -f json
cat ensayo.md | iadetector detect -f json
iadetector batch corpus/ -f csv -o corpus.csv
iadetector batch corpus/ --verbose -f jsonl --max 500

Or through the workspace-wide entry point: arsenal run iadetector <command> ..., and arsenal doctor iadetector --live to check this CLI still honours the contract.

Troubleshooting

El modelo no está descargado Los modelos ONNX no vienen incluidos. Descárgalos una sola vez: iadetector models download. Ocupan unos cientos de MB y quedan en la caché de la aplicación; míralas con iadetector models list.

El primer análisis tarda mucho más que el resto Es la carga inicial de los modelos ONNX en memoria. Los siguientes son rápidos, y un texto ya analizado sale de la caché de resultados al instante.

Reanalizar un corpus vuelve a tardar lo mismo Comprueba que no estés pasando --no-cache o --refresh. Con iadetector cache stats ves cuántos resultados hay guardados. La clave incluye la versión de los modelos: si actualizas los modelos, la caché anterior queda obsoleta a propósito.

Un texto muy corto da confianza baja Con pocas palabras las señales estadísticas no tienen material suficiente. Por debajo de un párrafo, el resultado no es informativo — y así lo reporta.

Documentation

Document	What's in it
CHANGELOG.md	What changed in each release
CONTRIBUTING.md	Dev setup, the CLI contract, how to run the tests
SECURITY.md	What this server sends and where; how to report a vulnerability
server.json	Registry metadata for the official MCP registry
../ARSENAL-SPEC.md	The CLI contract shared by every research server here

Licence

MIT — see LICENSE.