# Kit reproducible: tokens y ventana de contexto

Este kit acompaña la investigación editorial de Ranquia. Cuenta cuatro archivos
de texto plano con dos codificaciones explícitas de `tiktoken==0.14.0`. No llama
a una API, no usa credenciales y no reproduce el overhead de mensajes,
herramientas, imágenes o archivos de una solicitud real.

## Resultados canónicos

| Muestra | Formato/idioma | Encoding | Caracteres | Bytes UTF-8 | Segmentos por espacios | Tokens |
|---|---|---|---:|---:|---:|---:|
| `codigo` | code/python | `cl100k_base` | 718 | 718 | 76 | **167** |
| `codigo` | code/python | `o200k_base` | 718 | 718 | 76 | **167** |
| `en-prose` | prose/en | `cl100k_base` | 522 | 522 | 83 | **97** |
| `en-prose` | prose/en | `o200k_base` | 522 | 522 | 83 | **97** |
| `es-prosa` | prose/es | `cl100k_base` | 527 | 531 | 83 | **121** |
| `es-prosa` | prose/es | `o200k_base` | 527 | 531 | 83 | **102** |
| `tabla` | table/es | `cl100k_base` | 209 | 209 | 5 | **80** |
| `tabla` | table/es | `o200k_base` | 209 | 209 | 5 | **79** |

`Segmentos por espacios` es una medida descriptiva de `str.split()`, no un
recuento lingüístico de palabras. La comparación ES/EN usa una sola pareja de
textos alineados semánticamente: muestra que el resultado depende de la muestra
y del encoding, pero **no permite generalizar sobre idiomas completos**. Código,
CSV y prosa tampoco son muestras equivalentes.

Los valores completos están en `results/token-summary.json` y
`results/token-summary.csv`; los IDs y bytes de cada pieza están en
`results/token-pieces.json`.

## Reproducir en Windows con CPython 3.11

```powershell
py -3.11 -m venv .venv
.venv\Scripts\python -m pip install --require-hashes -r requirements-win-py311.lock.txt
.venv\Scripts\python -B scripts/bootstrap_tokenizers.py --cache .runtime-cache/tiktoken
.venv\Scripts\python -B scripts/count_tokens.py --cache .runtime-cache/tiktoken
$env:TIKTOKEN_CACHE_DIR = (Resolve-Path .runtime-cache/tiktoken).Path
.venv\Scripts\python -B -m unittest discover -s tests -v
.venv\Scripts\python -B scripts/verify_manifest.py
```

`bootstrap_tokenizers.py` es el único paso que puede necesitar red. Guarda los
datos del tokenizer en el directorio indicado y registra tamaños/hashes en
`results/tokenizer-cache-manifest.json`. Conteo, tests y cálculo funcionan sin
red después del bootstrap. El caché no se distribuye en este directorio.

## Calcular un coste con tarifas propias

Completa una copia de `config/pricing-template.json` con proveedor, modelo,
superficie, moneda, unidad, tarifas, URL oficial y fecha. Prepara un escenario:

```json
{
  "requests": 100,
  "input_tokens": 1000,
  "cached_input_tokens": 500,
  "output_tokens": 200
}
```

Luego ejecuta:

```powershell
.venv\Scripts\python scripts/calculate_cost.py --pricing mi-precio.json --scenario mi-escenario.json
```

La fórmula asume que `cached_input_tokens` es un subconjunto de
`input_tokens`. Confirma esa semántica en la documentación del proveedor. No
incluye herramientas, búsqueda, almacenamiento, imagen, audio ni otras unidades.
`results/pricing-example.json` usa tarifas hipotéticas y no describe un producto.
El script rechaza metadatos incompletos, fechas distintas de `YYYY-MM-DD`, URLs
que no sean HTTP(S) absolutas, unidades no positivas, tarifas negativas/no
finitas y recuentos negativos o no enteros.

## Qué puede y qué no puede probar

- Sí reproduce el conteo de estos bytes con esta versión y estos encodings.
- Sí muestra que una conversión fija entre palabras, caracteres y tokens no es
  una propiedad del corpus.
- No mide una solicitud completa ni el uso real de un chatbot.
- No permite trasladar límites entre web/app y API.
- No demuestra que una ventana más grande entregue mejores respuestas.
- No convierte tokens a páginas o libros mediante una regla fija.

Para claims de producto, consulta documentación vigente de cada proveedor. Las
referencias de OpenAI usadas por el artículo deben proceder de
https://developers.openai.com/api/docs/ o https://platform.openai.com/; la
estructura específica de contexto de Claude se atribuye a
https://platform.claude.com/docs/es/build-with-claude/context-windows.

## Integridad y procedencia

- Corpus y scripts: creados para Ranquia, licencia MIT, sin datos personales.
- Dependencias: versiones/hashes en el lock y avisos en `THIRD_PARTY-NOTICES.md`.
- Entradas y resultados: SHA-256 en `manifest-sha256.json`.
- El manifest se excluye a sí mismo para evitar autorreferencia.
- Cambiar un byte, versión o encoding crea otra versión del experimento.