Metadata-Version: 2.4
Name: nexpi
Version: 0.2.2
Summary: Chip virtual de generacion de video: anclas por difusion en la integrada, propagacion 2.5D en CPU y acelerador universal para modelos de video sin GPU dedicada
Author: Nexora Technology LLC
Maintainer: Nexora Technology LLC
Keywords: difusion,video,aceleracion,openvino,igpu,cpu,diffusers,inferencia,plazo,sla
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openvino>=2025.4.0
Requires-Dist: numpy>=2.0
Requires-Dist: opencv-python>=4.10
Requires-Dist: transformers>=4.50
Requires-Dist: sentencepiece>=0.2
Requires-Dist: diffusers>=0.30
Requires-Dist: torch>=2.4
Requires-Dist: huggingface_hub>=0.30
Requires-Dist: psutil>=5.9
Requires-Dist: packaging>=23
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.30
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: booster
Requires-Dist: dxcam>=0.0.5; extra == "booster"
Requires-Dist: comtypes>=1.4; extra == "booster"
Requires-Dist: windows-capture>=1.4; extra == "booster"
Requires-Dist: pywin32>=306; extra == "booster"

# NEXPI

Dos piezas que comparten una misma tesis: **el video es casi todo redundante, y
el hardware que la gente ya tiene esta desaprovechado.**

```
nexpi_accel/   ACELERADOR UNIVERSAL — hace que modelos de video de otros corran
               en maquinas sin GPU dedicada (integrada, NPU o solo CPU)
nexpi/         GENERADOR PROPIO 2.5D — texto -> mp4 1080p con camara cinematografica
```

## Instalacion

```bash
pip install nexpi                # acelerador + contrato + auditoria + edicion (~1,5 GB, trae torch); ffmpeg en el PATH
pip install "nexpi[booster]"     # ademas, la captura de pantalla/ventana del Frame Booster (solo Windows)
nexpi instalar-modelos           # SOLO para la generacion de video propia, `nexpi generar` (~2,4 GB)
nexpi-accel doctor               # lo primero en una maquina nueva: que funciona, que falta y como arreglarlo
```

Python 3.10-3.13. Para integrar la edicion en otra plataforma (un ViralFlick, un Opus Clip)
basta con `pip install nexpi`: no hacen falta ni `[booster]` ni los modelos.

Instalado desde PyPI, NEXPI guarda cache, modelos y salidas (entre ellas el `doctor.json`
del doctor) en `~/.nexpi`, fuera del entorno virtual; `nexpi rutas` dice donde y la variable
`NEXPI_HOME` lo cambia. Para dejar la maquina como estaba: `pip uninstall nexpi` y borrar
`~/.nexpi`.

Para desarrollar, desde el repositorio: `pip install -e ".[booster,dev]"`; los pesos de los
bancos, con `python bench/fetch_models.py` y `python bench/fetch_video_model.py`.

---

## 1. NEXPI Accel — acelerador universal de modelos de video

**El problema:** todo lo que existe para acelerar generacion de video esta hecho
para NVIDIA. FastVideo soporta NVIDIA y Apple Silicon, y nada mas. Las tecnicas
de atencion dispersa (SVG, VSA, Sliding Tile) exigen kernels CUDA o CK-Tile. Si
tienes un portatil con grafica integrada, no hay nada para ti.

**Lo que hace NEXPI:** se enchufa a un pipeline de difusion que ya tengas y
aplica cinco palancas que **se multiplican entre si**:

| # | Palanca | Coste | Ganancia |
|---|---|---|---|
| 1 | pasos (cache adaptativa) | lineal | 2-6x |
| 2 | pixeles (superresolucion) | **cuadratico** | 2-4x |
| 3 | fotogramas (interpolacion) | lineal | 2-4x |
| 4 | precision (fp16 / int8) | lineal | 2x |
| 5 | unidad de ejecucion | segun silicio | 2.5x |

```bash
python -m nexpi_accel hardware              # que hay en esta maquina, MEDIDO
python -m nexpi_accel plan --segundos 60    # como repartir el computo
python -m nexpi_accel video "un gato en la ventana" --segundos 90
```

