docs: params/output semántico en 506 funciones para composabilidad

Añade campos params y output al frontmatter YAML de las 506 funciones del registry.
Cada parámetro tiene descripción semántica (qué representa, unidades, rango típico)
y cada función describe qué produce su output. Permite a agentes razonar sobre
cadenas de composición (ej: prices → log_return → sharpe_ratio) sin leer código.

python/functions/infra/cache_to_file.md

@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["os", "json", "hashlib", "time", "threading"]
+params:
+  - name: cache_dir
+    desc: "directorio raiz donde se almacenan los archivos de cache"
+  - name: namespace
+    desc: "namespace logico dentro de cache_dir para aislar diferentes cachés"
+output: "instancia FileCache con metodos set, get, get_or_set, clear y stats"
 tested: true
 tests:
   - "Set y get basico"

python/functions/infra/cache_to_sqlite.md

@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["sqlite3", "json", "time", "threading"]
+params:
+  - name: db_path
+    desc: "ruta al archivo SQLite de cache"
+  - name: namespace
+    desc: "namespace logico dentro de la BD para aislar cachés"
+output: "instancia CacheStore con metodos set, get, get_or_set, clear y stats"
 tested: true
 tests:
   - "Set y get basico"

python/functions/infra/get_logger.md

@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [logging]
+params:
+  - name: name
+    desc: "nombre del logger a obtener o crear"
+output: "instancia logging.Logger configurada con handlers"
 tested: true
 tests:
   - "get_logger retorna logger configurado"

python/functions/infra/http_download_file.md

@@ -14,6 +14,18 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["os", "urllib.error", "urllib.request"]
+params:
+  - name: url
+    desc: "URL del archivo a descargar"
+  - name: dest_path
+    desc: "ruta destino donde guardar el archivo descargado"
+  - name: headers
+    desc: "diccionario opcional de headers HTTP personalizados"
+  - name: timeout
+    desc: "timeout en segundos para la descarga (defecto 120.0)"
+  - name: chunk_size
+    desc: "tamaño en bytes de cada chunk descargado (defecto 8192)"
+output: "diccionario con keys path, size_bytes y content_type"
 tested: true
 tests:
   - "mock de descarga con contenido binario"

python/functions/infra/http_get_json.md

@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["json", "urllib.error", "urllib.parse", "urllib.request"]
+params:
+  - name: url
+    desc: "URL base para la solicitud GET"
+  - name: headers
+    desc: "diccionario opcional de headers HTTP personalizados"
+  - name: params
+    desc: "diccionario opcional de parametros de query"
+  - name: timeout
+    desc: "timeout en segundos para la solicitud (defecto 30.0)"
+output: "diccionario con la respuesta JSON parseada"
 tested: true
 tests:
   - "mock de respuesta 200 con JSON"

python/functions/infra/http_post_json.md

@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["json", "urllib.error", "urllib.request"]
+params:
+  - name: url
+    desc: "URL destino para la solicitud POST"
+  - name: body
+    desc: "diccionario a serializar como JSON en el body"
+  - name: headers
+    desc: "diccionario opcional de headers HTTP personalizados"
+  - name: timeout
+    desc: "timeout en segundos para la solicitud (defecto 30.0)"
+output: "diccionario con la respuesta JSON parseada"
 tested: true
 tests:
   - "mock de POST con body serializado correctamente"

python/functions/infra/normalize_zip_filenames.md

@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [zipfile]
+params:
+  - name: zipf
+    desc: "instancia zipfile.ZipFile abierta para reparacion de nombres UTF-8"
+output: "None (modifica in-place los ZipInfo del objeto ZipFile)"
 tested: true
 tests:
   - "ZIP con nombres UTF-8 correctos no se modifican"

python/functions/infra/read_file_with_encoding.md

@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: []
+params:
+  - name: path
+    desc: "ruta del archivo a leer"
+  - name: encodings
+    desc: "lista opcional de encodings a intentar en orden (defecto: ['utf-8', 'utf-8-sig', 'latin-1', 'cp1252'])"
+output: "string con el contenido del archivo decodificado"
 tested: true
 tests:
   - "archivo utf-8 valido"

python/functions/infra/safe_extract_zip.md

@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [os, zipfile, pathlib]
+params:
+  - name: zip_path
+    desc: "ruta del archivo ZIP a extraer"
+  - name: dest_dir
+    desc: "directorio destino para la extraccion"
+output: "None (extrae archivos al disco en dest_dir)"
 tested: true
 tests:
   - "ZIP normal extrae correctamente dentro del destino"

python/functions/infra/scan_directory.md

@@ -14,6 +14,20 @@ returns: [directory_scan_result_py_infra]
 returns_optional: false
 error_type: "error_go_core"
 imports: [os, pathlib, fnmatch, sys, dataclasses]
+params:
+  - name: root
+    desc: "directorio raiz a escanear"
+  - name: supported_extensions
+    desc: "conjunto opcional de extensiones soportadas (ej: {'.pdf', '.md'})"
+  - name: ignore_dirs
+    desc: "conjunto opcional de nombres de directorio a ignorar"
+  - name: include
+    desc: "patrones glob opcionales separados por coma para incluir archivos"
+  - name: exclude
+    desc: "patrones glob opcionales separados por coma para excluir archivos"
+  - name: strict
+    desc: "si True, lanza ValueError si hay archivos no soportados"
+output: "instancia DirectoryScanResult con listas processable y unsupported de ClassifiedFile"
 tested: true
 tests:
   - "directorio con mezcla de archivos"

python/functions/infra/setup_logger.md

@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [logging, logging.handlers, os, sys, datetime]
+params:
+  - name: name
+    desc: "nombre del logger a configurar"
+  - name: log_dir
+    desc: "directorio donde guardar archivos de log (defecto 'logs')"
+  - name: level
+    desc: "nivel de logging (defecto logging.DEBUG)"
+output: "instancia logging.Logger configurada con handlers de archivo y consola"
 tested: true
 tests:
   - "logger se crea con 2 handlers"