Skip to main content

Detector IA

PyPI Python CI MIT

Español · English

Desarrollado por Alberto Ortiz Sánchez · albertoortiz.is-a.dev · PyPI · GitHub

pip install detector-ia && detector-ia --version

Español

Herramienta de línea de comandos para detectar indicios de texto generado por IA y posibles copias entre entregas de alumnos, y generar un reporte CSV ordenado por riesgo.

Analiza cuadernos de Jupyter (.ipynb), PDF, Word (.docx), Markdown (.md) y texto plano (.txt) en una sola pasada.

Es una ayuda para la revisión, no una prueba. Un porcentaje alto es un motivo para hablar con el alumno o revisar el trabajo a mano; nunca un veredicto automático.

Documentación

Guías en español e inglés dentro de cada archivo:

Cómo funciona

Cada entrega se parte en bloques de ~1500 caracteres y cada bloque de más de 300 caracteres se puntúa combinando tres señales:

Señal Peso Qué mide
Huella estructural en español 50 % Guiones largos (—), listas * **Concepto:**, encabezados ### 1., conectores enciclopédicos (por tanto, cabe destacar, en última instancia) y ausencia de erratas/coloquialismos
Uniformidad estadística 30 % Baja variación en la longitud de las frases, típica de texto generado
Red neuronal 20 % fakespot-ai/roberta-base-ai-text-detection-v1

Opcionalmente (--perplejidad, experimental) se añade una cuarta señal tipo Binoculars: la perplejidad del texto bajo dos modelos de lenguaje emparentados. No necesita entrenar con ejemplos de IA, pero sus límites no están calibrados para español: mídela con evaluacion/evaluar.py --perplejidad antes de fiarte.

Cada resultado lleva una confianza (Alta, Media o Baja) y avisos cuando hay poca base: texto corto, bloques que se contradicen (posible texto mixto), puntuación que viene solo de la uniformidad o muchas citas. La confianza no es la probabilidad de acertar; indica cuánto se puede fiar uno del número.

Plagio entre entregas

Se compara el orden de las palabras, no solo el vocabulario: cada entrega se parte en n-gramas y se seleccionan huellas con winnowing (la idea de MOSS). La similitud es el porcentaje de huellas de la entrega más pequeña que aparecen en la otra, así que detecta también la copia parcial y no se deja engañar por trabajos que solo hablan del mismo tema. En los cuadernos se normaliza el código (nombres de variables, números y cadenas), de modo que renombrar variables no esconde la copia. El informe muestra los pasajes coincidentes de las dos entregas. El coseno clásico (bolsa de palabras) se sigue calculando como segunda opinión, en la columna Similitud_Coseno (%).

Con --base se indica el enunciado o la plantilla que reciben todos los alumnos, para que lo compartido no cuente como copia. Con --traduccion (extra semantica) se buscan frases con el mismo significado entre entregas en español e inglés; solo genera un aviso, nunca cambia el veredicto. Un mismo trabajo entregado en dos formatos (por ejemplo PDF y TXT) no se cuenta como copia.

Qué no hace bien

Con las señales estructurales, el texto generado sin editar se detecta mucho mejor que el retocado a mano o el escrito «como un estudiante»; y los textos muy formales, traducidos o de quien escribe en una lengua que no es la suya pueden dar falsos positivos. El detalle y las cifras del corpus de pruebas están en Método y calibración.

Instalación

Requiere Python 3.13 o superior.

pip install detector-ia            # desde PyPI: señales estructurales, sin modelo neuronal
pip install "detector-ia[modelo]"  # con el modelo neuronal (torch + transformers)
pip install "detector-ia[semantica]"  # solo para --traduccion (sentence-transformers)

El extra modelo instala torch y transformers; sin él la herramienta sigue funcionando con --sin-modelo, usando solo las señales estructurales. La primera ejecución descarga el modelo (~500 MB) en cache_modelo/, que está fuera del control de versiones. Las siguientes arrancan sin conexión.

Con el paquete instalado el comando es detector-ia; comprueba que responde con detector-ia --version.

Desde el código fuente

Si prefieres trabajar sobre el repositorio, clona y sincroniza. Para esto hace falta uv:

git clone https://github.com/alberto2005-coder/detector-ia.git
cd detector-ia
uv sync --extra modelo

Dentro del repositorio los comandos del resto de la guía se ejecutan con uv run detector-ia.

