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.
- detector_ia-1.0.0/LICENSE +21 -0
- detector_ia-1.0.0/PKG-INFO +310 -0
- detector_ia-1.0.0/README.md +281 -0
- detector_ia-1.0.0/pyproject.toml +80 -0
- detector_ia-1.0.0/pyproject.toml.orig +73 -0
- detector_ia-1.0.0/src/detector_ia/__init__.py +15 -0
- detector_ia-1.0.0/src/detector_ia/__main__.py +4 -0
- detector_ia-1.0.0/src/detector_ia/extractores.py +64 -0
- detector_ia-1.0.0/src/detector_ia/main.py +384 -0
- detector_ia-1.0.0/src/detector_ia/motores.py +183 -0
|
@@ -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.
|