```python
from nexpi_accel import acelerar
with acelerar(pipe, presupuesto_error=0.03) as a:   # cualquier pipeline de diffusers
    video = pipe(prompt, num_frames=16).frames[0]
print(a.informe())
```

### Los agentes: quien detecta que, y que recuerda

NEXPI es un conjunto de agentes con una responsabilidad cada uno, que miden en vez de
suponer y dejan memoria por maquina: `doctor` (que funciona), `hardware` (que hay),
`capacidades` (que acepta cada unidad), `detector` (que modelo), `planificador` y
`calibrador` (que palancas), `libro de contratos` (sobre que se promete), y los ejecutores
(`chip automatico`, `contrato`, `auditoria`, `booster`) que devuelven lo medido. El mapa y
las reglas en [docs/AGENTES.md](docs/AGENTES.md).

```bash
nexpi-accel --help                 # las ordenes, por fases: diagnostico, deteccion, decision, ejecucion
nexpi-accel agentes                # estado y memoria de cada agente en esta maquina
nexpi-accel agentes --olvidar hardware   # se vuelve a medir la proxima vez
```

### El chip se enchufa solo

No hace falta decirle a NEXPI que modelo es ni pasarle nada: lo identifica por lo
que ES (el modulo que evalua la difusion, sus parametros contados de verdad y lo
que admite su llamada) y le aplica el plan que salga del hardware ya medido.

```python
import nexpi_accel.auto                  # una linea: todo lo que cargues despues sale acelerado
pipe = DiffusionPipeline.from_pretrained("Lightricks/LTX-Video")
video = pipe(prompt, num_frames=97).frames[0]
```

O envolviendo por fuera un programa que ya tengas, sin abrirlo:

```bash
python -m nexpi_accel detectar               # que modelos hay ya en la maquina
python -m nexpi_accel auto mi_script.py      # lo ejecuta con el chip puesto
python -m nexpi_accel auto mi_script.py --segundos 60 --calidad rapida
```

Sin objetivo de tiempo solo tira de la palanca que **no cambia lo que pediste**:
la cache adaptativa (misma resolucion, mismos fotogramas, mismos pasos). Con
objetivo de tiempo entran las cinco: genera mas pequeno y sube con
superresolucion, genera menos fotogramas y los repone interpolando, recorta
pasos y reparte las etapas entre las unidades. Lo que quita, lo devuelve: si
pides 16 fotogramas de 512x512, recibes 16 de 512x512.

Funciona con lo que ya tengas descargado (cache de HuggingFace, ComfyUI, A1111):
no hay que convertir ni volver a bajar nada.

### Auditoria: lo que se le entrega a un cliente antes de cobrar

```bash
nexpi-accel auditoria su_script.py --determinismo --informe informe.html
```

Ejecuta el proyecto del cliente **sin tocarlo**, dos veces en procesos aparte
(tal cual esta hoy, y con el chip enchufado), y emite un informe HTML con el
veredicto: `ACELERABLE`, `NO COMPENSA`, `GANA TIEMPO, CAMBIA EL RESULTADO`...
Con `--determinismo` repite la base para comprobar que el script es repetible;
si no fija la semilla, lo dice y no se inventa una comparacion de calidad.

Un informe que siempre sale bien no lo cree nadie: si el chip no ayuda, el
informe lo dice, y eso es lo que hace que valga algo cuando si ayuda.

### El proyecto original, para quien quiera comprarlo entero

```bash
python marca/empaqueta_original.py              # ~22 MB
python marca/empaqueta_original.py --con-videos # + el material de marca
```

Un zip con el codigo, la investigacion (`docs/`), los bancos, los registros de
los 67 experimentos y las mediciones, mas `INVENTARIO.md` (que hay y donde esta
la prueba de cada cifra) y `MANIFIESTO.sha256` (huella de cada fichero, para
que el comprador compruebe que nada falta ni se toco). Aborta si detecta algo
con pinta de credencial. Los pesos de los modelos no viajan: son de terceros.

