raulrgmx/Cloud-Conversion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Subir archivos a "docs"

Browse Source
This commit is contained in:
Raul Reyes
2026-06-02 16:46:19 +00:00
commit b345c353e1
5 changed files with 960 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

232
docs/DATA_DICTIONARY.md Normal file
View File

@@ -0,0 +1,232 @@
# Diccionario de Datos
Este documento resume los archivos principales que consume y genera Cloud Conversion. Los formatos no se cambian desde la documentacion; se describen para que otros arquitectos puedan preparar inventarios y leer resultados.
## Inventarios de entrada
Formatos soportados:
- CSV
- XLS
- XLSX
Ubicaciones:
| Ruta | Uso |
| --- | --- |
| `input/` | Inventarios disponibles para CLI y GUI. |
| `input/gui_uploads/` | Inventarios subidos desde Streamlit. |
| `input/done/` | Inventarios archivados manualmente en GUI o automaticamente por CLI. |
Columnas locales esperadas cuando existen:
| Campo normalizado | Columna local | Descripcion |
| --- | --- | --- |
| `quantity` | `Cantidad` | Cantidad de servidores o instancias equivalentes. |
| `cpu` | `vCPU` | vCPU por servidor. |
| `memory_gb` | `Memoria` | Memoria por servidor en GB. |
| `storage_gb` | `Block Storage` | Storage por servidor en GB. |
| `os` | `Nombre` | Sistema operativo o plataforma. |
| `environment` | `Ambiente` | Ambiente: PRD, QA, DEV, UAT, DR, etc. |
| `notes` | `Tipo` | Tipo, rol, workload o descripcion. |
El proyecto tambien tiene fallback para nombres comunes como `VM`, `CPUs`, `RAM`, `storage`, `OS according to the VMware Tools`, `environment`, `hostname` y equivalentes.
## Inventario normalizado
Los matchers transforman cada fila a campos comunes:
| Columna | Descripcion |
| --- | --- |
| `server_name` | Nombre de servidor, VM o grupo. |
| `quantity` | Cantidad final usada para multiplicar costos. |
| `source_cpu` | CPU/vCPU por unidad. |
| `source_memory_gb` | Memoria por unidad en GB. |
| `source_storage_gb` | Storage por unidad en GB. |
| `source_total_cpu` | CPU total para AWS. |
| `source_total_vcpu` | vCPU total para OCI output. |
| `source_ocpu` | OCPU calculado para OCI. |
| `source_total_ocpu` | OCPU total para OCI. |
| `source_total_memory_gb` | Memoria total. |
| `source_total_storage_gb` | Storage total. |
| `os` | OS detectado o mapeado. |
| `environment` | Ambiente. |
| `notes` | Notas o rol del workload. |
## Catalogo AWS
Ruta:
```text
data/catalog/aws/aws_ec2_catalog.csv
```
Origen:
```text
data/raw/aws/index.json
```
Columnas actuales:
| Columna | Descripcion |
| --- | --- |
| `sku` | SKU AWS Pricing. |
| `regionCode` | Codigo de region AWS. |
| `location` | Nombre de ubicacion. |
| `instanceType` | Tipo de instancia, por ejemplo `m7a.xlarge`. |
| `instanceFamily` | Familia comercial. |
| `vcpu` | vCPU del shape. |
| `memory` | Memoria textual del offer. |
| `currentGeneration` | Si es generacion actual. |
| `processorArchitecture` | Arquitectura de CPU. |
| `networkPerformance` | Descripcion de red. |
| `operatingSystem` | OS del precio. |
| `tenancy` | Tenancy, por ejemplo `Shared`. |
| `preInstalledSw` | Software preinstalado. |
| `capacitystatus` | Estado de capacidad, normalmente `Used`. |
| `unit` | Unidad de precio, normalmente `Hrs`. |
| `price_usd` | Precio USD por hora. |
| `description` | Descripcion AWS. |
## Salida AWS Match
Ruta:
```text
data/match/aws/MATCH-AWS-<inventario>.csv
```
Columnas principales:
| Columna | Descripcion |
| --- | --- |
| `server_name` | Servidor o grupo origen. |
| `quantity` | Cantidad origen. |
| `source_cpu` | CPU origen por unidad. |
| `source_memory_gb` | Memoria origen por unidad. |
| `source_storage_gb` | Storage origen por unidad. |
| `workload_type` | Clasificacion de workload usada para ranking. |
| `aws_sku` | SKU recomendado. |
| `aws_region_code` | Region AWS seleccionada. |
| `aws_location` | Ubicacion AWS. |
| `aws_instance_type` | Shape recomendado. |
| `aws_instance_family` | Familia del shape recomendado. |
| `aws_vcpu` | vCPU del shape recomendado. |
| `aws_memory_gb` | Memoria del shape recomendado. |
| `aws_price_usd_per_hr` | Precio unitario por hora. |
| `aws_total_instances` | Instancias recomendadas. |
| `aws_total_price_usd_per_hr` | Costo total por hora. |
| `aws_monthly_price_usd_730h` | Costo mensual usando 730 horas. |
| `aws_operating_system` | OS del precio usado. |
| `aws_match_status` | `MATCH`, `NO_MATCH` o status de error de datos. |
| `aws_candidate_group_selected` | Grupo de candidatos usado para ranking. |
| `aws_recommendation_reason` | Explicacion de seleccion. |
| `aws_preferred_m_family` | Familia M preferida configurada. |
| `aws_m_max_cpu_ratio` | Ratio CPU maximo configurado. |
| `aws_preferred_m_rejection_reason` | Razon de rechazo si la M preferida no aplica. |
## Catalogo OCI
Ruta:
```text
data/catalog/oci/oci_price_list.csv
```
Origen:
```text
data/raw/oci/products.json
```
Columnas:
| Columna | Descripcion |
| --- | --- |
| `partNumber` | SKU o parte OCI. |
| `displayName` | Nombre comercial. |
| `serviceCategory` | Categoria de servicio. |
| `metricName` | Metrica de precio. |
| `currencyCode` | Moneda, normalmente USD. |
| `prices_model` | Modelo de precio. |
| `prices_value` | Valor del precio. |
## Salida OCI Match
Ruta:
```text
data/match/oci/MATCH-OCI-<inventario>.csv
```
Columnas:
| Columna | Descripcion |
| --- | --- |
| `row_type` | `DETAIL`, `BOM` o `SUMMARY`. |
| `server_name` | Servidor o grupo origen. |
| `quantity` | Cantidad origen. |
| `source_cpu` | vCPU origen. |
| `source_ocpu` | OCPU origen calculado. |
| `source_memory_gb` | Memoria por unidad. |
| `source_storage_gb` | Storage por unidad. |
| `source_total_vcpu` | vCPU total. |
| `source_total_ocpu` | OCPU total. |
| `source_total_memory_gb` | Memoria total. |
| `source_total_storage_gb` | Storage total. |
| `os` | OS origen. |
| `environment` | Ambiente origen. |
| `notes` | Notas origen. |
| `oci_pricing_profile` | Perfil de precio OCI, por ejemplo Linux o Windows. |
| `oci_line_item` | Linea BOM o resumen. |
| `oci_sku` | SKU OCI. |
| `oci_display_name` | Nombre OCI. |
| `oci_service_category` | Categoria OCI. |
| `oci_metric_name` | Metrica OCI. |
| `oci_currency_code` | Moneda. |
| `oci_prices_model` | Modelo de precio. |
| `oci_quantity` | Cantidad cotizada. |
| `oci_unit_price_usd_per_hr` | Precio unitario por hora. |
| `oci_hours_per_month` | Horas mensuales usadas. |
| `oci_monthly_price_usd` | Precio mensual calculado. |
| `oci_match_status` | Status de matching. |
| `oci_recommendation_reason` | Explicacion de BOM. |
| `oci_compute_generation` | Generacion compute seleccionada. |
## Dashboard
La GUI lee los ultimos `MATCH-AWS-*.csv` y `MATCH-OCI-*.csv` por fecha de modificacion.
Metricas:
| Metrica | Calculo |
| --- | --- |
| AWS mensual | Suma de `aws_monthly_price_usd_730h` para filas `aws_match_status == MATCH`. |
| OCI mensual | Fila `SUMMARY` de grand total, o suma de filas `BOM`. |
| Ahorro | `(AWS - OCI) / AWS * 100`. |
| Cobertura | Filas AWS con `MATCH` sobre total de filas AWS. |
## Logs
Ruta:
```text
logs/log_cloud_conversion_YYYYMMDD.txt
```
Cada linea incluye timestamp, prefijo de script y mensaje. Prefijos comunes:
| Prefijo | Origen |
| --- | --- |
| `>> AWS_fetch_offer>>` | Descarga AWS. |
| `>> AWS_eda>>` | EDA AWS. |
| `>> AWS_match>>` | Matching AWS. |
| `>> OCI_fetch_offer>>` | Descarga OCI. |
| `>> OCI_match>>` | Matching OCI. |
| `>> cloud_chat>>` | Cloud Chat CLI. |
| `>> cloud_chat_runtime>>` | Runtime WhatsApp/Cloud Chat. |
| `>> whatsapp_chatbot>>` | Webhook WhatsApp. |
Los logs estan ignorados por Git y no deben compartirse sin revision.