Uso

Copia las entregas a analizar en revision_ia/ y ejecuta:

uv run detector-ia

Eso lee revision_ia/, imprime el progreso y guarda reporte_profesional_ia.csv. Hay textos inventados de prueba en ejemplos/:

uv run detector-ia -c ejemplos -s reporte_ejemplos.csv

Con opciones:

uv run detector-ia --carpeta entregas --salida reportes/marzo.csv
uv run detector-ia -c ejemplos/misma_entrega.md --sin-modelo   # un solo archivo
uv run detector-ia --folder entregas --output reporte.csv --lang en
uv run detector-ia --modelo fakespot-ai/roberta-base-ai-text-detection-v1
uv run detector-ia -c entregas --html informe.html --markdown informe.md   # informes para leer
uv run detector-ia -c entregas --base enunciado.ipynb                      # sin contar la plantilla

También funciona sin uv, con el entorno activado:

python -m detector_ia --carpeta revision_ia

Opciones

Opción Por defecto Descripción
-c, --carpeta, --ruta, --folder, --path revision_ia Carpeta con las entregas o ruta de un archivo concreto
-s, --salida, --output reporte_profesional_ia.csv Ruta del reporte generado
-m, --modelo, --model RoBERTa de detección de IA Modelo de Hugging Face a usar
--sin-modelo, --no-model desactivado Analiza solo con las señales estructurales, sin descargar el modelo
--html RUTA — Guarda además un informe HTML autocontenido (sin conexión, con marcas por frase y pasajes coincidentes)
--markdown RUTA, --md — Guarda además un informe en Markdown
--base RUTA — Enunciado o plantilla (archivo o carpeta): lo que coincida con ella no cuenta como copia
--perplejidad, --perplexity desactivado Añade la señal de perplejidad tipo Binoculars (experimental; requiere el extra modelo)
--traduccion, --translation desactivado Busca plagio traducido entre español e inglés (requiere el extra semantica)
--json desactivado Escribe el resultado en JSON por la salida estándar (con el detalle de cada bloque) y el progreso por la de errores
--fail-on ninguno Devuelve código de salida 1 si el reporte alcanza error, alto/high o sospechoso/suspicious (también vale none)
--lang, --idioma es Idioma de los mensajes de consola (es/en); el CSV no cambia
-V, --version — Muestra la versión instalada y sale

Todos los flags, sus valores y la ayuda de -h se pueden escribir en español o en inglés: --carpeta entregas y --folder entregas hacen lo mismo, igual que --salida/--output. El CSV y los veredictos se quedan en español para que las columnas no cambien según el idioma; solo se traducen los mensajes de consola.

Reporte

El CSV se guarda en UTF-8 con BOM y separador ; para que abra directamente en Excel en español. Columnas:

  • Archivo / Formato: nombre y extensión de la entrega.
  • IA_Media (%): media de la puntuación híbrida de los bloques evaluados.
  • IA_Pico_Max (%): bloque con la puntuación más alta, el que más se parece a texto de IA.
  • Similitud_Companero (%) y Coincide_Con: similitud por n-gramas con la entrega más parecida y su nombre si llega al 40 % (o si el coseno supera el 75 %). Desde la 1.1.0 esta columna ya no es el coseno; el coseno está en Similitud_Coseno (%).
  • Veredicto: ALTO RIESGO IA, REVISAR COPIA ENTRE ALUMNOS, Sospechoso (Revisar), Normal o Poco texto.
  • Fragmento_Sospechoso: el bloque con mayor puntuación, para leerlo en contexto.
  • Error: vacía salvo que el archivo no se pudiera leer o puntuar; en ese caso el veredicto es Error y aquí aparece el motivo, sin detener el resto del lote.
  • Columnas añadidas en la 1.1.0, al final para no mover las anteriores: Similitud_Coseno (%), Confianza (Alta/Media/Baja), Avisos, Fragmento_Coincidente (el pasaje más largo que comparte con Coincide_Con) y Similitud_Traducida (%) (solo con --traduccion).

Umbrales actuales (en src/detector_ia/main.py): pico ≥ 58 % o media ≥ 45 % es alto riesgo; pico ≥ 45 % o media ≥ 35 % es sospechoso; similitud por n-gramas ≥ 60 % o coseno > 88 % es posible copia.