### Frame Booster para juegos, en cualquier PC sin grafica (o con una floja)

```bash
pip install "nexpi[booster]"                  # ~1,5 GB; el [booster] es la captura (solo Windows)
nexpi-accel doctor                            # que funciona y que falta en ESTA maquina
nexpi instalar-modelos                        # SOLO para la generacion de video propia (~2,4 GB)
nexpi-accel booster --calibrar                # mide ESTA maquina y elige la configuracion
nexpi-accel booster --auto --fuente-ventana "Mi juego"
nexpi-accel escena --fps 30                   # juego sintetico para probarlo sin un juego real
```

`--calibrar` sintetiza fotogramas de juego a 1080p, 900p, 720p y 540p en esta
maquina, mide cuanto cuesta cada uno y elige la resolucion mas alta que cabe en
el ritmo pedido, cuantos hilos dejarle al juego, y la unidad: **CPU si la unica
grafica es la integrada** (se la deja entera al juego, que es lo que Lossless
Scaling no puede hacer en una Intel), **OpenCL en la integrada si ademas hay una
dedicada** (el juego ira en la dedicada y la integrada esta ociosa). Con
`--auto` aplica lo calibrado. La cadencia es la correcta (el fotograma inventado
y el real van equiespaciados) y la latencia se MIDE, no se estima.

El juego sintetico (`nexpi_accel/escena.py`) es una escena 3D renderizada en
CPU, determinista en el tiempo: corre en cualquier PC sin cuenta ni anti-cheat,
carga la CPU como un juego, y da la verdad de terreno con la que se mide la
calidad de los fotogramas inventados (`bench/bench_booster_calidad.py`).

**Medido en el i9-12900H sin GPU dedicada**: la calibracion elige 720p, flujo 0,25 y 7
hilos; con el juego sintetico a 30 fps, NEXPI entrega **52 fps** y **el juego sigue a
30,0 fps** (su render sube de 19,7 a 27,8 ms); latencia medida 28 ms el fotograma real,
43 ms el inventado. Calidad contra la verdad de terreno: el modo calidad gana +4,1 dB y
+0,016 de SSIM sobre repetir el fotograma; el rapido empata en PSNR con una mezcla
lineal. Todo, con sus trampas (DPI, recorte del area de cliente), en
`docs/JUEGOS_MEDIDO.md`.

### Contrato de plazo: lo que no hace nadie

Todos los aceleradores del mercado te dan velocidad. Ninguno te da una
**garantia**. NEXPI si:

```bash
nexpi-accel contrato "un faro al atardecer" --plazo 30 --certificado cert.json
```

```python
from nexpi_accel import contrato
oferta = contrato.negocia(pipe, plazo=30, height=512, width=512)   # antes de gastar un vatio
print(oferta.texto())
salida, cert = contrato.ejecuta(pipe, plazo=30, prompt="un faro", height=512, width=512)
print(cert.texto())
```

Tres piezas:

1. **Negociacion**: dice SI o NO *antes* de empezar, y si no puede, dice cual es
   el mejor tiempo alcanzable en esta maquina.
2. **Controlador**: dentro del bucle mide el ritmo real, aprieta o afloja la
   cache y, si el siguiente paso no cabe en el plazo, **entrega lo que tiene**.
   Un modelo de difusion siempre tiene una imagen a medio hacer utilizable: por
   eso el plazo se puede cumplir siempre.
3. **Certificado**: que se prometio, que paso y con que se midio, con huella
   para que no se pueda retocar sin que se note.

**Medido en SD1.5 a 512x512 (CPU, sin GPU dedicada):**

| plazo | real | |
|---|---|---|
| 240 s | 64,8 s | CUMPLIDO (previsto 68,1 s: 5% de error) |
| 90 s | 78,8 s | CUMPLIDO |
| 40 s | 29,9 s | CUMPLIDO, entregado al vencer (2 pasos; un tercero no cabia) |
| 25 s | 20,7 s | CUMPLIDO, entregado al vencer |
| 15 s | 10,2 s | CUMPLIDO, entregado al vencer |

