Metadata-Version: 2.4
Name: holobit-sdk
Version: 1.2.0
Summary: SDK para arquitectura holográfica avanzada
Author-email: Adolfo González Hernández <adolfogonzal@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Alphonsus411/holobit_SDK
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Provides-Extra: api
Requires-Dist: azure-identity; extra == "api"
Requires-Dist: azure-mgmt-batch; extra == "api"
Requires-Dist: bcrypt; extra == "api"
Requires-Dist: boto3; extra == "api"
Requires-Dist: fastapi; extra == "api"
Requires-Dist: google-cloud-compute; extra == "api"
Requires-Dist: grpcio<1.82.0,>=1.81.0; extra == "api"
Requires-Dist: protobuf<7.0.0,>=6.33.5; extra == "api"
Requires-Dist: uvicorn; extra == "api"
Provides-Extra: cython
Requires-Dist: Cython>=0.29.36; extra == "cython"
Provides-Extra: api-codegen
Requires-Dist: grpcio-tools==1.81.0; extra == "api-codegen"
Provides-Extra: pure
Provides-Extra: qiskit
Requires-Dist: qiskit; extra == "qiskit"
Provides-Extra: cirq
Requires-Dist: cirq; extra == "cirq"
Provides-Extra: qutip
Requires-Dist: qutip; extra == "qutip"
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk; extra == "braket"
Requires-Dist: amazon-braket-default-simulator; extra == "braket"
Provides-Extra: pennylane
Requires-Dist: pennylane; extra == "pennylane"
Provides-Extra: aws
Requires-Dist: boto3; extra == "aws"
Provides-Extra: azure
Requires-Dist: azure-identity; extra == "azure"
Requires-Dist: azure-mgmt-batch; extra == "azure"
Provides-Extra: gcp
Requires-Dist: google-cloud-compute; extra == "gcp"
Provides-Extra: rate-limit-redis
Requires-Dist: redis; extra == "rate-limit-redis"
Provides-Extra: ml
Requires-Dist: pandas; extra == "ml"
Requires-Dist: scikit-learn; extra == "ml"
Requires-Dist: torch; extra == "ml"
Provides-Extra: tensor
Requires-Dist: numpy; extra == "tensor"
Provides-Extra: itensor
Requires-Dist: itensors; extra == "itensor"
Provides-Extra: tensor-numpy
Requires-Dist: numpy; extra == "tensor-numpy"
Provides-Extra: tensor-torch
Requires-Dist: torch; extra == "tensor-torch"
Provides-Extra: tensor-tensorflow
Requires-Dist: tensorflow; extra == "tensor-tensorflow"
Provides-Extra: tensor-jax
Requires-Dist: jax; extra == "tensor-jax"
Provides-Extra: tensor-itensors
Requires-Dist: itensors; extra == "tensor-itensors"
Provides-Extra: tensor-all
Requires-Dist: torch; extra == "tensor-all"
Requires-Dist: tensorflow; extra == "tensor-all"
Requires-Dist: jax; extra == "tensor-all"
Requires-Dist: itensors; extra == "tensor-all"
Dynamic: license-file


# Holobit SDK - Documentación Oficial

## 📌 Introducción
El **Holobit SDK** es un kit de desarrollo diseñado para la transpilación y ejecución de código holográfico cuántico. Su arquitectura multinivel permite trabajar con diferentes niveles de abstracción, optimizando el rendimiento en múltiples arquitecturas de hardware.

## 🔹 Características Principales
- **Transpilador Cuántico Holográfico**: Convierte código HoloLang en código máquina optimizado para arquitecturas x86, ARM y RISC-V.
- **Backends C/C++, Rust y Go**: Traducen programas HoloLang a código clásico en C, C++, Rust o Go, permitiendo un flujo tradicional de compilación.
- **Optimización Avanzada**: Reduce instrucciones redundantes y reutiliza registros para maximizar la eficiencia.
- **Ejecución Multinivel**: Soporte para bajo, medio y alto nivel en la programación holográfica.
- **Compatibilidad con Múltiples Arquitecturas**: x86, ARM y RISC-V.
- **Integración con frameworks cuánticos**: Qiskit, PennyLane, Cirq, AWS Braket y QuTiP.

## 📥 Instalación
Para instalar el SDK Holobit, sigue los siguientes pasos:

### 🔹 Requisitos Previos
- **Python >=3.10** (versión mínima recomendada)
- **pip** actualizado
- **Git (opcional, pero recomendado)**

### 🔹 Instalación desde GitHub
```bash
# Clonar el repositorio
git clone https://github.com/Alphonsus411/holobit_SDK.git
cd holobit_SDK

# Instalar dependencias
pip install -r requirements_optional.txt
# Este archivo solo incluye herramientas de documentación, pruebas y utilidades
# generales; las bibliotecas destacadas en esta guía (pandas, scikit-learn,
# torch, FastAPI, gRPC y los SDKs de AWS/Azure/GCP) se instalan a través de los
# extras indicados más abajo.
# Para tareas de desarrollo instala también las dependencias de
# linting y cobertura
pip install -r requirements_dev.txt

# Para habilitar la API REST basada en FastAPI instala el extra dedicado
pip install .[api]
# Incluye FastAPI, bcrypt, uvicorn, grpcio>=1.81.0,<1.82.0,
# protobuf>=6.33.5,<7.0.0 y los SDK de AWS/Azure/GCP utilizados por los
# backends (`boto3`, `azure-identity`, `azure-mgmt-batch`,
# `google-cloud-compute`). Las herramientas de generación gRPC
# (`grpcio-tools==1.81.0`) se instalan solo con el extra .[api-codegen]
# o requirements_dev.txt. Como alternativa,
# puedes instalarlo desde el archivo
# requirements_api.txt para entornos donde prefieras fijar el conjunto de
# dependencias:
# pip install -r requirements_api.txt
# Si ejecutas la API sin estos SDKs opcionales, los endpoints seguirán
# inicializando correctamente pero cualquier backend que los requiera devolverá
# un error 502 indicando la dependencia faltante.

# Para habilitar el puente de datos con pandas y frameworks de ML instala el extra `[ml]`
pip install .[ml]
# Incluye `pandas`, `scikit-learn` y `torch`, requeridas por
# `holobit_sdk.api.python_bridge` para cargar datasets, tensores y holobits
# desde DataFrames o arreglos NumPy.
```

> Nota: aunque el repositorio en disco se llama `holobit_SDK`, el nombre del paquete instalable es `holobit-sdk`.

### 🔹 Instalación con o sin compilación
- **Ruta compilada (recomendada cuando hay compilador disponible)**
  ```bash
  pip install .[cython]
  ```
  Esto instalará `Cython` como dependencia extra, habilitará la compilación de
  los módulos `.pyx` y respetará el `language_level=3`. Para activar el
  perfilado de Cython (directivas `profile=True` y `linetrace=True`), exporta
  `HOLOBIT_CYTHON_PROFILE=1` antes de instalar.

- **Ruta en Python puro (sin compilador o sin Cython)**
  ```bash
  HOLOBIT_DISABLE_CYTHON=1 pip install .[pure]
  ```
  El flujo ignora la compilación y carga automáticamente las variantes `_py` o
  las implementaciones `.py` equivalentes.

