From b345c353e15175e4b8e16c74a4d1fd59d721d940 Mon Sep 17 00:00:00 2001 From: Raul Reyes Date: Tue, 2 Jun 2026 16:46:19 +0000 Subject: [PATCH] Subir archivos a "docs" --- docs/DATA_DICTIONARY.md | 232 ++++++++++++++++++++++++++++++++++++ docs/DEPLOYMENT.md | 160 +++++++++++++++++++++++++ docs/DIRECTORY_STRUCTURE.md | 195 ++++++++++++++++++++++++++++++ docs/SCRIPTS.md | 220 ++++++++++++++++++++++++++++++++++ docs/UI_GUIDE.md | 153 ++++++++++++++++++++++++ 5 files changed, 960 insertions(+) create mode 100644 docs/DATA_DICTIONARY.md create mode 100644 docs/DEPLOYMENT.md create mode 100644 docs/DIRECTORY_STRUCTURE.md create mode 100644 docs/SCRIPTS.md create mode 100644 docs/UI_GUIDE.md diff --git a/docs/DATA_DICTIONARY.md b/docs/DATA_DICTIONARY.md new file mode 100644 index 0000000..4ccff18 --- /dev/null +++ b/docs/DATA_DICTIONARY.md @@ -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-.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-.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. + diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..0055346 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -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. + diff --git a/docs/DIRECTORY_STRUCTURE.md b/docs/DIRECTORY_STRUCTURE.md new file mode 100644 index 0000000..6fe7397 --- /dev/null +++ b/docs/DIRECTORY_STRUCTURE.md @@ -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. + diff --git a/docs/SCRIPTS.md b/docs/SCRIPTS.md new file mode 100644 index 0000000..e3ffcf0 --- /dev/null +++ b/docs/SCRIPTS.md @@ -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-.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-.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 +``` + diff --git a/docs/UI_GUIDE.md b/docs/UI_GUIDE.md new file mode 100644 index 0000000..9c0bcb7 --- /dev/null +++ b/docs/UI_GUIDE.md @@ -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. +