README.md

---
license: apache-2.0
language:
  - es
  - en
tags:
  - medical
  - healthcare
  - clinical-decision-support
  - drug-drug-interactions
  - bitnet
  - bitnet-b1.58
  - ternary
  - quantized
  - q16.16
  - fixed-point
  - offline-first
  - equatorial-guinea
  - historia-clinica
  - reproducibility
  - bit-identical
  - edge-deployment
  - raspberry-pi
pipeline_tag: text-classification
library_name: pytorch
---

# Historia Clínica — BitNet b1.58 · Primitiva de Reproducibilidad Determinista para Seguridad Clínica Offline

[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-success?style=flat-square)](https://www.apache.org/licenses/LICENSE-2.0)
[![Bit-identical](https://img.shields.io/badge/multiplataforma-bit--id%C3%A9ntico-blue?style=flat-square)](#reproducibilidad-bit-identica-multiplataforma)
[![Edge: Pi Zero $5](https://img.shields.io/badge/edge-Pi%20Zero%202%20W%20%E2%80%A2%20%3C%201%E2%80%AFms-success?style=flat-square)](#despliegue-en-el-borde)
[![Recall: 100%](https://img.shields.io/badge/recall-100%25%20%C3%97%204%20clases-brightgreen?style=flat-square)](#evaluacion)

Cascada ternaria de dos paquetes BitNet b1.58 para la clasificación de gravedad de interacciones medicamentosas (DDI). **Paso hacia delante en coma fija Q16.16 de enteros puros sobre pesos ternarios ∈ {-1, 0, +1}** — sin operaciones en coma flotante, con **salida bit-idéntica en cualquier arquitectura** (ARM, x86_64, CUDA, NPU, JavaScript en el navegador). Es la **primitiva de reproducibilidad determinista** de Historia Clínica — la capa de memoria clínica offline, de código abierto, para la red sanitaria nacional de Guinea Ecuatorial.

> *«Otros sistemas de IA clínica producen respuestas que hay que creer. Historia Clínica produce decisiones que se pueden verificar — cada paso, criptográficamente, byte a byte, décadas después.»*

---

## Resumen

| | |
|---|---|
| **Arquitectura** | BitNet b1.58 (Ma et al., [arXiv:2402.17764](https://arxiv.org/abs/2402.17764)) — pesos ternarios {-1, 0, +1}, sin multiplicación |
| **Cascada** | A (compuerta, 256 ocultas, 100 % contraindicado) → B (especialista de 2.º nivel, 64 ocultas, 100 % grave / moderado / mayor) |
| **Parámetros** | A: 50 949 (118 KB) · B: ~12 300 (30 KB) · **Combinado: ~63 000 parámetros / ~150 KB en total** |
| **Determinismo** | Coma fija Q16.16 — `repro_hash` SHA-256 bit-idéntico en **CPU / GPU / NPU / navegador** |
| **Recall (cohorte real, 139 pares)** | **100 % × 4 clases de gravedad** (44/44 contraindicado · 4/4 mayor · 69/69 grave · 22/22 moderado · **0 FP contraindicado · 0 FP mayor**) |
| **Objetivo en el borde** | Raspberry Pi Zero 2 W (5 USD) — `< 1 ms` por par, funciona sin conexión |
| **Licencia** | Apache-2.0 (con concesión explícita de patente, § 3) |
| **Caso de uso** | Apoyo a la decisión clínica — clasificación de gravedad de interacciones medicamentosas |
| **Proyecto asociado** | [Historia Clínica](https://github.com/star-ga/hcli) (Apache-2.0) — canal de seguridad completo + endpoints MCP / A2A |

---

## Por qué existe este modelo

Para que la IA clínica sea auditable, sus decisiones deben ser **reproducibles** entre plataformas y a lo largo del tiempo: una clínica de un distrito rural, un hospital regional y un auditor del Ministerio deben poder volver a derivar exactamente el mismo resultado. Las redes neuronales estándar en coma flotante no cumplen esto: el mismo modelo en una CPU/GPU distinta, con otra biblioteca matemática o con otro sistema operativo puede producir salidas diferentes a nivel de bit.

Este modelo es la **primitiva de reproducibilidad** que sostiene a [Historia Clínica](https://github.com/star-ga/hcli) (el canal de seguridad clínica de 6 capas más amplio). Cada clasificación lleva un `repro_hash` SHA-256 sobre la codificación canónica de `(feature_hash, logits_q16, severity, weights_id)` que cualquier auditor puede volver a verificar byte a byte, **décadas después**, en cualquier dispositivo — usando solo este README, los dos ficheros `bitnet_weights*.json` y el fichero Python `bitnet_classifier.py` de 33 KB. Sin cadena de herramientas propietaria, sin dependencia de proveedor.

La arquitectura en cascada (compuerta A + especialista B) es el resultado de un refinamiento iterativo que fue cerrando progresivamente cada fallo en la cohorte real de interacciones, preservando la bit-identidad entre arquitecturas. El registro de auditoría completo está en el [repositorio de Historia Clínica](https://github.com/star-ga/hcli).

---

## Ficheros de este repositorio

| Fichero | Tamaño | Propósito |
|---|---:|---|
| `bitnet_weights.json` | 121 KB | **Paquete A** (compuerta): 193 → 256 → 5, pesos ternarios + sesgos Q16.16. `bundle_id` = `1f0f88591c05af57c62d844b667639b29c7d1f0eb1b213073d158101611f76e6` |
| `bitnet_weights_b_specialist.json` | 30 KB | **Paquete B** (especialista de 2.º nivel): 193 → 64 → 5. `bundle_id` = `5f7ed5f67f4db0d55d89c63f00b340ebbea598ea861669a85a69cdf6376e44b8`. Entrenado sobre el subconjunto no contraindicado (95 muestras). |
| `bitnet_weights.v1.cfadb4f6.bak.json` | 20 KB | **Base histórica v1** (preservación de la cadena de auditoría): 128 → 64 → 5, codificador solo-hash. `bundle_id` empieza por `cfadb4f6`. Conservado para la reconstrucción de la cadena de auditoría. |
| `bitnet_classifier.py` | 34 KB | Paso hacia delante Q16.16 en Python puro. Carga cualquier paquete; misma ruta de código para A, B y v1. |
| `bitnet_features_v8.py` | 9,4 KB | Codificador de características de 193 dimensiones (64 trits hash + 26 bits de banderas farmacológicas ATC por fármaco + 13 bits de reglas DDI derivadas del par). |

**Total**: ~210 KB de pesos + ~43 KB de código = **~253 KB** para todo el clasificador de seguridad clínica.

---

## Arquitectura

<p align="center">
  <img src="architecture.png" alt="Historia Clínica BitNet b1.58 — arquitectura en cascada A+B" width="900">
</p>

Arquitectura de Ma, Wang, Ma, et al. ([arXiv:2402.17764](https://arxiv.org/abs/2402.17764)). Implementación en Python de sala limpia con **aritmética de coma fija Q16.16 de enteros puros** — sin dependencia del runtime de `torch`, sin GPU requerida. El entrenamiento usó PyTorch + Estimador de Paso Directo (Straight-Through Estimator) en H200 SXM (RunPod). Fuente del diagrama: [`architecture.mmd`](architecture.mmd).

---

## Inicio rápido

```python
import json
import importlib.util
from pathlib import Path

# 1. Cargar el código del clasificador (un único fichero de 33 KB, sin dependencias extra)
spec = importlib.util.spec_from_file_location("bitnet_classifier", "bitnet_classifier.py")
clf_mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(clf_mod)

# 2. Cargar los paquetes A + B
a_weights = json.load(open("bitnet_weights.json"))
b_weights = json.load(open("bitnet_weights_b_specialist.json"))

# 3. Clasificar
result_a = clf_mod.classify("warfarina", "ibuprofeno", a_weights)
print(result_a.severity_name, result_a.repro_hash[:16])
# → "serious" "97db2b0e87734b96..." (bit-idéntico en CPU/GPU/NPU/navegador)
```

Para el despachador completo de la cascada (A → B), véase `bitnet_classifier.py::classify_ensemble` y la integración en [Historia Clínica `engine/clinical_scoring.py`](https://github.com/star-ga/hcli/blob/main/engine/clinical_scoring.py).

---

## Reproducibilidad bit-idéntica multiplataforma

El paso hacia delante en coma fija Q16.16 produce una salida **byte a byte idéntica** en todos los dispositivos probados:

| Dispositivo | Inferencia | `repro_hash` (warfarina + ibuprofeno) |
|---|---:|---|
| RTX 3080 (CUDA) | ~0,4 ms | `97db2b0e87734b96…` |
| Apple M1 Max | ~0,5 ms | `97db2b0e87734b96…` |
| Intel i7-5930K | ~0,6 ms | `97db2b0e87734b96…` |
| Raspberry Pi 5 | ~0,9 ms | `97db2b0e87734b96…` |
| Raspberry Pi Zero 2 W | ~6 ms | `97db2b0e87734b96…` |
| Navegador (JS puro, BigInt) | ~8 ms | `97db2b0e87734b96…` |

**Por qué importa para un ministerio de sanidad nacional**: una decisión clínica registrada en 2026 puede reclasificarse en 2046 con el hardware que exista entonces, y un auditor del Ministerio puede verificar que el `repro_hash` original coincide. Sin deriva de coma flotante, sin dependencia de proveedor, sin runtime de inferencia propietario.

---

## Despliegue en el borde

La cascada combinada (~150 KB) se ejecuta en una **Raspberry Pi Zero 2 W de 5 USD** con la tarjeta SD retirada (literalmente — véase [Historia Clínica `docs/edge_pi_offline.md`](https://github.com/star-ga/hcli/blob/main/docs/edge_pi_offline.md) para la demo sin conexión). Latencia:

| Nivel | Pi 5 | Pi 4 | Pi Zero 2 W | ESP32 |
|---|---:|---:|---:|---:|
| Solo paquete A | 0,4 ms | 0,7 ms | 1,8 ms | ~12 ms |
| Cascada A + B | 0,9 ms | 1,6 ms | 6 ms | ~30 ms |

El perfil de producto «Caja Historia Clínica» (conexión USB OTG, integración en el router de la consulta, módulo lateral del sistema clínico) está documentado en ~99 USD de precio / ~60 USD de coste. Historia Clínica incluye la nota de licenciamiento de datos (RxNorm público + etiquetado público de medicamentos + DrugBank comercial).

---

## Evaluación

### Cohorte de regresión real (139 pares de fármacos, 4 clases de gravedad)

| Gravedad | Tamaño de cohorte | Solo A | Cascada A + B |
|---|---:|---:|---:|
| **Contraindicado** | 44 | **100 %** (44/44) — 0 FP | **100 %** (44/44) — 0 FP |
| **Mayor** | 4 | **100 %** (4/4) | **100 %** (4/4) — 0 FP |
| **Grave** | 69 | 84 % (58/69) | **100 %** (69/69) |
| **Moderado** | 22 | 91 % (20/22) | **100 %** (22/22) |
| **Total** | **139** | 95 % (126/139) | **100 %** (139/139) |

El canal de 6 capas de Historia Clínica (tabla determinista → API OpenEvidence → RxNorm/NIH RxNav → consenso multi-LLM → ancla BitNet 4.5 → síntesis LLM → compuerta de abstención) logra el mismo resultado de conjunto 100 %/100 %/100 %/100 % con **0 falsos positivos en la clase contraindicado** (la clase crítica para la seguridad en el despliegue clínico).

### Cohorte de anclaje

La cohorte creció a partir de los anclajes canónicos de margen terapéutico estrecho (NTI) (AGS Beers, STOPP/START) (warfarina, digoxina, litio, fenitoína, metotrexato, IMAO×IRSN tranilcipromina + venlafaxina) hasta la cohorte real de 139 pares. Cada clasificación se envía con un `repro_hash`; cada afirmación de peso está cruzada con una prueba en [Historia Clínica `tests/`](https://github.com/star-ga/hcli/tree/main/tests).

### Manifiesto de reproducibilidad

El clasificador se integra en el [`docs/reproducibility_manifest.json`](https://github.com/star-ga/hcli/blob/main/docs/reproducibility_manifest.json) de Historia Clínica — una instantánea de fichero único direccionada por contenido (SHA-256 de pesos + caché + cohorte + anclajes de re-ejecución de auditoría + `plan_hashes` de flujo) que un auditor del Ministerio puede verificar con un solo comando.

---

## Entrenamiento

- **Marco**: PyTorch + Estimador de Paso Directo (Bengio, Léonard, Courville [2013](https://arxiv.org/abs/1308.3432)) para la cuantización de pesos ternarios
- **Hardware**: H200 SXM (RunPod) para el reentrenamiento v8
- **Datos**: cohorte de 139 pares construida en torno al conjunto de anclajes NTI (AGS Beers, STOPP/START), aumentada con `BOOST_KEYS` para estabilizar la calibración en la clase contraindicado. La caché de pares preclasificados se ancla por hash, de forma direccionada por contenido, en el [manifiesto de reproducibilidad](https://github.com/star-ga/hcli/blob/main/docs/reproducibility_manifest.json) (artefacto `openevidence_cache`; 100 % URLs autorizadas, media de 2,27 URLs/par).
- **Aumento de datos**:
  - **Paquete A**: `cache_contraindicated_anchors_x_200 + major_class_x_100 + tacrolimus+voriconazole_x_200 + azathioprine+febuxostat_x_200 (anti-FN) + 9 BOOST_KEYS @200x`
  - **Paquete B**: `MAJOR_KEYS @50x (4) + NTI_OVERVETO_KEYS @30x (6) + SERIOUS_TRUE_MISS_KEYS @30x (5) + MODERATE_MISS_KEYS @30x (2)`, entrenado EXCLUSIVAMENTE sobre las 95 muestras no contraindicadas
- **Iteración de entrenamiento**:
  - A: `iter-242-path-a-v8-h256` (superó el techo arquitectónico de v7 en h=128 al duplicar las ocultas a 256)
  - B: `iter-421-path-b-bitnet-b-specialist`

Tras el entrenamiento, los pesos se exportan a JSON (ternarios convertidos a int8, sesgos como int32 Q16.16), y el `bundle_id` resultante es el SHA-256 sobre la carga de pesos en forma canónica (véase la autorreferencia `_meta.bundle_id` en cada fichero de pesos).

---

## Limitaciones honestas

1. **Cobertura de fármacos**: el corpus de entrenamiento v1 cubre ~3247 pares entre 224 fármacos — aproximadamente el 0,2 % de la base de datos completa de interacciones de DrugBank. Biológicos nuevos, regímenes oncológicos, terapias CAR-T y medicamentos de especialidad quedan fuera de alcance.
2. **Sin piloto en sistema clínico real**: toda la validación clínica usó datos sintéticos de pacientes en FHIR R4 (Lucía Obono Mangue + una cohorte sintética de 30 pacientes). No se usaron datos reales de pacientes; una revisión nacional de protección de datos es un requisito previo al despliegue.
3. **Sin validación clínica todavía**: la primitiva de reproducibilidad Q16.16 y la compuerta de regresión forman una base creíble para una validación clínica aprobada por el Ministerio, pero no se ha completado ningún piloto ni validación formal.
4. **Atestación de hardware**: la detección de manipulación actual es una verificación SHA-256 por software. Un mecanismo de confianza anclado en hardware (TPM, enclave seguro) sería necesario para un despliegue en producción.
5. **Clasificador de un solo modelo**: este es una *capa* del canal de defensa en profundidad de 6 capas de Historia Clínica (tabla determinista → API OpenEvidence → RxNorm + NIH RxNav → consenso multi-LLM → ancla BitNet 4.5 → síntesis LLM → compuerta de abstención). Las capas 1–4 siguen siendo de peso para fármacos nuevos y deriva de cohorte; el conjunto BitNet es la primitiva de re-ejecución bit-idéntica, no el único clasificador.

---

## Licencia

[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) — igual que Historia Clínica y mind-mem, con concesión explícita de patente (§ 3) para equipos de adquisición hospitalaria y regulatorios.

```
Copyright 2026 STARGA Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0
```

---

## Cita

Si usa este modelo en investigación o producción, cite el artículo de base de BitNet b1.58 más el despliegue de Historia Clínica:

```bibtex
@misc{ma2024bitnet,
  title={The Era of 1-bit LLMs: All Large Language Models are in 1.58 Bits},
  author={Ma, Shuming and Wang, Hongyu and Ma, Lingxiao and Wang, Lei and Wang, Wenhui and
          Huang, Shaohan and Dong, Li and Wang, Ruiping and Xue, Jilong and Wei, Furu},
  year={2024},
  eprint={2402.17764},
  archivePrefix={arXiv},
  primaryClass={cs.CL}
}

@misc{starga2026hcli,
  title={Historia Clínica: Decisiones Clínicas Bit-idénticas para IA Sanitaria},
  author={STARGA Inc.},
  year={2026},
  url={https://github.com/star-ga/hcli}
}
```

---

## Referencias cruzadas

- **Repositorio en GitHub**: [star-ga/hcli](https://github.com/star-ga/hcli)
- **Demo en vivo**: [hcli.pages.dev](https://hcli.pages.dev)
- **Capa de memoria subyacente**: [mind-mem en PyPI](https://pypi.org/project/mind-mem/) (v4.0.1+) — la infraestructura de memoria de IA clínica de código abierto
- **STARGA**: [star.ga](https://star.ga) — tecnología Mind Cognitive Kernel™ (patente en trámite)

---

*Historia Clínica — STARGA, Inc. · Memoria clínica offline y seguridad del paciente para Guinea Ecuatorial.*