La promesa **no sale de un modelo teorico**: sale de lo medido en esta maquina y
guardado en `cache/contratos.json`, escalado por pixeles cuando cambia la
resolucion. El certificado dice siempre de donde sale la cifra y con cuantas
ejecuciones se sostiene. Y lo que dice de la desviacion es lo que de verdad se
ha medido (el error de las verificaciones de la cache contra la red real), no la
distancia al resultado sin acelerar, que exigiria generarlo dos veces.

**Lo que aporta y no existe en ningun otro sitio:**

- **Presupuesto de error en lazo cerrado** en vez de umbral fijo calibrado a mano.
  Medido: **33,5 dB con 28,7/30 evaluaciones** frente a **20,4 dB con 26/30** del
  metodo publicado. Eso es sobre trayectorias de prueba; sobre SD1.5 real, saltar
  2 de 25 pasos **cambia la imagen** (10-16 dB sobre miniaturas, medido con la
  auditoria). La cache compra tiempo a cambio de fidelidad: no promete la misma
  imagen, y la auditoria lo mide en cada proyecto en vez de suponerlo.
- **Coeficiente de extrapolacion aprendido** por minimos cuadrados en cada
  verificacion. Extrapolar a ciegas hunde la calidad de 33,5 a 21,1 dB en
  modelos destilados; NEXPI lo detecta y se comporta como copia cuando conviene.
- **Autocalibracion**: mide su propio fallo cada pocos saltos y corrige la
  ganancia. Por eso funciona igual en cualquier modelo y en cualquier hardware.
- **Enganche universal**: envuelve `pipe.unet`/`pipe.transformer`, cuenta pasos
  por cambio de timestep (acierta con CFG en lote y separado) y lleva una cache
  por rama de guia. Vale para Wan, LTX, CogVideoX, AnimateDiff, SVD y pipelines
  propios, sin una linea de codigo por modelo.
- **Runtime OpenVINO** que ejecuta modelos de diffusers en iGPU, NPU o CPU, con
  captura automatica de las formas reales del modelo y respaldo por
  `torch.compile`.
- **Planificador con presupuesto de tiempo**: le dices "en 60 segundos" y reparte
  las cinco palancas sobre el hardware que ha medido.

Detalles y fuentes en [docs/ACELERADOR.md](docs/ACELERADOR.md).

### Edicion y juegos (medido)

- **Edicion**: `nexpi_accel/ffmpeg_accel.py` elige la ruta mas rapida de ffmpeg.
  Recorte de 6 s **13x** mas rapido (sin recodificar), transcodificacion **1,8x**
  con la cadena entera en la integrada. Y una regla medida: decodificar por
  hardware solo compensa si la cadena sigue en hardware (con filtros de CPU en
  medio, `hwdownload` se come la ganancia: 5 %, medido). Los fotogramas clave se
  leen de los paquetes, sin decodificar, para cualquier codec (en AV1 el
  decodificador ignora `-skip_frame nokey`). Y honestidad de caso de uso: en una
  plataforma de clips verticales donde todo clip se transforma (caras, 9:16,
  subtitulos), el recorte sin recodificar no aplica y el tiempo lo domina la
  deteccion de caras, que NEXPI no acelera hoy.
- **Juegos**: `nexpi_accel/juegos.py` (NEXPI Frame Booster) sintetiza fotogramas
  intermedios con flujo optico y warping, como DLSS 3 Frame Generation o AFMF pero
  sin hardware dedicado, y `nexpi_accel/booster.py` lo hace **en vivo** sobre lo que
  hay en pantalla (captura DXGI a 8 ms, sintesis en CPU, presentacion). **Medido en
  vivo sobre una fuente en movimiento** (`docs/JUEGOS_MEDIDO.md`): a 720p, 17-21 ms
  por fotograma y 45-55 -> 89-109 fps; **a 1080p NO cabe** (40-47 ms, 20-23 fps de
  entrada). La configuracion que se sostiene: el juego a 720p, NEXPI dobla fotogramas
  y la ventana escala a 1080p. Sintetizar en CPU cuesta lo mismo que en la iGPU, asi
  que deja la integrada entera para el juego, que es lo que Lossless Scaling no puede
  hacer en una Intel. Latencia anadida ~50 ms a 30 fps de fuente: inherente a toda
  generacion de fotogramas. Ningun chip hace correr un juego en un PC sin requisitos:
  lo que hace es duplicar los fotogramas presentados y permitir renderizar mas pequeno.
  **Sobre Fortnite real todavia no esta medido** (protocolo en el documento).