### 🔹 Extensiones Cython y ruta de instalación
El SDK incluye extensiones Cython para acelerar operaciones críticas. Durante
la instalación con `pip install .[cython]` se compilan explícitamente los
módulos `holobit_sdk/assembler/virtual_machine.pyx` y
`holobit_sdk/assembler/parser.pyx`, además de los módulos de núcleo en
`holobit_sdk/core/*.pyx` y los de `holobit_sdk/quantum_holocron/**/*.pyx`, con
las optimizaciones `language_level=3`, `boundscheck=False` y `cdivision=True`.
Si se habilita `HOLOBIT_CYTHON_PROFILE=1`, también se activan las directivas
`profile` y `linetrace` para facilitar el análisis de rendimiento.

- Si hay un compilador disponible, la rueda resultante incluirá también las
  fuentes `.pxd` y los ficheros C generados (`*.c`) para facilitar la
  redistribución.
- Si el entorno no cuenta con compilador, el proceso de instalación continúa y
  el SDK utiliza automáticamente las implementaciones en Python puro sin
  modificar la API pública.
- Para forzar el modo sin compilación puedes definir
  `HOLOBIT_DISABLE_CYTHON=1 pip install .`, lo cual activa el *fallback* sin
  necesidad de eliminar dependencias de compilación.

La API se mantiene estable tanto en la versión compilada como en la de Python
puro; la diferencia está únicamente en el rendimiento.

### 🔎 Verificación rápida de dependencias por método
- `pip install -r requirements_optional.txt`: instala utilidades para pruebas,
  documentación y soporte de publicación (`pytest`, `matplotlib`, `rich`,
  `twine`, `qiskit`, `pennylane`, entre otros). No incluye `pandas`,
  `scikit-learn`, `torch`, FastAPI ni los SDKs cloud.
- `pip install -r requirements_dev.txt`: añade herramientas de linting,
  cobertura y desarrollo local (por ejemplo, `ruff`, `coverage`, `mypy`).
- `pip install .`: instala el SDK base sin extras opcionales.
- `pip install .[ml]`: añade `pandas`, `scikit-learn` y `torch` para el puente
  de datos.
- `pip install .[api]` o `pip install -r requirements_api.txt`: instala la pila
  runtime de servicios (FastAPI, `uvicorn`, `grpcio>=1.81.0,<1.82.0`,
  `protobuf>=6.33.5,<7.0.0`, `bcrypt`) y los SDKs de AWS, Azure y GCP (`boto3`,
  `azure-identity`, `azure-mgmt-batch`, `google-cloud-compute`). Para regenerar
  los stubs protobuf/gRPC instala `pip install .[api-codegen]` o
  `pip install -r requirements_dev.txt`, que incluyen `grpcio-tools==1.81.0`.
- Extras individuales `.[aws]`, `.[azure]` o `.[gcp]`: instalan únicamente el
  SDK del proveedor correspondiente cuando no necesitas el resto de la pila de
  servicios.

### 🔹 Pruebas de consistencia y rendimiento con Cython
Se añaden pruebas parametrizadas para validar que las rutas de Cython y las de
Python puro producen los mismos resultados numéricos en `interactions` y
`operations`, incluso al forzar `HOLOBIT_DISABLE_CYTHON`.

- Consistencia de API en ambos modos:
  ```bash
  # Ejecuta las pruebas sin incluir los benchmarks opcionales
  pytest tests/test_interactions_operations_cython_toggle.py -m "not performance"
  ```
- Benchmarks opcionales (marcados como `performance` y `slow`):
  ```bash
  # Compara la versión compilada frente al fallback en Python
  pytest -m "performance" tests/test_interactions_operations_cython_toggle.py
  ```

- Casos adicionales para `GeneticOptimizer` y `operations.entrelazar`:
  ```bash
  # Verifica consistencia entre Cython y Python forzando HOLOBIT_DISABLE_CYTHON
  pytest tests/test_genetic_optimizer_operations_cython.py -m "not benchmark"

  # Ejecuta los microbenchmarks con pytest-benchmark (requiere tener instalado
  # el plugin `pytest-benchmark` y las extensiones Cython)
  pytest -m "benchmark and slow" tests/test_genetic_optimizer_operations_cython.py
  ```

  Estos benchmarks calculan el tiempo medio de `GeneticOptimizer.run` y de
  `operations.entrelazar` en modos compilado y Python puro. Las aserciones
  esperan que la versión Cython mantenga al menos un 10 % de mejora. Si el
  plugin de benchmarks o las extensiones compiladas no están disponibles, las
  pruebas se marcan como `xfail` para no bloquear la suite.

Los benchmarks usan `pytest-benchmark` y exigen que la versión compilada sea al
menos un 10 % más rápida que la implementación en Python puro. En CI pueden
habilitarse de forma opcional ejecutando los marcadores `performance`/`slow`.

### 📊 Resultados recientes (compilado vs. Python puro)

| Modo | Comando | Resultado |
| --- | --- | --- |
| Cython habilitado | `pytest tests/test_interactions_operations_cython_toggle.py -m "not performance"` | ✅ 4 pruebas pasaron, 1 deseleccionada (1.06 s). |
| Cython habilitado | `pytest tests/test_interactions_operations_cython_toggle.py -m performance` | ⚠️ 1 prueba marcada como `skipped`; el resto deseleccionadas (0.46 s). |
| Cython habilitado | `pytest tests/test_interactions_operations_cython_toggle.py -m slow` | ⚠️ 1 prueba marcada como `skipped`; el resto deseleccionadas (0.45 s). |
| Python puro (`HOLOBIT_DISABLE_CYTHON=1`) | `pytest tests/test_interactions_operations_cython_toggle.py -m "not performance"` | ✅ 4 pruebas pasaron, 1 deseleccionada (0.49 s). |
| Python puro (`HOLOBIT_DISABLE_CYTHON=1`) | `pytest tests/test_interactions_operations_cython_toggle.py -m performance` | ⚠️ 1 prueba marcada como `skipped`; el resto deseleccionadas (0.51 s). |
| Python puro (`HOLOBIT_DISABLE_CYTHON=1`) | `pytest tests/test_interactions_operations_cython_toggle.py -m slow` | ⚠️ 1 prueba marcada como `skipped`; el resto deseleccionadas (0.46 s). |

> Notas:
> - Los `skips` en los marcadores `performance`/`slow` son esperados: los
>   benchmarks están decorados para omitirse automáticamente cuando no se
>   cumplen los requisitos opcionales de entorno.
> - La suite de consistencia (`not performance`) es estable en ambos modos; la
>   ruta en Python puro resulta ligeramente más rápida en este entorno
>   controlado, aunque sin diferencias funcionales.

## 🔬 Perfilado de hotspots para priorizar Cython
Se incluye un script utilitario para identificar las rutas con mayor tiempo
acumulado y generar un archivo intermedio para el proceso de build.