160
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,160 @@
# 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.

195
docs/DIRECTORY_STRUCTURE.md Normal file
View File

@@ -0,0 +1,195 @@
# Estructura de Directorios
Vista general de la raiz del proyecto:
```text
.
|-- cloud_conversion_ui/
|-- data/
|-- docs/
|-- input/
|-- logs/
|-- prompts/
|-- references/
|-- scripts/
|-- tests/
|-- .env.example
|-- .gitignore
|-- README.md
|-- requirements.txt
|-- send.py
`-- server.py
```
## `cloud_conversion_ui/`
Interfaz grafica Streamlit.
```text
cloud_conversion_ui/
|-- Home.py
|-- components.py
|-- models.py
|-- theme.py
|-- pages/
`-- services/
```
| Ruta | Uso |
| --- | --- |
| `Home.py` | Entrada de Streamlit. |
| `pages/01_Inventario.py` | Carga, seleccion y archivado de inventarios. |
| `pages/02_Catalogos.py` | Estado y actualizacion de catalogos. |
| `pages/03_Ejecucion.py` | Ejecucion paso a paso de AWS/OCI. |
| `pages/04_Dashboard.py` | Comparativo de costos y cobertura. |
| `pages/05_Logs_Artefactos.py` | Lectura y descarga de artefactos. |
| `services/pipeline_runner.py` | Adaptador que invoca scripts existentes. |
| `services/inventory_files.py` | Gestion de archivos de inventario. |
| `services/dashboard_data.py` | Calculos del dashboard. |
| `services/artifacts.py` | Busqueda de artefactos recientes. |
## `scripts/`
Scripts operativos y utilidades compartidas.
```text
scripts/
|-- aws_fetch_offer.py
|-- aws_eda.py
|-- aws_match.py
|-- oci_fetch_offer.py
|-- oci_match.py
|-- cloud-chat.py
|-- cloud_chat_runtime.py
|-- whatsapp_chatbot.py
|-- whatsapp_send.py
|-- whatsapp_logging.py
|-- match_shared.py
`-- cloud_conversion_logging.py
```
Los scripts CLI son utiles para automatizacion, reproduccion de problemas o ejecuciones sin Streamlit.
## `data/`
Datos crudos, catalogos y resultados.
```text
data/
|-- raw/
| |-- aws/
| `-- oci/
|-- catalog/
| |-- aws/
| `-- oci/
|-- match/
| |-- aws/
| `-- oci/
`-- eda/
`-- aws/
```
| Ruta | Uso |
| --- | --- |
| `data/raw/aws/index.json` | Offer AWS EC2 descargado. |
| `data/raw/oci/products.json` | Productos OCI descargados. |
| `data/catalog/aws/aws_ec2_catalog.csv` | Catalogo AWS plano. |
| `data/catalog/oci/oci_price_list.csv` | Catalogo OCI plano. |
| `data/match/aws/` | Salidas `MATCH-AWS-*.csv`. |
| `data/match/oci/` | Salidas `MATCH-OCI-*.csv`. |
| `data/eda/aws/` | Reportes Markdown de EDA AWS. |
Nota: `data/` puede ser grande. En este workspace pesa aproximadamente 8 GB.
## `input/`
Inventarios de entrada.
```text
input/
|-- done/
`-- gui_uploads/
```
| Ruta | Uso |
| --- | --- |
| `input/` | Inventarios activos disponibles para CLI/GUI. |
| `input/gui_uploads/` | Inventarios subidos desde Streamlit. |
| `input/done/` | Inventarios procesados o archivados. |
La GUI no mueve inventarios automaticamente al ejecutar matching. El archivado manual se hace desde la pagina `Inventario`.
## `logs/`
Bitacoras diarias generadas por scripts:
```text
logs/log_cloud_conversion_YYYYMMDD.txt
```
`logs/` esta en `.gitignore`. Revisa contenido antes de compartir.
## `prompts/`
Prompts usados por matching AWS y mapeo de columnas.
```text
prompts/aws_match_prompts.py
```
## `references/`
Material de referencia, notebooks y ejemplos historicos.
```text
references/
|-- Pricing-oci-example.xlsx
`-- aws-latest-json-eda-v1-1.ipynb
```
## `tests/`
Suite de pruebas Pytest.
Incluye pruebas para:
- AWS/OCI fetch y match.
- Cloud Chat.
- WhatsApp.
- Utilidades compartidas.
- Interfaz grafica y servicios UI.
Comando:
```bash
python -m pytest -q
```
## Archivos raiz
| Archivo | Uso |
| --- | --- |
| `README.md` | Entrada principal del proyecto. |
| `requirements.txt` | Dependencias Python. |
| `.env.example` | Plantilla segura de variables. |
| `.gitignore` | Exclusiones de secretos, venv, logs y caches. |
| `server.py` | Demo legacy Flask/Twilio. |
| `send.py` | Demo legacy de envio WhatsApp. |
## Que compartir
Compartir:
- Codigo fuente.
- Documentacion.
- `.env.example`.
- Datos actuales, si ya fueron revisados para uso interno.
No compartir:
- `.env`.
- `.venv/`.
- `logs/` sin revision.
- Caches de Python, Pytest, Ruff o sistema.
- Inventarios con informacion sensible no autorizada.