Informe HTML

--html informe.html genera una sola página que se abre sin conexión (no carga nada de internet): resumen por veredicto, tabla que se ordena y se filtra, puntuación de cada bloque, los rasgos que suben o bajan la puntuación marcados dentro del texto, los pasajes copiados lado a lado y los pares de entregas más parecidos. El texto de los alumnos se escapa, así que no puede ejecutar nada. Como contiene trabajos reales, trátalo igual que el CSV.

Estructura

detector-ia/
├── src/detector_ia/
│   ├── main.py          # CLI, umbrales y generación del reporte
│   ├── extractores.py   # Lectura de .ipynb, .pdf, .docx, .txt y .md
│   ├── motores.py       # Modelo neuronal, huella estructural y puntuación por bloques
│   ├── perplejidad.py   # Señal tipo Binoculars (opcional, experimental)
│   ├── similitud.py     # N-gramas con winnowing, fragmentos copiados y plantilla base
│   ├── semantica.py     # Plagio traducido por significado (opcional)
│   ├── confianza.py     # Nivel de confianza y avisos
│   └── informes.py      # Informes HTML y Markdown
├── tests/               # Pruebas con un detector falso, sin descargar el modelo
├── docs/                # Índice, método, uso responsable y formatos
├── ejemplos/            # Textos inventados para probar
├── evaluacion/          # Corpus etiquetado y script de métricas
├── scripts/             # Notas de release a partir del CHANGELOG
├── .github/             # CI, releases, Dependabot y plantillas
├── revision_ia/         # Entregas de entrada (ignoradas por git)
├── README.md            # Guía completa, en español e inglés
├── CONTRIBUTING.md      # Cómo contribuir
├── SECURITY.md          # Política de seguridad
├── CODE_OF_CONDUCT.md   # Código de conducta
├── CHANGELOG.md         # Historial de cambios por versión
├── LICENSE              # Licencia MIT
├── pyproject.toml       # Metadatos, dependencias y entry point
├── uv.lock              # Versiones exactas de las dependencias
├── .gitattributes       # Finales de línea normalizados
└── .gitignore           # Excluye .venv, cache_modelo y entregas

Privacidad

Las entregas de los alumnos y los reportes generados están excluidos de git (.gitignore), porque contienen trabajos reales y nombres de archivo. No los subas al repositorio ni compartas los CSV fuera del ámbito docente.

Autor

Desarrollado por Alberto Ortiz Sánchez.

Licencia

Distribuido bajo la licencia MIT. Consulta LICENSE. © 2026 Alberto Ortiz Sánchez.


English

A command-line tool to spot AI-generated text and possible copying between students' submissions, and to produce a CSV report sorted by risk.

It analyses Jupyter notebooks (.ipynb), PDF, Word (.docx), Markdown (.md) and plain text (.txt) in a single pass.

This is a review aid, not evidence. A high score is a reason to talk to the student or read the work by hand; never an automatic verdict.

Documentation

Guides in Spanish and English within each file:

How it works

Each submission is split into blocks of ~1500 characters, and every block longer than 300 characters is scored by combining three signals:

Signal Weight What it measures
Spanish structural fingerprint 50 % Em dashes (—), * **Term:** lists, ### 1. headings, encyclopedic connectors (por tanto, cabe destacar, en última instancia) and absence of typos or colloquialisms
Statistical uniformity 30 % Low variation in sentence length, typical of generated text
Neural network 20 % fakespot-ai/roberta-base-ai-text-detection-v1

Optionally (--perplejidad, experimental) a fourth signal in the style of Binoculars is added: the perplexity of the text under two related language models. It needs no training on AI examples, but its limits are not calibrated for Spanish: measure it with evaluacion/evaluar.py --perplejidad before trusting it.

Every result carries a confidence (Alta, Media or Baja) and notices when the basis is thin: short text, blocks that disagree (possibly mixed text), a score that comes only from uniformity, or many quotations. Confidence is not the probability of being right; it tells you how far the number can be trusted.

Plagiarism between submissions

The order of the words is compared, not just the vocabulary: every submission is split into n-grams and fingerprints are chosen with winnowing (the idea behind MOSS). Similarity is the share of fingerprints of the smaller submission found in the other, so it also catches partial copying and is not fooled by pieces of work that merely cover the same topic. In notebooks the code is normalised (variable names, numbers and strings), so renaming variables does not hide the copy. The report shows the shared passages from both submissions. The classic cosine (bag of words) is still computed as a second opinion, in the Similitud_Coseno (%) column.