1. Ejecuta el perfilador desde la raíz del repositorio:
   ```bash
   python tools/profile_hotspots.py --limit 20 --min-time 0.002
   ```
   Variables de entorno útiles para activar o ajustar el perfilado sin tocar el
   código:
   - `HOLOBIT_PROFILE_SEED`: semilla para las cargas pseudoaleatorias.
   - `HOLOBIT_PROFILE_TRANSPILE_ITERATIONS`: repeticiones del bucle de
     transpilación.
   - `HOLOBIT_PROFILE_ENTANGLE_SIZE`: tamaño de los vectores de holobits en los
     experimentos de entrelazamiento.
   - `HOLOBIT_PROFILE_POPULATION` y `HOLOBIT_PROFILE_GENERATIONS`: parámetros
     del experimento genético fractal.
   - `HOLOBIT_PROFILE_DATASET`: ruta a un archivo de instrucciones sintéticas
     (texto plano) que sustituye al dataset embebido usado por el workload de
     transpilación; las líneas vacías y las que empiezan por `#` se ignoran y se
     barajan con la semilla indicada.
   - `--limit`, `--min-time` y `--output` controlan respectivamente la cantidad
     de entradas, el umbral de tiempo acumulado y la ruta de salida
     (predeterminada: `build/cython_targets.json`).

2. La consola mostrará el resumen de `pstats` ordenado por tiempo acumulado y
   la lista de rutas candidatas. Cada entrada se imprime como
   `ruta:línea (función) -> tiempo_en_segundos` para que puedas inspeccionar
   rápidamente qué módulos son los más costosos.

3. El archivo `build/cython_targets.json` incluye los mismos candidatos en
   formato estructurado (propiedades `candidates` y `source_paths`).
   - `_load_cython_sources` consume el campo `source_paths` para decidir qué
     módulos se intentarán compilar con Cython.
   - Para forzar la compilación de un módulo puedes añadir manualmente su ruta
     relativa (por ejemplo `holobit_sdk/core/holobit.pyx` o su par `.py`) en
     `source_paths`, incluso si no apareció en el perfilado.
   - Para excluir un módulo basta con eliminarlo de `source_paths`; si lo dejas
     vacío, el proceso de build volverá a explorar `holobit_sdk/**/*.pyx` de
     forma automática.

4. Si quieres ajustar las cargas simuladas, edita las funciones
   `workload_transpiler`, `workload_entanglement` o
   `workload_fractal_genetics` dentro de `tools/profile_hotspots.py` para que
   se parezcan más a tus casos de uso reales.

5. Para regenerar la lista de módulos a compilar con Cython hay un flujo
   simplificado basado en microbenchmarks:
   ```bash
   make profile-cython  # genera build/cython_targets.json con rutas críticas
   make wheel-profiled  # reutiliza el JSON anterior antes de construir la rueda
   ```
   - El script `tools/profile_cython_targets.py` ejecuta cargas cortas de
     evolución fractal y simulación de colisiones usando `cProfile`, ordena las
     funciones por tiempo acumulado y vuelca las rutas de origen en
     `build/cython_targets.json` bajo la clave `source_paths`.
   - `_load_cython_sources` (en `setup.py`) lee ese campo para decidir qué
     extensiones `.pyx` compilar; si el archivo no existe vuelve a explorar el
     árbol completo.
   - En CI puedes ejecutar `make profile-cython` antes del build y subir
     `build/cython_targets.json` como artefacto para mantener sincronizadas las
     rutas calientes entre ramas.

6. Si necesitas desactivar Cython temporalmente exporta la variable de entorno
   `HOLOBIT_DISABLE_CYTHON=1` antes de invocar `pip wheel .` o `python setup.py`;
   el build ignorará cualquier ruta listada en `source_paths` y usará las
   implementaciones en Python puro.

## 🧩 Extras opcionales
### Extra `ml`
El extra `ml` instala `pandas`, `scikit-learn` y `torch`, habilitando el puente
de datos (`holobit_sdk.api.python_bridge`) para convertir DataFrames o arreglos
NumPy en holobits y usarlos en flujos de PyTorch o scikit-learn. Instálalo con:

```bash
pip install .[ml]
```

Si importas funciones de `holobit_sdk.api` sin haber instalado estas
dependencias, se mostrará el mismo mensaje que en tiempo de ejecución:

> holobit_sdk.api.python_bridge requiere las dependencias del extra 'ml' (pandas,
> scikit-learn y torch). Instálalas con `pip install .[ml]` para habilitar las
> utilidades del puente de datos. Consulta la sección 'Extras opcionales' del
> README: https://github.com/Alphonsus411/holobit_SDK#extras-opcionales

### Ejemplo breve de uso
Las utilidades del puente de datos se exponen directamente desde
`holobit_sdk.api`, sin necesidad de importar módulos internos:

```python
import pandas as pd
from holobit_sdk.api import HolobitDataset, holobit_dataloader, holobits_from_dataframe

df = pd.DataFrame(
    {
        "q1": [0.1, 0.2, 0.3],
        "q2": [0.4, 0.5, 0.6],
        "q3": [0.7, 0.8, 0.9],
        "q4": [1.0, 1.1, 1.2],
        "q5": [1.3, 1.4, 1.5],
        "q6": [1.6, 1.7, 1.8],
    }
)

# Convertir el DataFrame en holobits nativos del SDK
holobits = holobits_from_dataframe(df)

# Crear un Dataset compatible con PyTorch y un DataLoader para iterarlo
dataset = HolobitDataset(df)
loader = holobit_dataloader(df, batch_size=2, shuffle=False)
for batch in loader:
    print(batch)
```

## 🚀 Uso del SDK
### 🔹 Ejecución de módulos del paquete
Para evitar errores de importación relativa, los archivos dentro del paquete deben ejecutarse con `python -m holobit_sdk.<ruta>` (por ejemplo `python -m holobit_sdk.quantum_holocron.fractal_evolution`) o invocando `ensure_package_context(globals())` al inicio del script. La alternativa recomendada es instalar el paquete y lanzar los módulos siempre con `python -m` en lugar de rutas relativas. Por ejemplo, el demostrador principal `main.py` puede ejecutarse correctamente tras instalar el SDK con:

```bash
python -m holobit_sdk.quantum_holocron.fractal_evolution --help
# o, si estás en el repositorio, añade ensure_package_context(globals()) y usa python main.py
```

### 🔹 Ejecución directa de módulos con `python archivo.py`
Si necesitas ejecutar un archivo dentro del paquete con `python ruta/al/archivo.py` (en lugar de usar `python -m paquete.modulo`), importa e invoca `ensure_package_context` al inicio para que los imports relativos funcionen como si el módulo se lanzara desde el paquete:

```python
from holobit_sdk.utils.bootstrap import ensure_package_context

ensure_package_context(globals())

from holobit_sdk.core.holobit import Holobit
# resto del código...
```

Este bootstrap ajusta `__package__` y `__spec__` automáticamente, evitando fallos de importación relativa cuando el intérprete no conoce el contexto del paquete. Los entrypoints principales ya lo incluyen por defecto, como la CLI de HoloLang (`holobit_sdk/multi_level/high_level/hololang_cli.py`) y los servicios REST/gRPC (`holobit_sdk/api/service.py` y `holobit_sdk/api/grpc_service.py`), por lo que no necesitas añadirlo si llamas a esas herramientas.

### 🔹 Ejecución de ejemplos o módulos sueltos sin instalar el paquete
Al ejecutar archivos de `examples/` o cualquier módulo individual del repositorio sin haber instalado `holobit-sdk` en el entorno, es necesario bootstrapear manualmente el contexto del paquete. De lo contrario, verás errores `ImportError`/`ModuleNotFoundError` al intentar resolver imports como `from holobit_sdk...` porque el intérprete no conoce la raíz del paquete.

Utiliza el helper `ensure_package_context` definido en `holobit_sdk/utils/bootstrap.py` o, en el caso de los ejemplos, importa el `_bootstrap` ya preparado en `examples/_bootstrap.py`. El patrón mínimo queda así:

```python
from holobit_sdk.utils.bootstrap import ensure_package_context

# Corrige el contexto de paquete para que los imports relativos funcionen
ensure_package_context(globals())

from holobit_sdk.core.holobit import Holobit  # ya no dispara ImportError
```

En los scripts bajo `examples/`, basta con añadir `import examples._bootstrap  # noqa: F401` al inicio para lograr el mismo efecto. Ambas rutas delegan en `holobit_sdk/utils/bootstrap.py`, donde puedes consultar la implementación completa del helper si necesitas adaptarlo.

### 🔹 Transpilación de Código HoloLang
Para transpilar un archivo de código holográfico:
```bash
holobit-transpiler --input archivo.holo --arch x86
```
También puedes ejecutarlo con el módulo de Python:
```bash
python -m holobit_sdk.transpiler.machine_code_transpiler --input archivo.holo --arch x86
```
Esto generará un archivo con el código máquina optimizado para la arquitectura especificada.

### 🔹 Ejemplo de Uso en Código
Puedes importar la clase directamente desde el paquete completo `holobit_sdk.transpiler.machine_code_transpiler`:
```python
from holobit_sdk.transpiler.machine_code_transpiler import MachineCodeTranspiler

transpiler = MachineCodeTranspiler("x86")
instruccion = "ADD H1 H2"
codigo_maquina = transpiler.transpile(instruccion)
print(codigo_maquina)  # ADD H1, H2 ; Registro reutilizado
```

Puedes encontrar más demostraciones en el directorio `examples/`.

### 🔹 Integración con Cirq, Braket y QuTiP
Los holobits pueden ejecutarse en diferentes frameworks cuánticos mediante adaptadores.

```python
from holobit_sdk.quantum_integration import CirqAdapter, BraketAdapter, QutipAdapter

adapter = CirqAdapter()  # También BraketAdapter o QutipAdapter
circuito = adapter.holobit_to_native(holobit)
resultado = adapter.execute(circuito)
```

Cada adaptador convierte el ``Holobit`` a la representación nativa del backend y devuelve el estado resultante tras la ejecución.

#### Instalación de backends opcionales
Para habilitar cada adaptador instala el *extra* correspondiente:

- Cirq: `pip install .[cirq]` para ejecutar holobits en `cirq` mediante `CirqAdapter`.
- Braket: `pip install .[braket]` para usar `BraketAdapter` y simular en `braket` a través de `LocalSimulator`.
- QuTiP: `pip install .[qutip]` para generar y evolucionar estados `qutip.Qobj` con `QutipAdapter`.

Si sólo necesitas el SDK principal puedes instalarlo sin extras (`pip install .`), y añadir después el backend que desees.

## Tensores holográficos opcionales
Los componentes tensoriales del SDK son opcionales para que el paquete base pueda
instalarse y ejecutarse en entornos mínimos. En concreto, son opcionales:

- la capa `holobit_sdk.tensor` y su registro de backends;
- los backends numéricos para redes tensoriales, incluido el backend NumPy;
- la integración iTensor/Julia expuesta por el backend `itensor`;
- las extensiones tensoriales/holográficas de HoloLang que solicitan operaciones
  como `TENSOR_BACKEND`, `TENSOR_COMPRESS`, `TENSOR_PROJECT`, `ITENSOR_RED`,
  `HOLOCRON_TENSOR` u operaciones equivalentes sobre holobits y holocrones.

Para habilitar el backend tensorial basado en NumPy, instala el extra `tensor`:

```bash
pip install .[tensor]
```

Para habilitar la integración con iTensor, instala el extra `itensor`:

```bash
pip install .[itensor]
```

El extra `tensor` añade NumPy para las operaciones tensoriales numéricas, mientras
que `itensor` añade la dependencia `itensors` usada por la integración iTensor.
Instala sólo el backend que vayas a usar; ambos extras son independientes del SDK
base y también pueden combinarse si necesitas las dos rutas:

```bash
pip install .[tensor,itensor]
```

Si una dependencia opcional no está instalada, no es compatible con la plataforma
o falla durante una operación, el sistema tensorial debe degradar de forma segura
a un modo nulo/simbólico o a una operación `TENSOR_NOOP`. Esa degradación evita
que falle la importación del SDK base, conserva el estado del programa y permite
seguir usando las rutas no tensoriales sin convertir NumPy, iTensor o Julia en
requisitos obligatorios. En la práctica, el registro puede seguir anunciando el
backend solicitado, pero la comprobación real se retrasa hasta el momento de uso
y devuelve un diagnóstico o payload simbólico en lugar de interrumpir el flujo
general del SDK.

Los documentos principales para ampliar el comportamiento esperado de los
backends y modelos holográficos están en `docs/`:

- `docs/tensor_backend.md`: contrato común de backends tensoriales, registro y
  fallback seguro;
- `docs/tensor_networks.md`: MPS, MPO, TTN, MERA y modelado de redes
  tensoriales;
- `docs/itensor_backend.md`: detalles de la integración iTensor opcional;
- `docs/internal/tensor_optional_dependencies.md`: política interna de
  dependencias tensoriales opcionales;
- `docs/tensorial_instruction_contract.md`: instrucciones tensoriales y
  degradación `TENSOR_NOOP`;
- `docs/dodecahedral_holobit_model.md`, `docs/fractal_holography.md` y
  `docs/dimensional_density.md`: modelos holográficos y de densidad que pueden
  apoyarse en backends tensoriales.

## 🌐 Servicio Web de Compilación y Ejecución
El SDK incluye un servicio REST basado en FastAPI para compilar y ejecutar Holobits mediante los backends definidos en `holobit_sdk.cloud`.

### Configuración
- `HOLOBIT_PORT`: puerto del servidor (por defecto 8000).
- `HOLOBIT_HOST`: interfaz de escucha del servicio REST (por defecto `127.0.0.1`; usa `0.0.0.0` solo si lo configuras explícitamente).
- `HOLOBIT_BACKEND`: backend cloud a utilizar para REST y gRPC. El default único es `universal`; también puedes fijarlo explícitamente a `aws`, `azure` o `gcp`.
- `HOLOBIT_PROVIDER`: proveedor efectivo cuando `HOLOBIT_BACKEND=universal`. Si no se define, el default documentado es `aws`; también admite `azure` o `gcp`.
- `HOLOBIT_USER` y `HOLOBIT_PASSWORD_HASH`: usuario y hash `bcrypt` de la contraseña.
- `HOLOBIT_TLS_CERT`: ruta al certificado TLS. En producción debe existir.
- `HOLOBIT_TLS_KEY`: ruta a la clave privada TLS. En producción debe existir.
- `HOLOBIT_ENFORCE_HTTPS`: controla la redirección HTTPS solo en modo desarrollo inseguro (`0` por defecto cuando `HOLOBIT_DEV_INSECURE=1`; usa `1` si quieres seguir redirigiendo). En producción HTTPS siempre se fuerza y `HOLOBIT_ENFORCE_HTTPS=0` se ignora.
- `HOLOBIT_DEV_INSECURE`: si vale `1`, permite arranque local sin TLS y desactiva la redirección HTTPS salvo que `HOLOBIT_ENFORCE_HTTPS=1` se configure explícitamente. No debe usarse en producción.
- `HOLOBIT_TRUSTED_PROXY_IPS`: lista separada por comas de proxies desde los que se acepta `X-Forwarded-Proto: https` para considerar segura la petición y emitir HSTS.