220
docs/SCRIPTS.md Normal file
View File

@@ -0,0 +1,220 @@
# Scripts y Comandos
Los scripts CLI estan en `scripts/` y son la ruta avanzada para automatizacion o troubleshooting. Ejecutalos desde la raiz del proyecto con el ambiente virtual activo.
## Resumen
| Script | Objetivo | Entrada principal | Salida principal |
| --- | --- | --- | --- |
| `scripts/aws_fetch_offer.py` | Descargar offer AWS EC2. | Internet AWS Pricing. | `data/raw/aws/index.json`. |
| `scripts/aws_eda.py` | Transformar offer AWS y generar EDA. | `data/raw/aws/index.json`. | `data/catalog/aws/aws_ec2_catalog.csv`, `data/eda/aws/aws_eda_*.md`. |
| `scripts/aws_match.py` | Recomendar shapes AWS por inventario. | Inventario CSV/XLS/XLSX y catalogo AWS. | `data/match/aws/MATCH-AWS-*.csv`. |
| `scripts/oci_fetch_offer.py` | Descargar precios OCI y catalogo plano. | API Oracle products. | `data/raw/oci/products.json`, `data/catalog/oci/oci_price_list.csv`. |
| `scripts/oci_match.py` | Generar BOM OCI agregada. | Inventario CSV/XLS/XLSX y catalogo OCI. | `data/match/oci/MATCH-OCI-*.csv`. |
| `scripts/cloud-chat.py` | Consultar catalogo cloud por CLI. | Pregunta natural y catalogo AWS. | Respuesta en consola y log. |
| `scripts/cloud_chat_runtime.py` | Adaptador importable para Cloud Chat. | Variables de entorno. | Respuesta segura para WhatsApp/Flask. |
| `scripts/whatsapp_send.py` | Enviar mensaje WhatsApp por Twilio. | `.env` y `--body`. | Mensaje Twilio o dry-run. |
| `scripts/whatsapp_chatbot.py` | Webhook Flask para WhatsApp Cloud Chat. | Twilio webhook. | TwiML sync o respuesta diferida. |
| `scripts/whatsapp_logging.py` | Sanitizar logs WhatsApp. | Eventos webhook. | Log diario. |
| `scripts/match_shared.py` | Utilidades comunes AWS/OCI. | DataFrames e inventarios. | Mapping, normalizacion y movimiento a done. |
| `scripts/cloud_conversion_logging.py` | Logging comun. | Prefijo y mensaje. | `logs/log_cloud_conversion_YYYYMMDD.txt`. |
## Pipeline AWS
### Descargar offer
```bash
python scripts/aws_fetch_offer.py
```
Descarga:
```text
data/raw/aws/index.json
```
Efectos:
- Crea directorio destino si no existe.
- Escribe de forma atomica usando archivo temporal.
- Registra mensajes con prefijo `>> AWS_fetch_offer>>`.
### Generar EDA y catalogo
```bash
python scripts/aws_eda.py
```
Con rutas explicitas:
```bash
python scripts/aws_eda.py \
--input data/raw/aws/index.json \
--eda-output data/eda/aws/aws_eda_manual.md \
--catalog-output data/catalog/aws/aws_ec2_catalog.csv
```
Salidas:
- Catalogo plano AWS EC2.
- Reporte Markdown EDA.
### AWS Match
```bash
python scripts/aws_match.py --inventory input/inventario.xlsx --skip-llm
```
Parametros frecuentes:
| Parametro | Uso |
| --- | --- |
| `--inventory` | Archivo CSV/XLS/XLSX de inventario. |
| `--aws-catalog` | Catalogo AWS alterno. |
| `--output` | CSV de salida. |
| `--skip-llm` | Usa reglas deterministicas, sin Ollama. |
| `--force-llm` | Fuerza mapeo por LLM. |
| `--region-code` | Region AWS, default `us-east-1`. |
| `--operating-system` | OS global opcional, por ejemplo `Linux` o `Windows`. |
| `--include-previous-generation` | Incluye generaciones anteriores. |
| `--include-unused-capacity` | Incluye capacidad distinta de `Used`. |
| `--preferred-m-family` | Familia M preferida, default `m7a`. |
Efectos:
- Genera `data/match/aws/MATCH-AWS-<inventario>.csv` si no se pasa `--output`.
- En CLI puede mover inventario exitoso a `input/done/`.
- Registra mensajes con prefijo `>> AWS_match>>`.
## Pipeline OCI
### Descargar offer y catalogo OCI
```bash
python scripts/oci_fetch_offer.py
```
Salidas:
```text
data/raw/oci/products.json
data/catalog/oci/oci_price_list.csv
```
Efectos:
- Descarga productos desde API Oracle.
- Aplana precios localizados a CSV.
- Registra mensajes con prefijo `>> OCI_fetch_offer>>`.
### OCI Match
```bash
python scripts/oci_match.py --inventory input/inventario.xlsx --skip-llm
```
Parametros frecuentes:
| Parametro | Uso |
| --- | --- |
| `--inventory` | Archivo CSV/XLS/XLSX de inventario. |
| `--oci-catalog` | Catalogo OCI alterno. |
| `--output` | CSV de salida. |
| `--skip-llm` | Usa reglas deterministicas, sin Ollama. |
| `--force-llm` | Fuerza mapeo por LLM. |
| `--compute-series` | Serie OCI Standard, default `E`. |
| `--compute-generation` | Generacion fija, por ejemplo `E6`. |
| `--hours-per-month` | Horas mensuales, default `730`. |
| `--no-move-to-done` | Evita archivar inventario al finalizar. |
Efectos:
- Genera `data/match/oci/MATCH-OCI-<inventario>.csv`.
- En CLI mueve inventario exitoso a `input/done/` salvo `--no-move-to-done`.
- Registra mensajes con prefijo `>> OCI_match>>`.
## Cloud Chat CLI
Modo interactivo:
```bash
python scripts/cloud-chat.py
```
Modo one-shot:
```bash
python scripts/cloud-chat.py --ask "Cuanto cuesta m7a.xlarge en virginia?"
```
Opciones:
```bash
python scripts/cloud-chat.py \
--provider aws \
--catalog data/catalog/aws/aws_ec2_catalog.csv \
--model llama3.1:8b \
--ask "Que shapes tienen 8 vCPU y al menos 16 GB?"
```
Defaults:
- Provider: `aws`.
- Catalogo: `data/catalog/aws/aws_ec2_catalog.csv`.
- Modelo: `llama3.1:8b`.
- Region default: `us-east-1`.
- OS default: `Linux`.
- Horas mensuales: `730`.
## WhatsApp
### Envio
```bash
python scripts/whatsapp_send.py --body "Prueba Cloud Conversion" --dry-run
```
Envio real:
```bash
python scripts/whatsapp_send.py --to whatsapp:+52XXXXXXXXXX --body "Hola"
```
Requiere:
- `TWILIO_ACCOUNT_SID`
- `TWILIO_AUTH_TOKEN`
- `TWILIO_WHATSAPP_FROM`
- `MY_WHATSAPP_TO` si no se pasa `--to`
### Webhook Cloud Chat
```bash
python scripts/whatsapp_chatbot.py
```
Requiere:
- `TWILIO_AUTH_TOKEN`
- `PUBLIC_WEBHOOK_URL`
- Variables de Cloud Chat si quieres cambiar modelo/catalogo.
El webhook responde sincronamente si la respuesta llega dentro de `WHATSAPP_SYNC_TIMEOUT_SECONDS`. Si tarda mas, devuelve un acuse y manda respuesta diferida por Twilio.
## Demos legacy
| Archivo | Estado |
| --- | --- |
| `server.py` | Demo Flask simple que valida firma Twilio y responde eco. No es el webhook recomendado. |
| `send.py` | Demo simple de envio WhatsApp con mensaje fijo. Usa `scripts/whatsapp_send.py` para operacion. |
## Validar argumentos
```bash
python scripts/aws_match.py --help
python scripts/oci_match.py --help
python scripts/aws_eda.py --help
python scripts/cloud-chat.py --help
python scripts/whatsapp_send.py --help
```

