detector-ia 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alberto Ortiz Sánchez
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,310 @@
1
+ Metadata-Version: 2.4
2
+ Name: detector-ia
3
+ Version: 1.0.0
4
+ Summary: Detector de texto generado por IA y de copia entre entregas · AI-text and plagiarism detection for student submissions
5
+ Keywords: ia,ai-detection,plagio,plagiarism,educacion,education,roberta,docencia,teaching,csv
6
+ Author: Alberto Ortiz Sánchez
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Education
12
+ Classifier: Natural Language :: Spanish
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Topic :: Education
17
+ Requires-Dist: pandas>=3.1.1
18
+ Requires-Dist: pypdf>=7.1.0
19
+ Requires-Dist: python-docx>=1.2.0
20
+ Requires-Dist: torch>=2.15.0 ; extra == 'modelo'
21
+ Requires-Dist: transformers>=5.23.0 ; extra == 'modelo'
22
+ Requires-Python: >=3.13
23
+ Project-URL: Homepage, https://github.com/alberto2005-coder/detector-ia
24
+ Project-URL: Repository, https://github.com/alberto2005-coder/detector-ia
25
+ Project-URL: Issues, https://github.com/alberto2005-coder/detector-ia/issues
26
+ Project-URL: Changelog, https://github.com/alberto2005-coder/detector-ia/blob/main/CHANGELOG.md
27
+ Provides-Extra: modelo
28
+ Description-Content-Type: text/markdown
29
+
30
+ # Detector IA
31
+
32
+ [Español](#español) · [English](#english)
33
+
34
+ ---
35
+
36
+ ## Español
37
+
38
+ 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.
39
+
40
+ Analiza cuadernos de Jupyter (`.ipynb`), PDF, Word (`.docx`), Markdown (`.md`) y texto plano (`.txt`) en una sola pasada.
41
+
42
+ > 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.
43
+
44
+ ### Documentación
45
+
46
+ Guías en español e inglés dentro de cada archivo:
47
+
48
+ - [Uso y formatos](docs/USAGE.md): qué se extrae de cada formato y solución de problemas.
49
+ - [Changelog](CHANGELOG.md): historial de cambios por versión.
50
+ - [Seguridad](SECURITY.md): cómo reportar un problema y qué datos no compartir.
51
+ - [Método y calibración](docs/METODO.md): de dónde salen los pesos y los umbrales, y cómo recalibrar.
52
+ - [Uso responsable](docs/USO_RESPONSABLE.md): qué hacer con un caso marcado antes de hablar con el alumno.
53
+ - [Contribuir](CONTRIBUTING.md): entorno, estructura del código y convención de commits.
54
+ - [Índice de documentación](docs/README.md).
55
+
56
+ ### Cómo funciona
57
+
58
+ 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:
59
+
60
+ | Señal | Peso | Qué mide |
61
+ | --- | --- | --- |
62
+ | 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 |
63
+ | Uniformidad estadística | 30 % | Baja variación en la longitud de las frases, típica de texto generado |
64
+ | Red neuronal | 20 % | [fakespot-ai/roberta-base-ai-text-detection-v1](https://huggingface.co/fakespot-ai/roberta-base-ai-text-detection-v1) |
65
+
66
+ Además se calcula la **similitud de coseno** (bolsa de palabras) entre todas las entregas: en los cuadernos se compara el código (o el texto, si el cuaderno no tiene código) y en el resto el texto redactado. Un mismo trabajo entregado en dos formatos (por ejemplo PDF y TXT) no se cuenta como copia.
67
+
68
+ ### Instalación
69
+
70
+ Requiere Python 3.13 o superior y, si no tienes `uv`, puedes instalarlo desde [astral.sh/uv](https://astral.sh/uv).
71
+
72
+ ```bash
73
+ git clone https://github.com/alberto2005-coder/detector-ia.git
74
+ cd detector-ia
75
+ uv sync --extra modelo
76
+ ```
77
+
78
+ 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.
79
+
80
+ ### Uso
81
+
82
+ Copia las entregas a analizar en `revision_ia/` y ejecuta:
83
+
84
+ ```bash
85
+ uv run detector-ia
86
+ ```
87
+
88
+ Eso lee `revision_ia/`, imprime el progreso y guarda `reporte_profesional_ia.csv`. Hay textos inventados de prueba en `ejemplos/`:
89
+
90
+ ```bash
91
+ uv run detector-ia -c ejemplos -s reporte_ejemplos.csv
92
+ ```
93
+
94
+ Con opciones:
95
+
96
+ ```bash
97
+ uv run detector-ia --carpeta entregas --salida reportes/marzo.csv
98
+ uv run detector-ia -c ejemplos/misma_entrega.md --sin-modelo # un solo archivo
99
+ uv run detector-ia --folder entregas --output reporte.csv --lang en
100
+ uv run detector-ia --modelo fakespot-ai/roberta-base-ai-text-detection-v1
101
+ ```
102
+
103
+ También funciona sin `uv`, con el entorno activado:
104
+
105
+ ```bash
106
+ python -m detector_ia --carpeta revision_ia
107
+ ```
108
+
109
+ #### Opciones
110
+
111
+ | Opción | Por defecto | Descripción |
112
+ | --- | --- | --- |
113
+ | `-c`, `--carpeta`, `--ruta`, `--folder`, `--path` | `revision_ia` | Carpeta con las entregas o ruta de un archivo concreto |
114
+ | `-s`, `--salida`, `--output` | `reporte_profesional_ia.csv` | Ruta del reporte generado |
115
+ | `-m`, `--modelo`, `--model` | RoBERTa de detección de IA | Modelo de Hugging Face a usar |
116
+ | `--sin-modelo`, `--no-model` | desactivado | Analiza solo con las señales estructurales, sin descargar el modelo |
117
+ | `--json` | desactivado | Escribe el resultado en JSON por la salida estándar y el progreso por la de errores |
118
+ | `--fail-on` | `ninguno` | Devuelve código de salida 1 si el reporte alcanza `error`, `alto`/`high` o `sospechoso`/`suspicious` (también vale `none`) |
119
+ | `--lang`, `--idioma` | `es` | Idioma de los mensajes de consola (`es`/`en`); el CSV no cambia |
120
+ | `-V`, `--version` | — | Muestra la versión instalada y sale |
121
+
122
+ 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.
123
+
124
+ ### Reporte
125
+
126
+ El CSV se guarda en UTF-8 con BOM y separador `;` para que abra directamente en Excel en español. Columnas:
127
+
128
+ - **Archivo / Formato**: nombre y extensión de la entrega.
129
+ - **IA_Media (%)**: media de la puntuación híbrida de los bloques evaluados.
130
+ - **IA_Pico_Max (%)**: bloque con la puntuación más alta, el que más se parece a texto de IA.
131
+ - **Similitud_Companero (%)** y **Coincide_Con**: entrega más parecida y su nombre si supera el 75 %.
132
+ - **Veredicto**: `ALTO RIESGO IA`, `REVISAR COPIA ENTRE ALUMNOS`, `Sospechoso (Revisar)`, `Normal` o `Poco texto`.
133
+ - **Fragmento_Sospechoso**: el bloque con mayor puntuación, para leerlo en contexto.
134
+ - **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.
135
+
136
+ Umbrales actuales (en `src/detector_ia/main.py`): pico ≥ 58 % o media ≥ 45 % es alto riesgo; pico ≥ 45 % o media ≥ 35 % es sospechoso; similitud > 88 % es posible copia.
137
+
138
+ ### Estructura
139
+
140
+ ```
141
+ detector-ia/
142
+ ├── src/detector_ia/
143
+ │ ├── main.py # CLI, umbrales y generación del reporte
144
+ │ ├── extractores.py # Lectura de .ipynb, .pdf, .docx, .txt y .md
145
+ │ └── motores.py # Modelo neuronal, huella estructural y similitud
146
+ ├── tests/ # Pruebas con un detector falso, sin descargar el modelo
147
+ ├── docs/ # Índice, método, uso responsable y formatos
148
+ ├── ejemplos/ # Textos inventados para probar
149
+ ├── evaluacion/ # Corpus etiquetado y script de métricas
150
+ ├── scripts/ # Notas de release a partir del CHANGELOG
151
+ ├── .github/ # CI, releases, Dependabot y plantillas
152
+ ├── revision_ia/ # Entregas de entrada (ignoradas por git)
153
+ ├── README.md # Guía completa, en español e inglés
154
+ ├── CONTRIBUTING.md # Cómo contribuir
155
+ ├── SECURITY.md # Política de seguridad
156
+ ├── CODE_OF_CONDUCT.md # Código de conducta
157
+ ├── CHANGELOG.md # Historial de cambios por versión
158
+ ├── LICENSE # Licencia MIT
159
+ ├── pyproject.toml # Metadatos, dependencias y entry point
160
+ ├── uv.lock # Versiones exactas de las dependencias
161
+ ├── .gitattributes # Finales de línea normalizados
162
+ └── .gitignore # Excluye .venv, cache_modelo y entregas
163
+ ```
164
+
165
+ ### Privacidad
166
+
167
+ 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.
168
+
169
+ ### Licencia
170
+
171
+ Distribuido bajo la licencia MIT. Consulta [LICENSE](LICENSE) para el texto completo.
172
+
173
+ ---
174
+
175
+ ## English
176
+
177
+ A command-line tool to **spot AI-generated text** and **possible copying between students' submissions**, and to produce a CSV report sorted by risk.
178
+
179
+ It analyses Jupyter notebooks (`.ipynb`), PDF, Word (`.docx`), Markdown (`.md`) and plain text (`.txt`) in a single pass.
180
+
181
+ > 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.
182
+
183
+ ### Documentation
184
+
185
+ Guides in Spanish and English within each file:
186
+
187
+ - [Usage and formats](docs/USAGE.md): what is extracted from each format and troubleshooting.
188
+ - [Changelog](CHANGELOG.md): change history per version.
189
+ - [Security](SECURITY.md): how to report a problem and which data never to share.
190
+ - [Method and calibration](docs/METODO.md): where the weights and thresholds come from, and how to recalibrate.
191
+ - [Responsible use](docs/USO_RESPONSABLE.md): what to do with a flagged case before talking to the student.
192
+ - [Contributing](CONTRIBUTING.md): environment, code layout and commit convention.
193
+ - [Documentation index](docs/README.md).
194
+
195
+ ### How it works
196
+
197
+ Each submission is split into blocks of ~1500 characters, and every block longer than 300 characters is scored by combining three signals:
198
+
199
+ | Signal | Weight | What it measures |
200
+ | --- | --- | --- |
201
+ | 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 |
202
+ | Statistical uniformity | 30 % | Low variation in sentence length, typical of generated text |
203
+ | Neural network | 20 % | [fakespot-ai/roberta-base-ai-text-detection-v1](https://huggingface.co/fakespot-ai/roberta-base-ai-text-detection-v1) |
204
+
205
+ **Cosine similarity** (bag of words) is also computed between all submissions: notebooks are compared by code (or by their text, when they have no code), everything else by written text. The same assignment submitted in two formats (say PDF and TXT) is not counted as copying.
206
+
207
+ ### Install
208
+
209
+ Requires Python 3.13 or newer; if you don't have `uv`, install it from [astral.sh/uv](https://astral.sh/uv).
210
+
211
+ ```bash
212
+ git clone https://github.com/alberto2005-coder/detector-ia.git
213
+ cd detector-ia
214
+ uv sync --extra modelo
215
+ ```
216
+
217
+ 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.
218
+
219
+ ### Usage
220
+
221
+ Copy the submissions into `revision_ia/` and run:
222
+
223
+ ```bash
224
+ uv run detector-ia
225
+ ```
226
+
227
+ That reads `revision_ia/`, prints progress and writes `reporte_profesional_ia.csv`. There are invented test texts in `ejemplos/`:
228
+
229
+ ```bash
230
+ uv run detector-ia -c ejemplos -s reporte_ejemplos.csv
231
+ ```
232
+
233
+ With options:
234
+
235
+ ```bash
236
+ uv run detector-ia --carpeta entregas --salida reportes/marzo.csv
237
+ uv run detector-ia -c ejemplos/misma_entrega.md --sin-modelo # a single file
238
+ uv run detector-ia --folder entregas --output reporte.csv --lang en
239
+ uv run detector-ia --modelo fakespot-ai/roberta-base-ai-text-detection-v1
240
+ ```
241
+
242
+ It also works without `uv`, with the environment active:
243
+
244
+ ```bash
245
+ python -m detector_ia --carpeta revision_ia
246
+ ```
247
+
248
+ #### Options
249
+
250
+ | Option | Default | Description |
251
+ | --- | --- | --- |
252
+ | `-c`, `--carpeta`, `--ruta`, `--folder`, `--path` | `revision_ia` | Folder with the submissions, or the path of a single file |
253
+ | `-s`, `--salida`, `--output` | `reporte_profesional_ia.csv` | Path of the generated report |
254
+ | `-m`, `--modelo`, `--model` | AI-detection RoBERTa | Hugging Face model to use |
255
+ | `--sin-modelo`, `--no-model` | off | Structural signals only, without downloading the model |
256
+ | `--json` | off | Write the result as JSON on stdout and progress on stderr |
257
+ | `--fail-on` | `ninguno` | Exit with code 1 when the report reaches `error`, `alto`/`high` or `sospechoso`/`suspicious` (`none` works too) |
258
+ | `--lang`, `--idioma` | `es` | Language of the console messages (`es`/`en`); the CSV does not change |
259
+ | `-V`, `--version` | — | Print the installed version and exit |
260
+
261
+ 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.
262
+
263
+ ### Report
264
+
265
+ The CSV is written in UTF-8 with BOM and a `;` separator so it opens directly in Spanish-locale Excel. Columns:
266
+
267
+ - **Archivo / Formato**: file name and extension of the submission.
268
+ - **IA_Media (%)**: mean hybrid score of the scored blocks.
269
+ - **IA_Pico_Max (%)**: highest-scoring block, the most AI-like passage.
270
+ - **Similitud_Companero (%)** and **Coincide_Con**: most similar submission, with its name when similarity is above 75 %.
271
+ - **Veredicto**: `ALTO RIESGO IA`, `REVISAR COPIA ENTRE ALUMNOS`, `Sospechoso (Revisar)`, `Normal` or `Poco texto`.
272
+ - **Fragmento_Sospechoso**: the highest-scoring block, to read it in context.
273
+ - **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.
274
+
275
+ Current thresholds (in `src/detector_ia/main.py`): peak ≥ 58 % or mean ≥ 45 % is high risk; peak ≥ 45 % or mean ≥ 35 % is suspicious; similarity > 88 % is possible copying.
276
+
277
+ ### Layout
278
+
279
+ ```
280
+ detector-ia/
281
+ ├── src/detector_ia/
282
+ │ ├── main.py # CLI, thresholds and report generation
283
+ │ ├── extractores.py # Readers for .ipynb, .pdf, .docx, .txt and .md
284
+ │ └── motores.py # Neural model, structural fingerprint and similarity
285
+ ├── tests/ # Tests with a fake detector, no model download
286
+ ├── docs/ # Index, method, responsible use and formats
287
+ ├── ejemplos/ # Invented texts for trying the tool
288
+ ├── evaluacion/ # Labelled corpus and metrics script
289
+ ├── scripts/ # Release notes from the CHANGELOG
290
+ ├── .github/ # CI, releases, Dependabot and templates
291
+ ├── revision_ia/ # Input submissions (git-ignored)
292
+ ├── README.md # Full guide, in Spanish and English
293
+ ├── CONTRIBUTING.md # How to contribute
294
+ ├── SECURITY.md # Security policy
295
+ ├── CODE_OF_CONDUCT.md # Code of conduct
296
+ ├── CHANGELOG.md # Change history per version
297
+ ├── LICENSE # MIT license
298
+ ├── pyproject.toml # Metadata, dependencies and entry point
299
+ ├── uv.lock # Exact dependency versions
300
+ ├── .gitattributes # Normalized line endings
301
+ └── .gitignore # Excludes .venv, cache_modelo and submissions
302
+ ```
303
+
304
+ ### Privacy
305
+
306
+ 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.
307
+
308
+ ### License
309
+
310
+ Distributed under the MIT license. See [LICENSE](LICENSE) for the full text.
@@ -0,0 +1,281 @@
1
+ # Detector IA
2
+
3
+ [Español](#español) · [English](#english)
4
+
5
+ ---
6
+
7
+ ## Español
8
+
9
+ 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.
10
+
11
+ Analiza cuadernos de Jupyter (`.ipynb`), PDF, Word (`.docx`), Markdown (`.md`) y texto plano (`.txt`) en una sola pasada.
12
+
13
+ > 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.
14
+
15
+ ### Documentación
16
+
17
+ Guías en español e inglés dentro de cada archivo:
18
+
19
+ - [Uso y formatos](docs/USAGE.md): qué se extrae de cada formato y solución de problemas.
20
+ - [Changelog](CHANGELOG.md): historial de cambios por versión.
21
+ - [Seguridad](SECURITY.md): cómo reportar un problema y qué datos no compartir.
22
+ - [Método y calibración](docs/METODO.md): de dónde salen los pesos y los umbrales, y cómo recalibrar.
23
+ - [Uso responsable](docs/USO_RESPONSABLE.md): qué hacer con un caso marcado antes de hablar con el alumno.
24
+ - [Contribuir](CONTRIBUTING.md): entorno, estructura del código y convención de commits.
25
+ - [Índice de documentación](docs/README.md).
26
+
27
+ ### Cómo funciona
28
+
29
+ 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:
30
+
31
+ | Señal | Peso | Qué mide |
32
+ | --- | --- | --- |
33
+ | 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 |
34
+ | Uniformidad estadística | 30 % | Baja variación en la longitud de las frases, típica de texto generado |
35
+ | Red neuronal | 20 % | [fakespot-ai/roberta-base-ai-text-detection-v1](https://huggingface.co/fakespot-ai/roberta-base-ai-text-detection-v1) |
36
+
37
+ Además se calcula la **similitud de coseno** (bolsa de palabras) entre todas las entregas: en los cuadernos se compara el código (o el texto, si el cuaderno no tiene código) y en el resto el texto redactado. Un mismo trabajo entregado en dos formatos (por ejemplo PDF y TXT) no se cuenta como copia.
38
+
39
+ ### Instalación
40
+
41
+ Requiere Python 3.13 o superior y, si no tienes `uv`, puedes instalarlo desde [astral.sh/uv](https://astral.sh/uv).
42
+
43
+ ```bash
44
+ git clone https://github.com/alberto2005-coder/detector-ia.git
45
+ cd detector-ia
46
+ uv sync --extra modelo
47
+ ```
48
+
49
+ 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.
50
+
51
+ ### Uso
52
+
53
+ Copia las entregas a analizar en `revision_ia/` y ejecuta:
54
+
55
+ ```bash
56
+ uv run detector-ia
57
+ ```
58
+
59
+ Eso lee `revision_ia/`, imprime el progreso y guarda `reporte_profesional_ia.csv`. Hay textos inventados de prueba en `ejemplos/`:
60
+
61
+ ```bash
62
+ uv run detector-ia -c ejemplos -s reporte_ejemplos.csv
63
+ ```
64
+
65
+ Con opciones:
66
+
67
+ ```bash
68
+ uv run detector-ia --carpeta entregas --salida reportes/marzo.csv
69
+ uv run detector-ia -c ejemplos/misma_entrega.md --sin-modelo # un solo archivo
70
+ uv run detector-ia --folder entregas --output reporte.csv --lang en
71
+ uv run detector-ia --modelo fakespot-ai/roberta-base-ai-text-detection-v1
72
+ ```
73
+
74
+ También funciona sin `uv`, con el entorno activado:
75
+
76
+ ```bash
77
+ python -m detector_ia --carpeta revision_ia
78
+ ```
79
+
80
+ #### Opciones
81
+
82
+ | Opción | Por defecto | Descripción |
83
+ | --- | --- | --- |
84
+ | `-c`, `--carpeta`, `--ruta`, `--folder`, `--path` | `revision_ia` | Carpeta con las entregas o ruta de un archivo concreto |
85
+ | `-s`, `--salida`, `--output` | `reporte_profesional_ia.csv` | Ruta del reporte generado |
86
+ | `-m`, `--modelo`, `--model` | RoBERTa de detección de IA | Modelo de Hugging Face a usar |
87
+ | `--sin-modelo`, `--no-model` | desactivado | Analiza solo con las señales estructurales, sin descargar el modelo |
88
+ | `--json` | desactivado | Escribe el resultado en JSON por la salida estándar y el progreso por la de errores |
89
+ | `--fail-on` | `ninguno` | Devuelve código de salida 1 si el reporte alcanza `error`, `alto`/`high` o `sospechoso`/`suspicious` (también vale `none`) |
90
+ | `--lang`, `--idioma` | `es` | Idioma de los mensajes de consola (`es`/`en`); el CSV no cambia |
91
+ | `-V`, `--version` | — | Muestra la versión instalada y sale |
92
+
93
+ 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.
94
+
95
+ ### Reporte
96
+
97
+ El CSV se guarda en UTF-8 con BOM y separador `;` para que abra directamente en Excel en español. Columnas:
98
+
99
+ - **Archivo / Formato**: nombre y extensión de la entrega.
100
+ - **IA_Media (%)**: media de la puntuación híbrida de los bloques evaluados.
101
+ - **IA_Pico_Max (%)**: bloque con la puntuación más alta, el que más se parece a texto de IA.
102
+ - **Similitud_Companero (%)** y **Coincide_Con**: entrega más parecida y su nombre si supera el 75 %.
103
+ - **Veredicto**: `ALTO RIESGO IA`, `REVISAR COPIA ENTRE ALUMNOS`, `Sospechoso (Revisar)`, `Normal` o `Poco texto`.
104
+ - **Fragmento_Sospechoso**: el bloque con mayor puntuación, para leerlo en contexto.
105
+ - **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.
106
+
107
+ Umbrales actuales (en `src/detector_ia/main.py`): pico ≥ 58 % o media ≥ 45 % es alto riesgo; pico ≥ 45 % o media ≥ 35 % es sospechoso; similitud > 88 % es posible copia.
108
+
109
+ ### Estructura
110
+
111
+ ```
112
+ detector-ia/
113
+ ├── src/detector_ia/
114
+ │ ├── main.py # CLI, umbrales y generación del reporte
115
+ │ ├── extractores.py # Lectura de .ipynb, .pdf, .docx, .txt y .md
116
+ │ └── motores.py # Modelo neuronal, huella estructural y similitud
117
+ ├── tests/ # Pruebas con un detector falso, sin descargar el modelo
118
+ ├── docs/ # Índice, método, uso responsable y formatos
119
+ ├── ejemplos/ # Textos inventados para probar
120
+ ├── evaluacion/ # Corpus etiquetado y script de métricas
121
+ ├── scripts/ # Notas de release a partir del CHANGELOG
122
+ ├── .github/ # CI, releases, Dependabot y plantillas
123
+ ├── revision_ia/ # Entregas de entrada (ignoradas por git)
124
+ ├── README.md # Guía completa, en español e inglés
125
+ ├── CONTRIBUTING.md # Cómo contribuir
126
+ ├── SECURITY.md # Política de seguridad
127
+ ├── CODE_OF_CONDUCT.md # Código de conducta
128
+ ├── CHANGELOG.md # Historial de cambios por versión
129
+ ├── LICENSE # Licencia MIT
130
+ ├── pyproject.toml # Metadatos, dependencias y entry point
131
+ ├── uv.lock # Versiones exactas de las dependencias
132
+ ├── .gitattributes # Finales de línea normalizados
133
+ └── .gitignore # Excluye .venv, cache_modelo y entregas
134
+ ```
135
+
136
+ ### Privacidad
137
+
138
+ 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.
139
+
140
+ ### Licencia
141
+
142
+ Distribuido bajo la licencia MIT. Consulta [LICENSE](LICENSE) para el texto completo.
143
+
144
+ ---
145
+
146
+ ## English
147
+
148
+ A command-line tool to **spot AI-generated text** and **possible copying between students' submissions**, and to produce a CSV report sorted by risk.
149
+
150
+ It analyses Jupyter notebooks (`.ipynb`), PDF, Word (`.docx`), Markdown (`.md`) and plain text (`.txt`) in a single pass.
151
+
152
+ > 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.
153
+
154
+ ### Documentation
155
+
156
+ Guides in Spanish and English within each file:
157
+
158
+ - [Usage and formats](docs/USAGE.md): what is extracted from each format and troubleshooting.
159
+ - [Changelog](CHANGELOG.md): change history per version.
160
+ - [Security](SECURITY.md): how to report a problem and which data never to share.
161
+ - [Method and calibration](docs/METODO.md): where the weights and thresholds come from, and how to recalibrate.
162
+ - [Responsible use](docs/USO_RESPONSABLE.md): what to do with a flagged case before talking to the student.
163
+ - [Contributing](CONTRIBUTING.md): environment, code layout and commit convention.
164
+ - [Documentation index](docs/README.md).
165
+
166
+ ### How it works
167
+
168
+ Each submission is split into blocks of ~1500 characters, and every block longer than 300 characters is scored by combining three signals:
169
+
170
+ | Signal | Weight | What it measures |
171
+ | --- | --- | --- |
172
+ | 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 |
173
+ | Statistical uniformity | 30 % | Low variation in sentence length, typical of generated text |
174
+ | Neural network | 20 % | [fakespot-ai/roberta-base-ai-text-detection-v1](https://huggingface.co/fakespot-ai/roberta-base-ai-text-detection-v1) |
175
+
176
+ **Cosine similarity** (bag of words) is also computed between all submissions: notebooks are compared by code (or by their text, when they have no code), everything else by written text. The same assignment submitted in two formats (say PDF and TXT) is not counted as copying.
177
+
178
+ ### Install
179
+
180
+ Requires Python 3.13 or newer; if you don't have `uv`, install it from [astral.sh/uv](https://astral.sh/uv).
181
+
182
+ ```bash
183
+ git clone https://github.com/alberto2005-coder/detector-ia.git
184
+ cd detector-ia
185
+ uv sync --extra modelo
186
+ ```
187
+
188
+ 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.
189
+
190
+ ### Usage
191
+
192
+ Copy the submissions into `revision_ia/` and run:
193
+
194
+ ```bash
195
+ uv run detector-ia
196
+ ```
197
+
198
+ That reads `revision_ia/`, prints progress and writes `reporte_profesional_ia.csv`. There are invented test texts in `ejemplos/`:
199
+
200
+ ```bash
201
+ uv run detector-ia -c ejemplos -s reporte_ejemplos.csv
202
+ ```
203
+
204
+ With options:
205
+
206
+ ```bash
207
+ uv run detector-ia --carpeta entregas --salida reportes/marzo.csv
208
+ uv run detector-ia -c ejemplos/misma_entrega.md --sin-modelo # a single file
209
+ uv run detector-ia --folder entregas --output reporte.csv --lang en
210
+ uv run detector-ia --modelo fakespot-ai/roberta-base-ai-text-detection-v1
211
+ ```
212
+
213
+ It also works without `uv`, with the environment active:
214
+
215
+ ```bash
216
+ python -m detector_ia --carpeta revision_ia
217
+ ```
218
+
219
+ #### Options
220
+
221
+ | Option | Default | Description |
222
+ | --- | --- | --- |
223
+ | `-c`, `--carpeta`, `--ruta`, `--folder`, `--path` | `revision_ia` | Folder with the submissions, or the path of a single file |
224
+ | `-s`, `--salida`, `--output` | `reporte_profesional_ia.csv` | Path of the generated report |
225
+ | `-m`, `--modelo`, `--model` | AI-detection RoBERTa | Hugging Face model to use |
226
+ | `--sin-modelo`, `--no-model` | off | Structural signals only, without downloading the model |
227
+ | `--json` | off | Write the result as JSON on stdout and progress on stderr |
228
+ | `--fail-on` | `ninguno` | Exit with code 1 when the report reaches `error`, `alto`/`high` or `sospechoso`/`suspicious` (`none` works too) |
229
+ | `--lang`, `--idioma` | `es` | Language of the console messages (`es`/`en`); the CSV does not change |
230
+ | `-V`, `--version` | — | Print the installed version and exit |
231
+
232
+ 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.
233
+
234
+ ### Report
235
+
236
+ The CSV is written in UTF-8 with BOM and a `;` separator so it opens directly in Spanish-locale Excel. Columns:
237
+
238
+ - **Archivo / Formato**: file name and extension of the submission.
239
+ - **IA_Media (%)**: mean hybrid score of the scored blocks.
240
+ - **IA_Pico_Max (%)**: highest-scoring block, the most AI-like passage.
241
+ - **Similitud_Companero (%)** and **Coincide_Con**: most similar submission, with its name when similarity is above 75 %.
242
+ - **Veredicto**: `ALTO RIESGO IA`, `REVISAR COPIA ENTRE ALUMNOS`, `Sospechoso (Revisar)`, `Normal` or `Poco texto`.
243
+ - **Fragmento_Sospechoso**: the highest-scoring block, to read it in context.
244
+ - **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.
245
+
246
+ Current thresholds (in `src/detector_ia/main.py`): peak ≥ 58 % or mean ≥ 45 % is high risk; peak ≥ 45 % or mean ≥ 35 % is suspicious; similarity > 88 % is possible copying.
247
+
248
+ ### Layout
249
+
250
+ ```
251
+ detector-ia/
252
+ ├── src/detector_ia/
253
+ │ ├── main.py # CLI, thresholds and report generation
254
+ │ ├── extractores.py # Readers for .ipynb, .pdf, .docx, .txt and .md
255
+ │ └── motores.py # Neural model, structural fingerprint and similarity
256
+ ├── tests/ # Tests with a fake detector, no model download
257
+ ├── docs/ # Index, method, responsible use and formats
258
+ ├── ejemplos/ # Invented texts for trying the tool
259
+ ├── evaluacion/ # Labelled corpus and metrics script
260
+ ├── scripts/ # Release notes from the CHANGELOG
261
+ ├── .github/ # CI, releases, Dependabot and templates
262
+ ├── revision_ia/ # Input submissions (git-ignored)
263
+ ├── README.md # Full guide, in Spanish and English
264
+ ├── CONTRIBUTING.md # How to contribute
265
+ ├── SECURITY.md # Security policy
266
+ ├── CODE_OF_CONDUCT.md # Code of conduct
267
+ ├── CHANGELOG.md # Change history per version
268
+ ├── LICENSE # MIT license
269
+ ├── pyproject.toml # Metadata, dependencies and entry point
270
+ ├── uv.lock # Exact dependency versions
271
+ ├── .gitattributes # Normalized line endings
272
+ └── .gitignore # Excludes .venv, cache_modelo and submissions
273
+ ```
274
+
275
+ ### Privacy
276
+
277
+ 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.
278
+
279
+ ### License
280
+
281
+ Distributed under the MIT license. See [LICENSE](LICENSE) for the full text.