### Proveedores de secretos
Los backends `AWSBackend` y `AzureBackend` pueden recibir un objeto que
implemente la interfaz `CredentialsProvider` para obtener credenciales desde
servicios externos como *AWS Secrets Manager* o *Azure Key Vault*.

```python
from holobit_sdk.cloud import AWSBackend, CredentialsProvider

class SecretsManagerProvider(CredentialsProvider):
    def get_credentials(self) -> dict[str, str]:
        return {
            "AWS_ACCESS_KEY_ID": "...",
            "AWS_SECRET_ACCESS_KEY": "...",
        }

backend = AWSBackend(provider=SecretsManagerProvider())
```

Si el proveedor no responde o devuelve credenciales incompletas se registrará
un error y se lanzará `EnvironmentError`.

### Ejecución
```bash
export HOLOBIT_BACKEND=universal
export HOLOBIT_PROVIDER=aws
export HOLOBIT_USER=usuario
export HOLOBIT_PASSWORD_HASH=$(python - <<'PY'
import bcrypt
print(bcrypt.hashpw(b'secreto', bcrypt.gensalt()).decode())
PY
)
python -m holobit_sdk.api.service
```
Los endpoints disponibles son:
- `POST /compile` con el campo `code` que devuelve `job_id`.
- `POST /execute` con `job_id` que devuelve el resultado.
  El identificador `job_id` acepta hasta 256 caracteres.

### 🔐 HTTPS requerido por defecto
El servicio REST fuerza HTTPS por defecto. Para servir TLS directamente debes generar un certificado y una clave
privada. Por ejemplo, con OpenSSL:

```bash
openssl req -x509 -nodes -newkey rsa:4096 -keyout holobit.key -out holobit.crt -days 365 -subj '/CN=localhost'
```

Antes de iniciar el servicio exporta las rutas de ambos archivos:

```bash
export HOLOBIT_TLS_CERT=holobit.crt
export HOLOBIT_TLS_KEY=holobit.key
python -m holobit_sdk.api.service
```

Si `HOLOBIT_TLS_CERT` o `HOLOBIT_TLS_KEY` no están definidos, o apuntan a archivos inexistentes, el arranque directo falla salvo que se active explícitamente `HOLOBIT_DEV_INSECURE=1`. En producción, `HOLOBIT_ENFORCE_HTTPS=0` no desactiva la redirección HTTPS; solo el modo de desarrollo inseguro puede hacerlo.

Si terminas TLS en un proxy inverso, ejecuta el servicio detrás de ese proxy, conserva `HOLOBIT_ENFORCE_HTTPS=1` y configura `HOLOBIT_TRUSTED_PROXY_IPS` con las IPs del proxy para que `X-Forwarded-Proto: https` se trate como una señal confiable y se añada `Strict-Transport-Security`.

Para desarrollo local sin cifrado, el opt-in debe ser explícito:

```bash
export HOLOBIT_DEV_INSECURE=1
python -m holobit_sdk.api.service
```

Consulta `examples/clients` para ver ejemplos de clientes en JavaScript y Go.


## 🔌 Servicio gRPC
Además del servicio REST, el SDK ofrece un servicio gRPC definido en `api/holobit.proto` con los métodos `Compile` y `Execute`.

Para arrancarlo:
```bash
python -m holobit_sdk.api.grpc_service
```
El puerto se puede configurar con la variable `HOLOBIT_PORT` (por defecto 50051). La selección de backend usa las mismas variables que REST: `HOLOBIT_BACKEND` tiene default `universal` y, en ese modo, `HOLOBIT_PROVIDER` tiene default `aws`.

### 🔐 TLS requerido por defecto
El servicio gRPC rechaza el arranque sin TLS salvo opt-in explícito de desarrollo. Para cifrar la comunicación es necesario generar un certificado y una clave
privada. Por ejemplo, con OpenSSL:

```bash
openssl req -x509 -nodes -newkey rsa:4096 -keyout holobit.key -out holobit.crt -days 365 -subj '/CN=localhost'
```

Antes de iniciar el servicio exporta las rutas de ambos archivos:

```bash
export HOLOBIT_TLS_CERT=holobit.crt
export HOLOBIT_TLS_KEY=holobit.key
python -m holobit_sdk.api.grpc_service
```

Si no se definen `HOLOBIT_TLS_CERT` y `HOLOBIT_TLS_KEY`, o si apuntan a archivos inexistentes, el servidor gRPC falla al arrancar. Para desarrollo local sin cifrado, el opt-in debe ser explícito:

```bash
export HOLOBIT_DEV_INSECURE=1
python -m holobit_sdk.api.grpc_service
```

No uses `HOLOBIT_DEV_INSECURE=1` en producción.

### 🔑 Autenticación por token
El servidor exige un token compartido para cada llamada gRPC. Genera un valor
aleatorio y expórtalo antes de iniciar el servicio:

```bash
python - <<'PY'
import secrets; print(secrets.token_hex(32))
PY
export HOLOBIT_GRPC_TOKEN=el_valor_generado
python -m holobit_sdk.api.grpc_service
```

Los clientes autorizados deben incluir el token en la metadata con la clave
`x-holobit-token`:

```python
import os
with grpc.insecure_channel("localhost:50051") as channel:
    stub = holobit_pb2_grpc.HolobitServiceStub(channel)
    metadata = [("x-holobit-token", os.environ["HOLOBIT_GRPC_TOKEN"])]
    stub.Compile(holobit_pb2.CodeRequest(code="..."), metadata=metadata)
```

Las solicitudes sin token o con un valor incorrecto serán rechazadas con el
estado `UNAUTHENTICATED`.

Los stubs Python incluidos en el paquete se generan con `grpcio-tools==1.81.0`, que produce código compatible con `grpcio>=1.81.0,<1.82.0` y `protobuf>=6.33.5,<7.0.0`. Tras instalar `pip install .[api-codegen]` o `pip install -r requirements_dev.txt`, regenera los artefactos versionados desde la raíz del repositorio con:
```bash
python scripts/regenerate_holobit_proto.py
```

El script ejecuta `grpc_tools.protoc` sobre `api/holobit.proto` y conserva la adaptación de importación necesaria para que `holobit_sdk.api.holobit_pb2_grpc` funcione tanto dentro del paquete como en clientes externos generados.

Los clientes en otros lenguajes pueden generarse compilando el archivo `.proto` correspondiente. Por ejemplo, para un cliente Python externo:
```bash
python -m grpc_tools.protoc -I api --python_out=. --grpc_python_out=. api/holobit.proto
```
En C++, Java, Go u otros lenguajes basta con ejecutar `protoc` con el plugin gRPC adecuado y apuntar al mismo archivo `holobit.proto`.


### 🔹 Flujo HoloLang → C/C++/Rust/Go → ensamblador
Además del código máquina directo, el compilador permite generar código C, C++, Rust o Go a partir de un programa HoloLang, manteniendo un flujo clásico de compilación:
```python
from holobit_sdk.multi_level.high_level.compiler import HoloLangCompiler

compiler = HoloLangCompiler("rust")  # también "go", "c" o "cpp"
programa = "IMPRIMIR A"
codigo = compiler.compilar_y_ejecutar(programa)
print(codigo)
```
El resultado puede compilarse con `gcc`/`clang`, `rustc` o `go build` para producir ensamblador u objetos binarios.