153
docs/UI_GUIDE.md Normal file
View File

@@ -0,0 +1,153 @@
# Guia de la Interfaz Grafica
La interfaz grafica de Cloud Conversion es una aplicacion Streamlit multipagina. Es la ruta recomendada para arquitectos porque permite operar el pipeline completo desde una consola local.
## Iniciar
Desde la raiz del proyecto:
```bash
source .venv/bin/activate
streamlit run cloud_conversion_ui/Home.py
```
Entrada principal:
```text
cloud_conversion_ui/Home.py
```
Paginas:
```text
cloud_conversion_ui/pages/01_Inventario.py
cloud_conversion_ui/pages/02_Catalogos.py
cloud_conversion_ui/pages/03_Ejecucion.py
cloud_conversion_ui/pages/04_Dashboard.py
cloud_conversion_ui/pages/05_Logs_Artefactos.py
```
## Home
Muestra resumen de los ultimos artefactos disponibles:
- Total mensual AWS.
- Total mensual OCI.
- Porcentaje de ahorro.
- Cobertura de matching.
- Accesos a artefactos recientes.
Si no existen salidas recientes, los indicadores pueden aparecer en cero.
## Inventario
Permite dos formas de seleccionar inventario:
- Subir archivo CSV, XLS o XLSX.
- Elegir un archivo existente en `input/`.
Los uploads se guardan en:
```text
input/gui_uploads/
```
El nombre se normaliza y recibe timestamp, por ejemplo:
```text
input/gui_uploads/20260602_002922_inventario-sbc1.xlsx
```
El inventario activo queda en `st.session_state["selected_inventory_path"]`. Si quieres archivarlo despues de usarlo, usa `Archivar en input/done`.
## Catalogos
Muestra estado de catalogos y permite actualizar precios:
| Boton | Resultado |
| --- | --- |
| `AWS Fetch` | Descarga el offer AWS EC2 en `data/raw/aws/index.json`. |
| `AWS EDA` | Genera `data/catalog/aws/aws_ec2_catalog.csv` y reporte Markdown en `data/eda/aws/`. |
| `OCI Fetch` | Descarga productos OCI y genera `data/catalog/oci/oci_price_list.csv`. |
Requiere acceso de red para descargar precios.
## Ejecucion
Ejecuta los pipelines sobre el inventario activo.
### Parametros AWS
- Region AWS, default `us-east-1`.
- Sistema operativo global opcional.
- Tenancy, default `Shared`.
- Unidad, default `Hrs`.
- Modelo LLM, default `llama3.1:8b`.
- `Skip LLM` para evitar Ollama.
- `Force LLM` para forzar mapeo por LLM.
- Incluir generaciones anteriores.
- Incluir capacidad no usada.
- Prioridad de familia y familia M preferida.
- Max CPU ratio para familia M.
### Parametros OCI
- Modelo LLM, default `llama3.1:8b`.
- `Skip LLM` para evitar Ollama.
- `Force LLM` para forzar mapeo por LLM.
- Compute series, default `E`.
- Compute generation fija opcional.
- Horas por mes, default `730`.
### Diferencia importante contra CLI
La GUI llama `aws_match.run(...)` y `oci_match.run(...)` con:
```python
move_to_done=False
```
Esto evita mover el inventario despues de AWS Match y permite ejecutar OCI Match sobre el mismo archivo. En CLI, los scripts pueden mover inventarios exitosos a `input/done/` por default.
## Dashboard
Lee los ultimos CSVs `MATCH-AWS-*.csv` y `MATCH-OCI-*.csv` para mostrar:
- Costo mensual AWS.
- Costo mensual OCI.
- Ahorro porcentual.
- Cobertura de filas AWS con status `MATCH`.
- Tabla de recomendaciones AWS.
- Resumen BOM OCI.
El dashboard toma los ultimos artefactos por fecha de modificacion. Si necesitas comparar un inventario especifico, genera primero ambos `MATCH-*` desde la pagina `Ejecucion`.
## Logs y Artefactos
Muestra:
- Ultimas lineas del log diario `logs/log_cloud_conversion_YYYYMMDD.txt`.
- CSVs AWS Match.
- CSVs OCI Match.
- Reportes AWS EDA.
- Logs descargables.
Los botones `Descargar` entregan el archivo generado desde disco local.
## Servicios internos de la GUI
| Modulo | Responsabilidad |
| --- | --- |
| `cloud_conversion_ui/services/inventory_files.py` | Listar, subir y archivar inventarios. |
| `cloud_conversion_ui/services/pipeline_runner.py` | Ejecutar pasos AWS/OCI y capturar stdout/stderr. |
| `cloud_conversion_ui/services/dashboard_data.py` | Leer CSVs y calcular metricas comparativas. |
| `cloud_conversion_ui/services/artifacts.py` | Encontrar artefactos recientes y logs. |
## Recomendaciones de uso
- Ejecuta AWS Match y OCI Match sobre el mismo inventario antes de revisar el dashboard.
- Usa `Skip LLM` si no tienes Ollama instalado.
- Actualiza catalogos solo cuando necesites precios recientes; AWS raw puede ser grande.
- Descarga los artefactos desde `Logs y Artefactos` para compartir resultados.
- No expongas Streamlit publicamente sin controles de red o autenticacion externa.