--base takes the assignment brief or template every student receives, so what is shared does not count as copying. --traduccion (the semantica extra) looks for sentences with the same meaning across Spanish and English submissions; it only raises a notice and never changes the verdict. The same assignment submitted in two formats (say PDF and TXT) is not counted as copying.

What it does not do well

With the structural signals, unedited generated text is detected far better than text edited by hand or written "like a student"; and very formal or translated text, or text by people not writing in their first language, can produce false positives. The details and the numbers from the test corpus are in Method and calibration.

Install

Requires Python 3.13 or newer.

pip install detector-ia            # from PyPI: structural signals, no neural model
pip install "detector-ia[modelo]"  # with the neural model (torch + transformers)
pip install "detector-ia[semantica]"  # only for --traduccion (sentence-transformers)

The modelo extra installs torch and transformers; without it the tool still works with --sin-modelo, using only the structural signals. The first run downloads the model (~500 MB) into cache_modelo/, which is not tracked by git. Later runs start offline.

Once installed, the command is detector-ia; check it with detector-ia --version.

From source

If you prefer working on the repository, clone and sync. This needs uv:

git clone https://github.com/alberto2005-coder/detector-ia.git
cd detector-ia
uv sync --extra modelo

Inside the repository, the commands in the rest of this guide run as uv run detector-ia.

Usage

Copy the submissions into revision_ia/ and run:

uv run detector-ia

That reads revision_ia/, prints progress and writes reporte_profesional_ia.csv. There are invented test texts in ejemplos/:

uv run detector-ia -c ejemplos -s reporte_ejemplos.csv

With options:

uv run detector-ia --carpeta entregas --salida reportes/marzo.csv
uv run detector-ia -c ejemplos/misma_entrega.md --sin-modelo   # a single file
uv run detector-ia --folder entregas --output reporte.csv --lang en
uv run detector-ia --modelo fakespot-ai/roberta-base-ai-text-detection-v1
uv run detector-ia -c entregas --html report.html --markdown report.md   # reports to read
uv run detector-ia -c entregas --base brief.ipynb                        # ignore the template

It also works without uv, with the environment active:

python -m detector_ia --carpeta revision_ia

Options

Option Default Description
-c, --carpeta, --ruta, --folder, --path revision_ia Folder with the submissions, or the path of a single file
-s, --salida, --output reporte_profesional_ia.csv Path of the generated report
-m, --modelo, --model AI-detection RoBERTa Hugging Face model to use
--sin-modelo, --no-model off Structural signals only, without downloading the model
--html PATH — Also save a self-contained HTML report (works offline, with per-sentence marks and shared passages)
--markdown PATH, --md — Also save a Markdown report
--base PATH — Assignment brief or template (file or folder): what matches it does not count as copying
--perplejidad, --perplexity off Add the Binoculars-style perplexity signal (experimental; needs the modelo extra)
--traduccion, --translation off Look for translated plagiarism between Spanish and English (needs the semantica extra)
--json off Write the result as JSON on stdout (with per-block detail) and progress on stderr
--fail-on ninguno Exit with code 1 when the report reaches error, alto/high or sospechoso/suspicious (none works too)
--lang, --idioma es Language of the console messages (es/en); the CSV does not change
-V, --version — Print the installed version and exit

Every flag, its values and the -h help can be written in Spanish or in English: --carpeta entregas and --folder entregas are the same thing, as are --salida/--output. The CSV and the verdicts stay in Spanish so the columns never change with the language; only the console messages are translated.

Report

The CSV is written in UTF-8 with BOM and a ; separator so it opens directly in Spanish-locale Excel. Columns:

  • Archivo / Formato: file name and extension of the submission.
  • IA_Media (%): mean hybrid score of the scored blocks.
  • IA_Pico_Max (%): highest-scoring block, the most AI-like passage.
  • Similitud_Companero (%) and Coincide_Con: n-gram similarity with the most similar submission, and its name when it reaches 40 % (or the cosine is above 75 %). Since 1.1.0 this column is no longer the cosine; the cosine is in Similitud_Coseno (%).
  • Veredicto: ALTO RIESGO IA, REVISAR COPIA ENTRE ALUMNOS, Sospechoso (Revisar), Normal or Poco texto.
  • Fragmento_Sospechoso: the highest-scoring block, to read it in context.
  • Error: empty unless the file could not be read or scored; the verdict is then Error and the reason appears here, without stopping the rest of the batch.
  • Columns added in 1.1.0, at the end so the earlier ones do not move: Similitud_Coseno (%), Confianza (Alta/Media/Baja), Avisos, Fragmento_Coincidente (the longest passage shared with Coincide_Con) and Similitud_Traducida (%) (only with --traduccion).