### 🔹 Ejecución de HoloLang desde la línea de comandos
Puedes ejecutar código HoloLang directamente con el comando `hololang`:
```bash
hololang -c "CREAR H1 (0.1, 0.2, 0.3)" -c "IMPRIMIR H1"
```
O bien pasar un archivo con varias instrucciones y especificar el backend deseado:
```bash
hololang --file programa.holo --arch rust
```
Esto mostrará por pantalla el resultado de cada línea procesada.

### 🔹 Máquina Virtual del Ensamblador
El módulo `assembler.virtual_machine` permite ejecutar instrucciones holográficas en un entorno controlado.
```python
from holobit_sdk.assembler.virtual_machine import AssemblerVM

vm = AssemblerVM()
programa = ["CREAR Q1 (0.1, 0.2, 0.3)", "CREAR Q2 (0.4, 0.5, 0.6)", "CREAR H1 {Q1, Q2}", "ROT H1 z 90"]
vm.run_program(programa)
```
Las instrucciones del ASIIC pueden escribirse con cualquier combinación de mayúsculas y minúsculas. Por ejemplo, `rotar`, `Rotar` y `ROTAR` se interpretan de la misma manera.
#### 🧩 Macros y alias
El parser incluye un preprocesador que reconoce directivas `#macro` y `#endmacro` para definir plantillas reutilizables:
```asm
#macro CREAR_ROT nombre x y z
CREAR {nombre} ({x}, {y}, {z})
ROTAR {nombre} z 90
#endmacro

CREAR_ROT H1 0.1 0.2 0.3
```
Además, la máquina virtual carga alias al iniciar; por ejemplo `ROTAR` es un alias de `ROT`.
También se incluyen alias como `MEASURE` → `MEDIR`, `ENTRELAZAR` → `ENTANGLE` y `SUPERPOSICION` → `SUPERPOS`.
Las macros pueden eliminarse en tiempo de ejecución mediante `assembler.macros.remove_macro("CREAR_ROT")`.
### 🔹 Instrucciones cuánticas esenciales
Las últimas versiones del lenguaje incluyen operaciones de nivel cuántico que
pueden combinarse con macros y con la máquina virtual:

- **SUPERPOS** *(alias: `SUPERPOSICION`)*: coloca un Holobit o qubit en superposición.
  ```asm
  CREAR Q1 (0.1, 0.2, 0.3)
  SUPERPOS Q1
  ```
- **MEDIR** *(alias: `MEASURE`)*: colapsa el estado y almacena el resultado en `parser.measurements`.
  ```asm
  MEDIR Q1
  ```
- **ENTANGLE** *(alias: `ENTRELAZAR`)*: entrelaza dos registros, propagando el colapso de uno sobre el otro.
  ```asm
  ENTANGLE Q1 Q2
  ```
- **DECOHERENCIA**: simula la pérdida de coherencia devolviendo un estado clásico aleatorio.
  ```asm
  DECOHERENCIA Q1
  ```

### 🔹 Manejo de grupos
Los Holobits pueden organizarse en grupos lógicos para operar sobre varios
elementos simultáneamente:

```asm
CREAR H1 {Q1, Q2}
CREAR H2 {Q3, Q4}
GRUPO G1 {H1, H2}
```

### 🔹 Persistencia del estado del Holocron
Es posible guardar y restaurar el conjunto completo de holobits y grupos:

```holo
GUARDAR_ESTADO inicial
# ... realizar operaciones ...
RESTABLECER_ESTADO inicial
```

Estas instrucciones utilizan internamente ``Holocron.save_state`` y
``Holocron.restore_state`` para serializar y recuperar el contenido.

### 🔹 Estructuras de control
El ensamblador incorpora instrucciones de alto nivel para controlar el flujo:

- `SI` / `SINO` / `FIN`
- `MIENTRAS` / `FIN`
- `PARA` / `FIN`
- `CASO` / `CUANDO` / `OTRO` / `FINCASO`

```asm
MEDIR H1
SI H1
    ROT H1 z 90
SINO
    ROT H1 z 180
FIN

PARA 3
    ROT H1 x 30
FIN

CASO H1
    CUANDO 0
        ROT H1 y 45
    CUANDO 1
        ROT H1 y 90
    OTRO
        ROT H1 y 180
FINCASO
```

En HoloLang también pueden emplearse llaves para definir bloques con
condicionales y estructuras de casos:

```holo
SI condicion {
    INSTRUCCION_A
} SINO {
    INSTRUCCION_B
}

CASO expresion {
    CUANDO 1 {
        ACCION_1
    }
    CUANDO 2 {
        ACCION_2
    }
    OTRO {
        ACCION_DEFECTO
    }
} FINCASO
```

### 🔹 Simulación de Holobits
El simulador `HologramSimulator` permite mover y rotar Holobits paso a paso,
y visualizar cada estado en 3D.
```python
from holobit_sdk.quantum_holocron.core.hologram_simulator import HologramSimulator
sim = HologramSimulator()
pasos = [{"traslacion": (0.1, 0, 0), "rotacion": ("z", 15)}]
sim.animate(holobit, pasos)
```
### 🔹 Interacciones básicas
El módulo `holobit_sdk.core.interactions` ofrece funciones sencillas para
modificar el estado de los Holobits:

- `confinar_quarks(holobit, limite)`: limita la posición de cada quark al
  rango ``[-limite, limite]``.
- `cambiar_spin(holobit, nuevo_spin)`: ajusta el valor del *spin* del Holobit.
- `sincronizar_spin(holobits)`: iguala el *spin* de un grupo de Holobits al
  promedio del conjunto.

```python
from holobit_sdk.core import interactions

interactions.confinar_quarks(holobit, limite=0.5)
interactions.cambiar_spin(holobit, 1.0)
```
## 🔬 Arquitectura Interna del SDK
El SDK Holobit está estructurado en varios niveles:
1. **Nivel Bajo**: Manejo directo de registros y memoria holográfica.
2. **Nivel Medio**: Procesamiento cuántico holográfico.
3. **Nivel Alto**: Lenguaje de programación HoloLang y compilador asociado.

## 📖 Referencia Técnica
- **Módulo `transpiler`**: Contiene el transpilador de código holográfico a código máquina.
- **Módulo `execution`**: Maneja la ejecución de código transpilado en arquitecturas objetivo.
- **Módulo `debugger`**: Herramientas de depuración y análisis de código transpilado.

## 📄 Ejemplos de Código
Los ejemplos del SDK se encuentran en el directorio `examples/` y pueden
ejecutarse directamente con Python. Por ejemplo:
```bash
python examples/holobit_demo.py
python examples/hololang_compiler.py
python examples/hologram_simulation.py
python examples/new_instructions_demo.py
```
Cada script muestra una funcionalidad concreta del SDK. También puedes
utilizar el transpilador de forma manual:
```bash
holobit-transpiler --input ejemplo.holo --arch x86
```
O bien con el módulo de Python:
```bash
python -m holobit_sdk.transpiler.machine_code_transpiler --input ejemplo.holo --arch x86
```

### Expresiones ampliadas con `SIQ`
La instrucción `SIQ` permite evaluar los resultados de medición mediante
expresiones complejas combinando operadores aritméticos y lógicos.
Además de comparaciones simples entre un grupo y un valor, ahora es
posible evaluar **expresiones completas** utilizando los resultados de
medición disponibles:

```hololang
SIQ (G1 + G2) > 1 {
    CREAR A (1)
} ELSEQ {
    CREAR B (1)
}
```
Los operadores admitidos incluyen `==`, `!=`, `<`, `>`, `<=` y `>=`, así
como operaciones aritméticas dentro de la expresión. Asimismo, `SIQ`
soporta combinaciones lógicas mediante `AND`, `OR` y `NOT`, e incluso
agrupar subexpresiones con paréntesis para un control detallado.

### DESENTANGLE
La instrucción `DESENTANGLE` revierte el entrelazamiento entre dos
Holobits, restaurando su independencia y evitando colapsos propagados.
Es especialmente útil tras mediciones o manipulaciones intensivas.

```hololang
ENTANGLE Q1 Q2
DESENTANGLE Q1 Q2
```

### Operaciones adicionales con `CANALIZAR`
`CANALIZAR` abre un flujo de control sobre uno o varios Holobits donde se
habilitan operaciones avanzadas como `AMPLIFICAR`, `FILTRAR` y
`REFRACTAR`, las cuales no están disponibles fuera de este contexto.

```hololang
CANALIZAR H1 {
    AMPLIFICAR H1 2;
    FILTRAR H1 z>0;
}
```

### Sintaxis para secuencias de operaciones
Varias instrucciones pueden encadenarse en una sola línea utilizando el
separador `;`. Esto facilita describir **secuencias de operaciones** que
el intérprete ejecutará de izquierda a derecha.

```hololang
CREAR Q1 (0.1,0.2,0.3); ROTAR Q1 z 90; MEDIR Q1
```

### Ejemplo combinado según el Holocron Cuántico
El siguiente fragmento muestra cómo integrar estas características para
mantener la coherencia indicada por el **Holocron Cuántico**:

```hololang
CREAR Q1 (0.1,0.2,0.3); CREAR Q2 (0.4,0.5,0.6)
ENTANGLE Q1 Q2
CANALIZAR {Q1,Q2} {
    AMPLIFICAR Q1 2;
    FILTRAR Q2 x>0;
}
SIQ (MEDIR Q1 + MEDIR Q2) >= 1 AND NOT(MEDIR Q1 == 0) {
    DESENTANGLE Q1 Q2;
    CREAR H1 {Q1, Q2};
} ELSEQ {
    ROTAR Q1 y 45;
}
```

## 🌿 Fractales Holográficos

### Concepto, jerarquías de densidad y reglas morfométricas
Un **fractal holográfico** describe la distribución jerárquica de densidades dentro de un *Holocron*. Cada nivel genera subniveles con una densidad proporcional que sigue reglas morfométricas, permitiendo explorar la estructura cuántica con una escala autosimilar.

### Uso desde Python
```python
from holobit_sdk.quantum_holocron.core.holocron import Holocron
from holobit_sdk.quantum_holocron.fractal import Fractal
from holobit_sdk.core.holobit import Holobit
from holobit_sdk.core.quark import Quark
from holobit_sdk.visualization.fractal_plot import visualizar_fractal

def _crear_holocron():
    holo = Holocron()
    for i in range(10):
        q = [Quark(0, 0, 0) for _ in range(6)]
        aq = [Quark(0, 0, 0) for _ in range(6)]
        holo.add_holobit(f"hb{i}", Holobit(q, aq, spin=i))
    return holo

holo = _crear_holocron()
fractal = Fractal(holo)
fractal.hierarquia_superior = 20
fractal.generar()
fig, axes = visualizar_fractal(lambda **_: list(fractal.densidades.values()))
```

### Uso desde Hololang
```hololang
CREAR_FRACTAL F1 (densidad_max=20)
GRAFICAR_FRACTAL F1
```
### Sintaxis de las nuevas instrucciones
El SDK incorpora instrucciones específicas para trabajar con fractales multidimensionales:

- `CREAR_FRACTAL <id> (densidad_max=<N>, dimensiones=<D>)`: define un fractal con densidad máxima `N` y `D` dimensiones.
- `SIMULAR_FRACTAL <id> pasos=<P>`: ejecuta `P` iteraciones sobre el fractal existente.
- `GRAFICAR_FRACTAL <id> modo=<modo>`: muestra el fractal en modo `2D`, `3D` o `animado`.

Ejemplo completo:
```hololang
CREAR_FRACTAL F1 (densidad_max=20, dimensiones=4)
SIMULAR_FRACTAL F1 pasos=10
GRAFICAR_FRACTAL F1 modo=animado
```
## 📝 Notas sobre archivos binarios
Los documentos de arquitectura se mantienen en PDF, pero debido a que los archivos binarios dificultan las revisiones, se evita editarlos directamente en el repositorio. Las actualizaciones deben registrarse en formatos de texto o imágenes vectoriales, generando los PDFs fuera del control de versiones.

## 📦 Despliegue y Distribución
El SDK Holobit será empaquetado y distribuido a través de **GitHub Releases** y **PyPI**.

### 🔹 Construcción del Paquete
```bash
python setup.py sdist bdist_wheel
```

### 🔹 Publicación en PyPI
```bash
pip install twine

# Subir el paquete
python -m twine upload dist/*
```

## ➕ Añadir nuevos backends cuánticos
Para integrar un nuevo backend cuántico en el SDK:
1. Crea una clase en ``holobit_sdk/quantum_integration`` que herede de ``QuantumAdapter``.
2. Implementa el método ``holobit_to_native`` para traducir un ``Holobit`` al formato del backend.
3. Implementa ``execute`` para ejecutar la representación nativa y devolver su estado.
4. Añade pruebas correspondientes en ``holobit_sdk/quantum_integration/tests``.

## ☁️ Backends en la Nube
El SDK incluye conectores simples para ejecutar trabajos Holobit en servicios de **AWS**, **Azure** y **Google Cloud Platform**.

### Instalación de dependencias opcionales
Para cada proveedor instala el extra correspondiente:
```bash
# AWS
pip install .[aws]
# Azure
pip install .[azure]
# GCP
pip install .[gcp]
```

