feat(browser): auto-commit con 178 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

python/functions/datascience/kmeans_segments.md

@@ -0,0 +1,76 @@
+---
+name: kmeans_segments
+kind: function
+lang: py
+domain: datascience
+version: "1.0.0"
+purity: pure
+signature: "def kmeans_segments(columns: dict, k_min: int = 2, k_max: int = 8) -> dict"
+description: "Detecta segmentos naturales con KMeans eligiendo el mejor k automaticamente por silhouette. Estandariza, descarta filas con None y prueba k de k_min a min(k_max, n_rows-1)."
+tags: [eda, models, kmeans, clustering, segmentation, silhouette, unsupervised]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: ""
+imports: [numpy, scikit-learn]
+tested: true
+tests: ["test_three_separated_blobs_finds_k3", "test_insufficient_rows_returns_note", "test_insufficient_numeric_columns_returns_note", "test_rows_with_none_are_dropped"]
+test_file_path: "python/functions/datascience/kmeans_segments_test.py"
+file_path: "python/functions/datascience/kmeans_segments.py"
+params:
+  - name: columns
+    desc: "dict {col_name: [valores numericos]} con todas las listas alineadas por fila (misma longitud). Solo se usan columnas numericas; las no numericas se ignoran. Las filas con algun None se descartan."
+  - name: k_min
+    desc: "Numero minimo de clusters a probar. Default 2. El minimo efectivo de filas validas requerido es k_min*2."
+  - name: k_max
+    desc: "Numero maximo de clusters a probar. Default 8. Se acota internamente a min(k_max, n_rows_validas-1)."
+output: "dict con best_k (k de mayor silhouette), silhouette (score del mejor k), scores_by_k (lista de {k, silhouette, inertia} por cada k probado), cluster_sizes (tamano de cada cluster del mejor modelo), centers (centroides en espacio estandarizado), n_rows_used (filas validas) y n_features (columnas numericas). Si hay <2 columnas numericas o <k_min*2 filas validas devuelve {best_k: 0, note: 'datos insuficientes'}."
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join("python", "functions"))
+from datascience.kmeans_segments import kmeans_segments
+
+# Tres grupos claramente separados en 2D.
+g1 = [(0.0, 0.0)] * 30
+g2 = [(10.0, 10.0)] * 30
+g3 = [(0.0, 10.0)] * 30
+pts = g1 + g2 + g3
+columns = {
+    "x": [p[0] for p in pts],
+    "y": [p[1] for p in pts],
+}
+
+result = kmeans_segments(columns, k_min=2, k_max=6)
+print(result["best_k"])        # 3
+print(round(result["silhouette"], 2))  # ~1.0 (grupos perfectos)
+print(result["cluster_sizes"]) # [30, 30, 30] (en algun orden)
+```
+
+## Cuando usarla
+
+Usala cuando, durante un EDA, quieras descubrir cuantos segmentos naturales hay en un
+conjunto de columnas numericas sin saber el numero de grupos de antemano: clientes por
+comportamiento, productos por metricas, regiones por indicadores. Elige el k optimo por
+ti via silhouette, asi que no tienes que fijarlo a mano. Pasale solo las columnas
+numericas relevantes alineadas por fila.
+
+## Gotchas
+
+Funcion pura y determinista (KMeans con random_state=0 y n_init=10), pero requiere
+`numpy` y `scikit-learn` instalados. Los centroides (`centers`) estan en el espacio
+estandarizado (z-scores), no en las unidades originales de las columnas. La silhouette
+puede ser baja o negativa si los datos no tienen estructura de cluster real; un best_k
+alto con silhouette baja sugiere ausencia de segmentacion clara.
+
+## Notas
+
+Estandariza con StandardScaler antes de clusterizar para que todas las features pesen
+igual. Para cada k en [k_min, min(k_max, n_rows-1)] ajusta KMeans y calcula silhouette;
+devuelve el modelo con mayor silhouette. Guardas de datos insuficientes: <2 columnas
+numericas o <k_min*2 filas validas devuelven {best_k: 0, note: "datos insuficientes"}
+sin lanzar excepcion.