Current thresholds (in src/detector_ia/main.py): peak ≥ 58 % or mean ≥ 45 % is high risk; peak ≥ 45 % or mean ≥ 35 % is suspicious; n-gram similarity ≥ 60 % or cosine > 88 % is possible copying.

HTML report

--html report.html writes a single page that opens offline (it loads nothing from the internet): a summary by verdict, a sortable and filterable table, the score of every block, the traits that raise or lower the score marked inside the text, copied passages side by side and the most similar pairs of submissions. Student text is escaped, so it cannot run anything. Since it contains real work, treat it like the CSV.

Layout

detector-ia/
├── src/detector_ia/
│   ├── main.py          # CLI, thresholds and report generation
│   ├── extractores.py   # Readers for .ipynb, .pdf, .docx, .txt and .md
│   ├── motores.py       # Neural model, structural fingerprint and per-block scoring
│   ├── perplejidad.py   # Binoculars-style signal (optional, experimental)
│   ├── similitud.py     # N-grams with winnowing, copied passages and base template
│   ├── semantica.py     # Translated plagiarism by meaning (optional)
│   ├── confianza.py     # Confidence level and notices
│   └── informes.py      # HTML and Markdown reports
├── tests/               # Tests with a fake detector, no model download
├── docs/                # Index, method, responsible use and formats
├── ejemplos/            # Invented texts for trying the tool
├── evaluacion/          # Labelled corpus and metrics script
├── scripts/             # Release notes from the CHANGELOG
├── .github/             # CI, releases, Dependabot and templates
├── revision_ia/         # Input submissions (git-ignored)
├── README.md            # Full guide, in Spanish and English
├── CONTRIBUTING.md      # How to contribute
├── SECURITY.md          # Security policy
├── CODE_OF_CONDUCT.md   # Code of conduct
├── CHANGELOG.md         # Change history per version
├── LICENSE              # MIT license
├── pyproject.toml       # Metadata, dependencies and entry point
├── uv.lock              # Exact dependency versions
├── .gitattributes       # Normalized line endings
└── .gitignore           # Excludes .venv, cache_modelo and submissions

Privacy

Student submissions and generated reports are excluded from git (.gitignore), because they contain real work and file names. Do not push them to the repository or share the CSVs outside the classroom.

Author

Developed by Alberto Ortiz Sánchez.

License

Distributed under the MIT license. See LICENSE. © 2026 Alberto Ortiz Sánchez.

Metadata

Release files for detector-ia 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for detector-ia 1.1.0
File Size Uploaded Provenance Actions
detector_ia-1.1.0.tar.gz 44.3 kB With provenance Details for detector_ia-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for detector-ia 1.1.0
File Interpreter ABI Platform Actions
detector_ia-1.1.0-py3-none-any.whl Python 3 none any Details for detector_ia-1.1.0-py3-none-any.whl

Total release size: 85.3 kB

Release files / detector_ia-1.1.0.tar.gz

Download URL detector_ia-1.1.0.tar.gz
Size 44.3 kB
Tags Source
SHA-256 checksum
How to use checksums
98c986c3b0cc68d71dc4888325d084b53142ab2cf9e2e2f7c6f454e3438118ed
BLAKE2b-256 checksum
How to use checksums
305fb0afa98c2640d8866a08345ded0d4a8fc3826ad062074be371a569e7efa8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / detector_ia-1.1.0-py3-none-any.whl

Download URL detector_ia-1.1.0-py3-none-any.whl
Size 41.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04633dd3f3d0c7ec85d502461f3938621e3968a79dd0d6c69eb906d32295c949
BLAKE2b-256 checksum
How to use checksums
f063ffc908364ef628fa06aa2868c7a27dba002f216d97cf6a6133f36f1c53d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for detector-ia 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for detector_ia-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page