### Variables de entorno requeridas
- **AWS**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
- **Azure**: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`
- **GCP**: `GOOGLE_APPLICATION_CREDENTIALS` (ruta al archivo de credenciales)

Ejemplo de uso con AWS:
```python
from holobit_sdk.cloud.aws import CloudBackend
backend = CloudBackend()
job_id = backend.submit_job({"payload": "..."})
backend.execute_job(job_id)
```

## 🧩 Extensiones tensoriales/holográficas de HoloLang
Las extensiones tensoriales/holográficas añaden instrucciones declarativas para
consultar o seleccionar el backend tensorial y para operar sobre holobits,
holocrones y densidades fractales. Estas instrucciones son aditivas: no
modifican la semántica de HoloLang existente y se normalizan antes de llegar a
la VM o al transpilador de máquina.

### Sintaxis canónica
| Instrucción | Forma documentada | Descripción |
| --- | --- | --- |
| `TENSOR_BACKEND STATUS` | `TENSOR_BACKEND STATUS` | Consulta el backend tensorial activo o el estado degradado actual. |
| `TENSOR_BACKEND USE null` | `TENSOR_BACKEND USE null` | Fuerza el backend nulo/simbólico para ejecutar de forma determinista sin librerías tensoriales externas. |
| `TENSOR_BACKEND USE numpy` | `TENSOR_BACKEND USE numpy` | Solicita el backend NumPy cuando esté disponible en el entorno. |
| `TENSOR_BACKEND USE itensor` | `TENSOR_BACKEND USE itensor` | Solicita el backend iTensor cuando esté disponible en el entorno. |
| `TENSOR_COMPRESS H1` | `TENSOR_COMPRESS <id>` | Comprime el tensor asociado al identificador indicado; por ejemplo, `H1`. También puede aceptar `RANK <n>` en variantes parametrizadas. |
| `TENSOR_PROJECT H1 DIM 7` | `TENSOR_PROJECT <id> DIM <n>` | Proyecta el tensor identificado a la dimensión indicada. |
| `HOLOBIT_DODECA H1` | `HOLOBIT_DODECA <holobit>` | Construye o etiqueta una representación dodecaédrica del holobit indicado. |
| `HOLOCRON_TENSOR G1` | `HOLOCRON_TENSOR <holocron>` | Expone un holocrón como entidad tensorial operable por el runtime. |
| `FRACTAL_DENSITY G1 DEPTH 5 DIM 10` | `FRACTAL_DENSITY <id> DEPTH <n> DIM <m>` | Calcula o representa la densidad fractal para la profundidad y dimensión indicadas. |

Ejemplo mínimo:
```hololang
TENSOR_BACKEND STATUS
TENSOR_BACKEND USE null
TENSOR_BACKEND USE numpy
TENSOR_BACKEND USE itensor
TENSOR_COMPRESS H1
TENSOR_PROJECT H1 DIM 7
HOLOBIT_DODECA H1
HOLOCRON_TENSOR G1
FRACTAL_DENSITY G1 DEPTH 5 DIM 10
```

### Alias admitidos
Los alias en español se aceptan como azúcar sintáctico y se normalizan a la
forma canónica antes de validarse:

| Alias | Equivalente canónico |
| --- | --- |
| `PROYECTAR_TENSOR H1 DIM 7` | `TENSOR_PROJECT H1 DIM 7` |
| `COMPRIMIR_TENSOR H1` | `TENSOR_COMPRESS H1` |
| `DENSIDAD_FRACTAL G1 DEPTH 5 DIM 10` | `FRACTAL_DENSITY G1 DEPTH 5 DIM 10` |

### Backend tensorial opcional y degradación controlada
El backend tensorial es opcional. El SDK debe poder ejecutarse aunque `numpy` o
`itensor` no estén instalados o no sean compatibles con la arquitectura actual.
En esos casos, las instrucciones tensoriales deben degradar de forma controlada
a un backend nulo/simbólico o a `TENSOR_NOOP`, sin lanzar excepciones no
controladas ni alterar el estado del programa. La respuesta degradada debe
indicar de forma explícita el motivo, la instrucción afectada y el modo de
compatibilidad seguro.

### Compatibilidad con scripts existentes
Los scripts antiguos que usen `CREAR`, `IMPRIMIR`, `SUPERPOS`, `MEDIR`,
`ENTANGLE`, `ENTRELAZAR`, `GUARDAR_ESTADO`, `RESTABLECER_ESTADO`, estructuras
`SI`/`SINO`/`FIN`, loops, macros y grupos mantienen exactamente la misma
semántica. Las extensiones tensoriales/holográficas son compatibles hacia atrás
y solo añaden instrucciones nuevas o alias normalizados.

## 🧪 Pruebas
Para ejecutar las pruebas unitarias del proyecto debes instalar las dependencias opcionales.
La suite completa requiere la librería `qiskit`, incluida en este archivo, para ejecutar las pruebas de integración cuántica:
```bash
pip install -r requirements_optional.txt
```
Si además deseas comprobar la cobertura de código instala las dependencias de desarrollo y ejecuta `coverage`:
```bash
pip install -r requirements_dev.txt
```
Luego ejecuta `flake8` para verificar el estilo y `coverage run` junto con `pytest`:
```bash
flake8
coverage run -m pytest
```
Este repositorio cuenta con un flujo de **Integración Continua** en GitHub Actions que instala estas dependencias y ejecuta las pruebas en cada *push* y *pull request*.

## ♻️ Notas de migración
Para quienes actualicen desde versiones anteriores de **Hololang**:

- Las instrucciones `SUPERPOS`, `MEDIR` y `ENTANGLE` sustituyen a las antiguas `SUP`, `MEASURE` y `ENTRELACE`.
- La gestión de grupos se realiza con `GRUPO` en lugar de las primitivas heredadas `SET`.
- Las estructuras de control `SI`/`SINO`/`FIN` y `MIENTRAS`/`FIN` reemplazan a `IF`/`ELSE`/`END`.
- Las macros deben declararse mediante `#macro` y `#endmacro`; la sintaxis `DEFINE` ya no está soportada.

## 🛠 Mantenimiento y Contribución
Si deseas contribuir al SDK Holobit, puedes hacer un **fork** del repositorio y enviar un **pull request** con tus mejoras.

## 📧 Contacto y Soporte
Para cualquier consulta, reportes de errores o contribuciones, puedes contactarnos en **adolfogonzal@gmail.com** o a través del repositorio en **GitHub**.

---

📌 **Holobit SDK - Computación Cuántica Holográfica para el Futuro** 🚀



## 🧠 Backends tensoriales en runtime (`itensor` → `symbolic`)

El backend `ITensorBackend` ahora permite configurar preferencia en runtime con la variable:

```bash
export HOLOBIT_TENSOR_BACKEND_PREFERENCE="itensor,symbolic"
```

- Orden recomendado por defecto: `itensor,symbolic`.
- Si ITensor falla en una operación concreta, se conmuta de forma local y segura al modo simbólico (`NullTensorBackend`) para evitar estado inconsistente a mitad de ejecución.
- Cada conmutación registra un evento técnico resumido con forma `backend_switch` dentro de `metadata.switch_events`.
- El fallback simbólico marca `metadata.deterministic_fallback=true` para facilitar pruebas reproducibles.

### Compatibilidad y dependencia opcional (importante)

- `itensor` **no es dependencia obligatoria** del SDK.
- Esta ruta no modifica ni reemplaza integraciones cuánticas externas (`Qiskit`,
  `Cirq`, `Braket`, `QuTiP`), que permanecen en `holobit_sdk/quantum_integration`.
- Para contener acoplamientos indirectos en entornos sensibles se exponen flags
  internos no intrusivos:
  - `HOLOBIT_INTERNAL_TENSOR_ITENSOR_RUNTIME_PROBE` (default `true`)
  - `HOLOBIT_INTERNAL_TENSOR_ITENSOR_RUNTIME_OPS` (default `true`)
- Si alguno de estos flags se desactiva, `ITensorBackend` entra en fallback simbólico
  de forma determinística sin convertir `itensor` en requisito duro.

### Límites funcionales del modo simbólico frente a iTensor

- El modo `symbolic` representa operaciones como payloads trazables, no ejecuta álgebra tensorial numérica real de alto rendimiento.
- Operaciones avanzadas (p. ej., contracciones optimizadas por librería externa, kernels especializados o descomposiciones nativas de ITensor) se degradan a representación conceptual/simbólica.
- El modo `symbolic` prioriza estabilidad y trazabilidad, no rendimiento numérico.
