# Despliegue Local/VM

Esta guia documenta el despliegue recomendado para arquitectos: una laptop o VM con Python, acceso a los catalogos/datos del proyecto y ejecucion local de Streamlit. No requiere Docker ni servicios administrados.

## Requisitos

- Python 3.12. En este workspace se valido con Python 3.12.13.
- Acceso de red si se van a descargar catalogos AWS/OCI actualizados.
- Ollama opcional para funciones LLM de mapeo o respuestas naturales.
- Twilio opcional para WhatsApp.
- Puerto local disponible para Streamlit, normalmente `8501`.
- Puerto local disponible para Flask/WhatsApp, normalmente `3000`.

## Instalacion

Desde la raiz del proyecto:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Verifica instalacion:

```bash
python --version
python -m pytest -q
```

## Configuracion de entorno

Crea el archivo local:

```bash
cp .env.example .env
```

Variables relevantes:

| Variable | Uso | Obligatoria |
| --- | --- | --- |
| `CLOUD_CHAT_MODEL` | Modelo Ollama para Cloud Chat. | No |
| `CLOUD_CHAT_PROVIDER` | Provider del catalogo, hoy `aws`. | No |
| `CLOUD_CHAT_CATALOG` | Ruta del catalogo para Cloud Chat. | No |
| `CLOUD_CHAT_USE_LLM` | `true` para usar LLM, `false` para modo deterministico. | No |
| `TWILIO_ACCOUNT_SID` | Cuenta Twilio para envio WhatsApp. | Solo WhatsApp |
| `TWILIO_AUTH_TOKEN` | Token Twilio y validacion webhook. | Solo WhatsApp |
| `TWILIO_WHATSAPP_FROM` | Numero sandbox o remitente Twilio. | Solo WhatsApp |
| `MY_WHATSAPP_TO` | Destino default para pruebas de envio. | Solo envio |
| `PUBLIC_WEBHOOK_URL` | URL publica exacta de `/whatsapp`. | Solo webhook |
| `WHATSAPP_PORT` | Puerto Flask del webhook. | No |

No subas `.env`. Comparte solo `.env.example`.

## Iniciar GUI Streamlit

Con el ambiente activado:

```bash
streamlit run cloud_conversion_ui/Home.py
```

Alternativa sin activar el ambiente:

```bash
.venv/bin/streamlit run cloud_conversion_ui/Home.py
```

En una VM, si necesitas exponerlo a otros usuarios de la red:

```bash
streamlit run cloud_conversion_ui/Home.py --server.address 0.0.0.0 --server.port 8501
```

Usa reglas de firewall o red interna para restringir acceso. La GUI no implementa autenticacion propia.

## Actualizar catalogos

Desde la GUI, entra a `Catalogos` y ejecuta:

- `AWS Fetch`: descarga `data/raw/aws/index.json`.
- `AWS EDA`: genera `data/catalog/aws/aws_ec2_catalog.csv` y reporte EDA.
- `OCI Fetch`: descarga `data/raw/oci/products.json` y genera `data/catalog/oci/oci_price_list.csv`.

Desde CLI:

```bash
python scripts/aws_fetch_offer.py
python scripts/aws_eda.py
python scripts/oci_fetch_offer.py
```

## Ejecutar comparativas

Ruta recomendada:

1. Abre la GUI.
2. En `Inventario`, selecciona o sube un archivo CSV, XLS o XLSX.
3. En `Ejecucion`, revisa parametros AWS/OCI.
4. Ejecuta `AWS Match` y `OCI Match`.
5. En `Dashboard`, revisa costo mensual, ahorro y cobertura.
6. En `Logs y Artefactos`, descarga salidas.

Nota importante: la GUI ejecuta matching con `move_to_done=False`. Esto permite comparar AWS y OCI sobre el mismo inventario sin moverlo automaticamente. Para archivar el inventario, usa el boton `Archivar en input/done` en la pagina `Inventario`.

## Ollama opcional

Los scripts pueden inferir columnas con reglas deterministicas o con LLM local. Para evitar dependencia de Ollama en ejecuciones controladas, usa `--skip-llm` en CLI o marca `Skip LLM` en la GUI.

Si se usa LLM:

```bash
ollama pull llama3.1:8b
```

Luego ejecuta sin `--skip-llm` o configura el modelo en la GUI.

## WhatsApp opcional

Para probar envio:

```bash
python scripts/whatsapp_send.py --body "Prueba Cloud Conversion" --dry-run
```

Para iniciar el webhook Cloud Chat:

```bash
python scripts/whatsapp_chatbot.py
```

Twilio debe apuntar al `PUBLIC_WEBHOOK_URL` exacto, por ejemplo:

```text
https://tu-ngrok.ngrok-free.app/whatsapp
```

`server.py` y `send.py` son demos legacy. Para operacion real usa `scripts/whatsapp_chatbot.py` y `scripts/whatsapp_send.py`.

## Troubleshooting

| Sintoma | Revision |
| --- | --- |
| Streamlit no inicia | Confirma `streamlit==1.57.0` en `requirements.txt` y que el venv este activo. |
| No aparecen inventarios | Coloca CSV/XLS/XLSX en `input/` o sube desde la GUI. |
| Hay mas de un inventario en CLI | Usa `--inventory` para indicar el archivo exacto. |
| AWS Match no encuentra candidatos | Revisa region, OS, tenancy, unit y catalogo AWS generado. |
| OCI Match no genera BOM | Revisa que el catalogo OCI tenga SKUs Compute Standard y precios USD. |
| LLM falla | Ejecuta con `--skip-llm` o verifica Ollama/modelo. |
| Twilio rechaza webhook | `PUBLIC_WEBHOOK_URL` debe coincidir exactamente con la URL firmada por Twilio. |

## Checklist de publicacion interna

- `.env` no esta versionado.
- No hay secretos en logs o inventarios compartidos.
- `python -m pytest -q` pasa.
- La GUI inicia con `streamlit run cloud_conversion_ui/Home.py`.
- `data/` se comparte conscientemente aunque pesa aproximadamente 8 GB.