### Marca

`marca/lamina_chip.py` y `marca/lamina_chip_3d.py` generan las laminas de producto
por geometria vectorial; `marca/pdf_nexpi.py` el dossier tecnico (solo cifras
medidas); `marca/video_promo.py` el video promocional en espanol e ingles, con voz
neuronal y musica sintetizada, todo de cero.

### Se puede sumar la CPU y la integrada? (experimento)

Si, pero mucho menos de lo que promete la aritmetica. Medido con la maquina en
reposo: iGPU sola 15,91 fotogramas/s, CPU sola 6,72, suma teorica 22,63, y el
mejor reparto (el de NEXPI, 70/30 segun velocidad medida) da **16,39: solo un
+3 %**.

La razon esta medida: **al trabajar a la vez, cada unidad pierde ~24 %** porque
la integrada no tiene memoria propia y **compiten por el mismo bus**. No son dos
unidades independientes, son dos consumidores del mismo recurso escaso.

El experimento completo, con el metodo y las consecuencias de diseno, en
[docs/EXPERIMENTO_GPU_VIRTUAL.md](docs/EXPERIMENTO_GPU_VIRTUAL.md).

---

## 2. NEXPI (generador 2.5D)

Texto -> video 1080p en un portatil sin GPU: un ancla por difusion por plano
(SDXS 1 paso + TAESD, ~0,45 s en la integrada), profundidad, realce x4, capas
2.5D y movimiento de camara por warp en CPU (~18 ms/fotograma).

```bash
python -m nexpi generar "Un faro solitario en un acantilado al atardecer. Las olas rompen contra las rocas" -d 12
python -m nexpi api        # interfaz web en http://127.0.0.1:5050
```

Clip de 12 s en ~17 s (x1,1 tiempo real). Limite honesto: cada plano es una
imagen con movimiento de camara real por profundidad, no hay movimiento de
personajes dentro del plano. Detalles en [docs/ARQUITECTURA.md](docs/ARQUITECTURA.md).

---

## Hardware de referencia (medido, no de catalogo)

Portatil i9-12900H + Iris Xe 96 EU, **sin GPU NVIDIA**:

| Unidad | Medido |
|---|---|
| Iris Xe via OpenVINO fp16 | **756 GFLOP/s** |
| CPU via OpenVINO | 326 GFLOP/s |
| CPU via torch | 296 GFLOP/s |

La integrada rinde **2,5x la CPU** y practicamente todo el software de video la
ignora.

Mediciones completas y metodologia en [docs/HARDWARE_MEDIDO.md](docs/HARDWARE_MEDIDO.md)
e [docs/INVESTIGACION.md](docs/INVESTIGACION.md).

## Nexpigramas: LTX-Video en cualquier PC (2026-09-02)

LTX-Video 2B destilado corre entero en este portatil sin GPU dedicada: T5-XXL en streaming desde GGUF, transformer en 28 bloques OpenVINO int8 (CPU 6,6 s/paso, Iris Xe 3,9 s/paso, torch 19,5 s), VAE por baldosas. Clip 512x320x49: 87 s en la integrada, 107 s en CPU. Detalles y trampas en `docs/NEXPIGRAMAS.md`.

    python -m nexpi_accel.ltx_cpu "prompt" --ancho 512 --alto 320 --fotogramas 49 --backend gpu -o clip.mp4
    python -m nexpi_accel.nexpigramas plan --ancho 1024 --alto 640 --fps 48 --duracion 2 --presupuesto 300
