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.
2026-04-05 18:45:16 +02:00
parent bd1bf2b5dc
commit 988e901066
506 changed files with 2964 additions and 0 deletions
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista de elementos a evaluar"
+  - name: pred
+    desc: "predicado (funcion que retorna bool) para evaluar cada elemento"
+output: "booleano: True si todos los elementos cumplen el predicado, False en caso contrario"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista de elementos a evaluar"
+  - name: pred
+    desc: "predicado (funcion que retorna bool) para evaluar cada elemento"
+output: "booleano: True si al menos un elemento cumple el predicado, False en caso contrario"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: node_list
+    desc: "lista plana de dicts con campos title, level y opcionalmente line_num"
+output: "lista de dicts que forman arbol jerarquico anidado segun niveles"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["asyncio", "functools", "hashlib", "json"]
+params:
+  - name: store
+    desc: "store persistente compatible (CacheStore o FileCache) que implementa get/set"
+  - name: ttl
+    desc: "tiempo de vida del cache en segundos (0 significa infinito)"
+  - name: key_fn
+    desc: "funcion personalizada para generar clave de cache, recibe (func_name, args, kwargs)"
+output: "decorator que cachea resultados de la funcion decorada"
 tested: true
 tests:
  - "Funcion llamada una vez, segunda vez desde cache"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: image_count
+    desc: "numero total de imagenes en el documento"
+  - name: line_count
+    desc: "numero total de lineas de texto en el documento"
+output: "string con estrategia optima: 'full_page_vlm', 'extract' o 'text_only'"
 tested: true
 tests:
  - "0 imagenes text_only"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: pairs
+    desc: "lista de dicts con campos 'page' (numero logico) y 'physical_index' (indice fisico)"
+output: "entero con el offset (diferencia moda entre physical_index - page)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,24 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["time", "random", "typing.Callable", "typing.TypeVar"]
+params:
+  - name: items
+    desc: "lista de items a procesar"
+  - name: process_func
+    desc: "funcion que procesa un item individual"
+  - name: max_retries
+    desc: "numero maximo de reintentos por item"
+  - name: initial_delay
+    desc: "delay inicial en segundos para exponential backoff"
+  - name: max_delay
+    desc: "delay maximo en segundos para el backoff"
+  - name: backoff_factor
+    desc: "factor de multiplicacion para el backoff exponencial"
+  - name: exceptions
+    desc: "tupla de tipos de excepcion que desencadenan reintentos"
+  - name: continue_on_failure
+    desc: "si False, aborta el batch en el primer error; si True continua"
+output: "tupla (results, failures) donde results es lista de valores y failures es lista de dicts con index/item/error"
 tested: true
 tests:
  - "todos los items exito"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista a dividir"
+  - name: size
+    desc: "tamanio de cada sublista (chunk)"
+output: "lista de sublistas, cada una con maximo 'size' elementos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [threading, time, enum]
+params:
+  - name: failure_threshold
+    desc: "numero de fallos consecutivos que dispara el estado OPEN"
+  - name: reset_timeout
+    desc: "tiempo en segundos que debe esperar antes de pasar a HALF_OPEN"
+output: "instancia de CircuitBreaker con metodos check(), record_success(), record_failure(), retry_after"
 tested: true
 tests:
  - "Transicion CLOSED → OPEN despues de N fallos"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: error
+    desc: "excepcion de Python (Exception o subclase) a clasificar"
+output: "string: 'permanent' (no reintentar), 'transient' (reintentar), o 'unknown'"
 tested: true
 tests: ["error 429 es transitorio", "error 401 es permanente", "error timeout es transitorio", "error desconocido retorna unknown", "error con __cause__ transitorio"]
 test_file_path: "python/functions/core/classify_api_error_test.py"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [datetime]
+params:
+  - name: data
+    desc: "dict con valores a coercionar (tipicamente strings)"
+  - name: schema
+    desc: "dict con campos como keys y tipos esperados como values (int, float, str, bool, datetime, list[str])"
+output: "tupla (resultado_coercionado, lista_de_warnings)"
 tested: true
 tests:
  - "string 42 a int 42"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: fns
+    desc: "funciones a componer (variable number of arguments)"
+output: "funcion compuesta que aplica las funciones de derecha a izquierda"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [random]
+params:
+  - name: attempt
+    desc: "numero de intento (0-based, siendo 0 el primer reintento)"
+  - name: base_delay
+    desc: "delay inicial en segundos"
+  - name: max_delay
+    desc: "delay maximo permitido en segundos"
+  - name: jitter
+    desc: "si True anade variacion aleatoria al delay"
+output: "numero flotante representando el delay en segundos"
 tested: true
 tests: ["attempt 0 retorna base_delay sin jitter", "attempt alto se cappea a max_delay", "sin jitter es determinista"]
 test_file_path: "python/functions/core/compute_backoff_delay_test.py"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["urllib.parse"]
+params:
+  - name: url
+    desc: "URL a convertir (puede ser GitHub, GitLab o cualquier otra)"
+output: "string con la URL convertida a raw format (o sin cambios si no es un blob)"
 tested: true
 tests:
  - "URL GitHub blob"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: tree
+    desc: "lista de dicts representando arbol jerarquico con campos node_id y nodes"
+output: "dict con node_id como keys y nodos como values para lookup O(1)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,22 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["time", "typing.Callable", "typing.TypeVar"]
+params:
+  - name: fetch_page
+    desc: "callable que recibe limit y cursor como kwargs, retorna lista de items"
+  - name: get_cursor
+    desc: "callable que recibe un item y retorna su cursor (o None si es el ultimo)"
+  - name: page_size
+    desc: "numero de items por pagina a solicitar"
+  - name: max_items
+    desc: "limite maximo total de items a acumular"
+  - name: max_retries
+    desc: "numero maximo de reintentos por pagina"
+  - name: retry_delay
+    desc: "delay inicial en segundos para exponential backoff entre reintentos"
+  - name: retryable_exceptions
+    desc: "tupla de tipos de excepcion que desencadenan reintento"
+output: "lista de items recopilados de todas las paginas"
 tested: true
 tests:
  - "API que retorna 3 paginas de 10 items"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [pdfplumber, collections]
+params:
+  - name: pdf
+    desc: "objeto pdfplumber.PDF abierto con which_pages="
+  - name: min_delta
+    desc: "diferencia minima de font size para clasificar como heading"
+  - name: max_levels
+    desc: "numero maximo de heading levels a detectar"
+output: "lista de dicts con campos page_num, level, title para cada heading detectado"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["urllib.parse", "httpx"]
+params:
+  - name: url
+    desc: "URL a clasificar"
+  - name: timeout
+    desc: "timeout en segundos para HTTP HEAD request si es necesario"
+output: "tupla (tipo, metadata_dict) donde tipo es string como 'pdf', 'webpage', 'code_repository' etc."
 tested: true
 tests:
  - "URL .pdf por extension"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [python-docx, lxml]
+params:
+  - name: docx_path
+    desc: "ruta al archivo Word .docx"
+output: "string markdown con headings, parrafos formateados y tablas preservadas"
 tested: true
 tests: ["docx con headings y parrafos", "docx con tablas intercaladas", "docx con formato bold/italic", "docx vacio", "archivo no encontrado lanza FileNotFoundError"]
 test_file_path: "python/functions/core/docx_to_markdown_test.py"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista de la que descartar elementos"
+  - name: n
+    desc: "numero de elementos a descartar desde el inicio"
+output: "lista sin los primeros n elementos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [zipfile, html, re, ebooklib]
+params:
+  - name: epub_path
+    desc: "ruta al archivo EPUB"
+output: "string markdown con titulo, autor (si esta disponible) y contenido del ebook"
 tested: true
 tests:
  - "conversion de headings h1-h3"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: content
+    desc: "string de contenido a contar"
+output: "entero estimando el numero de tokens en el contenido"
 tested: true
 tests:
  - "texto vacio retorna cero"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["openpyxl", "xlrd"]
+params:
+  - name: path
+    desc: "ruta al archivo Excel (.xlsx, .xls, .xlsm)"
+  - name: max_rows_per_sheet
+    desc: "limite maximo de filas a procesar por sheet"
+output: "string markdown con cada sheet como seccion H2 y sus datos en tablas"
 tested: true
 tests:
  - "xlsx con multiples sheets produce una seccion H2 por sheet"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re, yaml]
+params:
+  - name: content
+    desc: "string con contenido markdown potencialmente precedido por YAML frontmatter"
+output: "tupla (contenido_sin_frontmatter, dict_parseado_o_None)"
 tested: true
 tests:
  - "contenido con frontmatter"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [json]
+params:
+  - name: content
+    desc: "string con respuesta LLM que contiene JSON (puede estar en bloque ```json)"
+output: "dict parseado desde el JSON; dict vacio si no se puede recuperar"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: markdown_content
+    desc: "string con contenido markdown"
+output: "tupla (lista_de_headers, lista_de_lineas_originales) donde headers son dicts con title/level/line_num"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [pdfplumber]
+params:
+  - name: pdf
+    desc: "objeto pdfplumber.PDF abierto"
+output: "lista de dicts con campos level (1-6), title y page_num para cada bookmark"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [PyPDF2]
+params:
+  - name: pdf_path
+    desc: "ruta al archivo PDF desde el cual extraer el texto"
+output: "string: texto concatenado de todas las páginas del PDF"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["os", "fitz (PyMuPDF)", "charset_normalizer", "chardet"]
+params:
+  - name: file_path
+    desc: "ruta al archivo (PDF, MD o TXT)"
+output: "string con texto extraido del archivo"
 tested: true
 tests:
  - "PDF con texto extrae contenido correctamente"
@@ -16,6 +16,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: ["httpx"]
+params:
+  - name: url
+    desc: "URL a descargar y convertir"
+  - name: timeout
+    desc: "timeout en segundos para el HTTP request"
+output: "string markdown con el contenido convertido desde la pagina web"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista a filtrar"
+  - name: pred
+    desc: "predicado (funcion que retorna bool) para seleccionar elementos"
+output: "lista con solo los elementos que cumplen el predicado"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista donde buscar"
+  - name: pred
+    desc: "predicado (funcion que retorna bool) para encontrar un elemento"
+output: "primer elemento que cumple el predicado, o None si no hay coincidencia"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: content
+    desc: "string con contenido markdown"
+output: "lista de tuplas (start_pos, end_pos, title, level) para cada heading detectado"
 tested: true
 tests:
  - "headings normales detectados correctamente"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista donde buscar"
+  - name: pred
+    desc: "predicado (funcion que retorna bool) para encontrar un indice"
+output: "entero con el indice del primer elemento que cumple, o -1 si no hay"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista a transformar"
+  - name: fn
+    desc: "funcion que recibe un elemento y retorna una lista"
+output: "lista plana resultado de aplicar fn a cada elemento y aplanar un nivel"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xss
+    desc: "lista de listas a aplanar"
+output: "lista plana con todos los elementos concatenados un nivel"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [copy]
+params:
+  - name: structure
+    desc: "arbol jerarquico (dict con campo 'nodes' anidado recursivamente)"
+output: "lista plana de dicts sin campo 'nodes', deep copy de cada nodo"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["datetime"]
+params:
+  - name: dt
+    desc: "datetime object (puede ser naive o aware)"
+output: "string ISO 8601 UTC con milisegundos formato yyyy-MM-ddTHH:mm:ss.SSSZ"
 tested: true
 tests:
  - "datetime naive formateado como UTC"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["datetime"]
+params:
+  - name: dt
+    desc: "datetime a formatear"
+  - name: now
+    desc: "datetime actual para comparacion"
+output: "string con formato humano simplificado: HH:MM:SS si mismo dia, YYYY-MM-DD si otro dia"
 tested: true
 tests:
  - "mismo dia muestra formato hora"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: rows
+    desc: "lista 2D de listas con celdas (cada fila es una lista de strings)"
+  - name: has_header
+    desc: "si True la primera fila se trata como header y se anade separador"
+output: "string con tabla markdown formateada con pipes y alineacion de columnas"
 tested: true
 tests: ["tabla normal", "tabla con celdas vacias", "tabla con 1 fila", "tabla vacia", "celdas con pipes", "sin header"]
 test_file_path: "python/functions/core/format_table_to_markdown_test.py"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: structure
+    desc: "arbol jerarquico (dict con campo 'nodes' anidado recursivamente)"
+  - name: order
+    desc: "lista de nombres de campos en el orden deseado para reordenar"
+output: "estructura arbol con los campos de cada nodo reordenados segun order"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: text
+    desc: "string con contenido CSV"
+  - name: delimiter
+    desc: "caracter delimitador de campos (default coma)"
+  - name: has_header
+    desc: "si True la primera fila se usa como nombres de columnas"
+output: "lista de dicts donde cada dict es una fila y las keys son los nombres de columnas"
 tested: true
 tests:
  - "csv simple con header"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["json"]
+params:
+  - name: text
+    desc: "string con contenido JSONL (JSON Lines, una linea por objeto)"
+output: "lista de dicts, cada uno parseado desde una linea del JSONL"
 tested: true
 tests:
  - "jsonl valido"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["re"]
+params:
+  - name: title
+    desc: "titulo del reporte HTML"
+  - name: sections
+    desc: "lista de dicts con campos heading, type, data para cada seccion"
+output: "string HTML completo autocontenido con CSS inline y todas las secciones renderizadas"
 tested: true
 tests:
  - "reporte con una tabla"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [copy]
+params:
+  - name: structure
+    desc: "arbol jerarquico (dict con campo 'nodes' anidado recursivamente)"
+output: "lista de dicts representando solo los nodos hoja (sin hijos)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [litellm, PyPDF2]
+params:
+  - name: pdf_path
+    desc: "ruta al archivo PDF (string o BytesIO)"
+  - name: model
+    desc: "nombre del modelo LLM para contar tokens (p.ej. 'gpt-4o')"
+  - name: pdf_parser
+    desc: "backend para extraer texto: 'PyPDF2' (default) o 'PyMuPDF'"
+output: "lista de tuplas (text, token_count) uno por pagina del PDF"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: text
+    desc: "string de texto a analizar"
+output: "dict con claves total_chars, total_lines, total_words conteniendo conteos basicos"
 tested: true
 tests: ["texto normal con palabras y lineas", "texto vacio retorna ceros", "texto con solo newlines"]
 test_file_path: "python/functions/core/get_text_stats_test.py"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista de elementos a agrupar"
+  - name: key_fn
+    desc: "funcion que extrae la clave de agrupacion de cada elemento"
+output: "dict donde las keys son los resultados de key_fn y los values son listas de elementos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["re", "html.parser"]
+params:
+  - name: html
+    desc: "string con contenido HTML a convertir"
+output: "string con markdown equivalente al contenido HTML"
 tested: true
 tests:
  - "HTML con nav/footer filtra boilerplate"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [urllib.parse]
+params:
+  - name: url
+    desc: "URL del repositorio de código a validar (HTTPS, HTTP, SSH)"
+  - name: known_hosts
+    desc: "Lista opcional de hosts conocidos para validar URLs SSH"
+output: "True si la URL apunta a un repositorio clonable, False en caso contrario"
 tested: true
 tests:
  - "URL repo valida"
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: left
+    desc: "Lista izquierda de diccionarios a joinear"
+  - name: right
+    desc: "Lista derecha de diccionarios a joinear"
+  - name: key
+    desc: "Nombre de la clave común para hacer matching"
+  - name: how
+    desc: "Tipo de join: 'inner', 'left', 'right' u 'outer'"
+output: "Lista de diccionarios resultantes del join con campos renombrados si hay conflicto"
 tested: true
 tests:
  - "Inner join solo matches"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "Lista plana de diccionarios con campo 'structure' (ej: '1.2.3')"
+output: "Árbol jerárquico anidado donde nodos padres contienen su lista 'nodes'"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [litellm, asyncio, logging]
+params:
+  - name: model
+    desc: "Nombre del modelo LLM (ej: 'gpt-4o', 'claude-sonnet-4-20250514')"
+  - name: prompt
+    desc: "Mensaje de usuario a enviar al modelo"
+  - name: max_retries
+    desc: "Número máximo de reintentos ante errores transitorios"
+  - name: temperature
+    desc: "Temperatura para la generación (0.0 a 1.0)"
+output: "Texto de respuesta del modelo LLM"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,20 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [litellm, logging, time]
+params:
+  - name: model
+    desc: "Nombre del modelo LLM soportado por litellm"
+  - name: prompt
+    desc: "Prompt del usuario a procesar"
+  - name: chat_history
+    desc: "Historial de chat opcional con formato [{'role': '...', 'content': '...'}]"
+  - name: return_finish_reason
+    desc: "Si True, retorna tupla (content, finish_reason) en lugar de solo content"
+  - name: max_retries
+    desc: "Número máximo de reintentos ante fallos"
+  - name: temperature
+    desc: "Temperatura para la generación"
+output: "String con la respuesta del modelo, o tupla (str, str) si return_finish_reason=True"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [json, os]
+params:
+  - name: locales_dir
+    desc: "Ruta al directorio con archivos de traducción JSON ({locale}.json)"
+output: "Diccionario con clave=nombre_locale y valor=contenido del JSON"
 tested: true
 tests: ["carga multiples locales", "directorio inexistente retorna dict vacio", "ignora archivos no json", "locale con estructura anidada"]
 test_file_path: "python/functions/core/load_translations_test.py"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "Lista de elementos a transformar"
+  - name: fn
+    desc: "Función a aplicar a cada elemento"
+output: "Nueva lista con el resultado de aplicar fn a cada elemento"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: attr_list
+    desc: "Lista de diccionarios con atributos de candidatos de la misma entidad"
+output: "Diccionario con atributos merged aplicando heurísticas de resolución por tipo"
 tested: true
 tests:
  - "Atributos complementarios (A tiene full_name, B tiene nationality) -> ambos"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [datetime]
+params:
+  - name: schedule
+    desc: "Diccionario de cron schedule parsado con parse_cron_expr"
+  - name: after
+    desc: "Datetime base desde el cual calcular la próxima ejecución"
+output: "Próximo datetime cuando se ejecute el cron, o None si el schedule es imposible"
 tested: true
 tests:
  - "0 * * * * desde :30 retorna la proxima hora en punto"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: name
+    desc: "Nombre de la entidad a normalizar"
+  - name: entity_type
+    desc: "Tipo de entidad para aplicar reglas específicas (person, organization, email, domain, ip, etc.)"
+output: "Nombre normalizado según el tipo de entidad"
 tested: true
 tests:
  - "person strip whitespace"
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math]
+params:
+  - name: page_contents
+    desc: "Lista de strings con contenido de cada página"
+  - name: token_lengths
+    desc: "Lista paralela con número de tokens por página"
+  - name: max_tokens
+    desc: "Límite máximo de tokens por grupo"
+  - name: overlap_pages
+    desc: "Número de páginas a solapar entre grupos consecutivos"
+output: "Lista de strings donde cada string es un grupo de páginas combinadas"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: [code_entity_py_core]
 returns_optional: false
 error_type: ""
 imports: [tree-sitter, tree-sitter-python, tree-sitter-go, tree-sitter-javascript, tree-sitter-typescript, tree-sitter-rust, tree-sitter-java, tree-sitter-cpp]
+params:
+  - name: source_code
+    desc: "String con el código fuente a analizar"
+  - name: language
+    desc: "Lenguaje del código (python/py, go, javascript/js, typescript/ts, rust/rs, java, cpp/c++)"
+output: "Lista de entidades CodeEntity extraídas del AST (funciones, clases, métodos, interfaces)"
 tested: true
 tests:
  - "lenguaje no soportado lanza value error"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: expr
+    desc: "Expresión cron estándar de 5 campos o alias como @daily, @hourly"
+output: "Diccionario con claves minute, hour, day_of_month, month, day_of_week conteniendo listas de enteros válidos"
 tested: true
 tests:
  - "*/15 expande minutos a [0 15 30 45]"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [urllib.parse]
+params:
+  - name: url
+    desc: "URL de repositorio de código (HTTPS, SSH, git://, ssh://)"
+  - name: known_hosts
+    desc: "Lista opcional de hosts conocidos a reconocer"
+output: "String con formato 'org/repo' si la URL es válida, None si no se puede parsear"
 tested: true
 tests:
  - "URL HTTPS GitHub"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["re", "datetime"]
+params:
+  - name: value
+    desc: "String en formato ISO 8601 (posiblemente con fracciones de segundo excesivas)"
+output: "Objeto datetime parseado y normalizado"
 tested: true
 tests:
  - "ISO normal sin fraccion"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [json]
+params:
+  - name: response
+    desc: "String con respuesta del LLM (posiblemente con think tags y markdown codeblocks)"
+output: "Diccionario parseado del JSON limpio"
 tested: true
 tests: ["JSON limpio es parseado correctamente", "JSON con think tags y codeblock es parseado correctamente", "JSON invalido lanza ValueError"]
 test_file_path: "python/functions/core/parse_llm_json_test.py"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: pages
+    desc: "String con especificación de páginas (ej: '5-7,3,10-12')"
+output: "Lista ordenada de números de página sin duplicados"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,8 @@ returns: [parse_result_py_core]
 returns_optional: false
 error_type: "error_go_core"
 imports: []
+params: []
+output: "ParseResult con contenido parseado y metadatos del parsing"
 tested: true
 tests:
  - "registrar parser custom"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "Lista a dividir"
+  - name: pred
+    desc: "Función predicado que retorna True/False"
+output: "Tupla (elementos_que_cumplen, elementos_que_no_cumplen)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [pdfplumber, os, sys]
+params:
+  - name: pdf_path
+    desc: "Ruta al archivo PDF a convertir"
+  - name: heading_detection
+    desc: "Estrategia de detección de headings: 'auto', 'bookmarks', 'font'"
+output: "Tupla (markdown_content, metadata_dict) con el PDF convertido a markdown y metadatos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: value
+    desc: "Valor inicial a pasar por las funciones"
+  - name: fns
+    desc: "Funciones a aplicar secuencialmente de izquierda a derecha"
+output: "Resultado final después de aplicar todas las funciones en orden"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: text
+    desc: "Texto crudo a normalizar"
+output: "Texto con whitespace normalizado y newlines ajustados"
 tested: true
 tests: ["texto con saltos de linea Windows CRLF", "texto con multiples newlines consecutivos", "texto con espacios leading y trailing en cada linea"]
 test_file_path: "python/functions/core/preprocess_text_test.py"
@@ -14,6 +14,24 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [json, re, typing]
+params:
+  - name: llm_chat
+    desc: "Función que envía mensajes al LLM y retorna la respuesta"
+  - name: tools
+    desc: "Diccionario de funciones disponibles como tools {nombre: callable}"
+  - name: system_prompt
+    desc: "Instrucciones del sistema para el agente"
+  - name: user_prompt
+    desc: "Pregunta/tarea inicial del usuario"
+  - name: max_iterations
+    desc: "Máximo número de iteraciones antes de fallback"
+  - name: on_thought
+    desc: "Callback opcional para logging de pensamientos"
+  - name: on_action
+    desc: "Callback opcional para logging de acciones"
+  - name: on_observation
+    desc: "Callback opcional para logging de observaciones"
+output: "String con la respuesta final del agente"
 tested: true
 tests:
  - "agente que usa 1 tool y da respuesta final"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "Lista a reducir"
+  - name: initial
+    desc: "Valor inicial del acumulador"
+  - name: fn
+    desc: "Función binaria fn(acumulador, elemento)"
+output: "Valor final del acumulador después de procesar todos los elementos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "Estructura árbol (dict/list/valor) a procesar"
+  - name: fields
+    desc: "Lista de nombres de campo a eliminar recursivamente (default: ['text'])"
+output: "Copia de la estructura sin los campos especificados"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["re"]
+params:
+  - name: template
+    desc: "String con template usando {{var}}, {{{raw}}}, {% for %}, {% if %}"
+  - name: context
+    desc: "Diccionario con valores para las variables"
+  - name: missing
+    desc: "Valor a usar cuando falta una variable (default: '')"
+output: "String renderizado con variables sustituidas y lógica aplicada"
 tested: true
 tests:
  - "sustitucion simple"
@@ -14,6 +14,20 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [asyncio, typing]
+params:
+  - name: func
+    desc: "Corrutina a reintentar"
+  - name: max_retries
+    desc: "Número máximo de reintentos"
+  - name: base_delay
+    desc: "Delay inicial en segundos"
+  - name: max_delay
+    desc: "Delay máximo en segundos"
+  - name: jitter
+    desc: "Si True, añade variabilidad al delay"
+  - name: is_retryable
+    desc: "Predicado opcional para decidir si reintentar una excepción"
+output: "Resultado de ejecutar la función si tiene éxito"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,20 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [time, typing]
+params:
+  - name: func
+    desc: "Función a reintentar"
+  - name: max_retries
+    desc: "Número máximo de reintentos"
+  - name: base_delay
+    desc: "Delay inicial en segundos entre reintentos"
+  - name: max_delay
+    desc: "Delay máximo en segundos"
+  - name: jitter
+    desc: "Si True, añade variabilidad al delay"
+  - name: is_retryable
+    desc: "Predicado opcional para decidir si reintentar"
+output: "Resultado de ejecutar la función si tiene éxito"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,22 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [functools, time, random, asyncio, collections.abc, typing]
+params:
+  - name: max_retries
+    desc: "Número máximo de reintentos"
+  - name: initial_delay
+    desc: "Delay inicial en segundos"
+  - name: max_delay
+    desc: "Delay máximo en segundos"
+  - name: backoff_factor
+    desc: "Factor multiplicativo para el delay exponencial"
+  - name: jitter
+    desc: "Si True, añade variabilidad aleatoria al delay"
+  - name: exceptions
+    desc: "Tupla de tipos de excepción a reintentar"
+  - name: on_retry
+    desc: "Callback opcional llamado cuando se reintenta"
+output: "Decorador que envuelve la función con lógica de retry"
 tested: true
 tests:
  - "funcion que falla dos veces y luego exito"
@@ -14,6 +14,22 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [functools, asyncio, random, collections.abc, typing]
+params:
+  - name: max_retries
+    desc: "Número máximo de reintentos"
+  - name: initial_delay
+    desc: "Delay inicial en segundos"
+  - name: max_delay
+    desc: "Delay máximo en segundos"
+  - name: backoff_factor
+    desc: "Factor multiplicativo para exponential backoff"
+  - name: jitter
+    desc: "Si True, añade variabilidad al delay"
+  - name: exceptions
+    desc: "Tupla de tipos de excepción a reintentar"
+  - name: on_retry
+    desc: "Callback opcional para logging de reintentos"
+output: "Decorador que envuelve función async con lógica de retry"
 tested: true
 tests:
  - "async funcion que falla dos veces y luego exito"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re, hashlib]
+params:
+  - name: text
+    desc: "Texto a convertir en nombre seguro para filesystem"
+  - name: max_length
+    desc: "Longitud máxima permitida del resultado"
+output: "String sanitizado apto para usar en paths y nombres de archivos"
 tested: true
 tests:
  - "texto normal produce slug con underscores"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: content
+    desc: "Contenido grande a dividir"
+  - name: max_tokens
+    desc: "Límite máximo de tokens por chunk"
+  - name: max_chars
+    desc: "Límite máximo de caracteres por chunk"
+output: "Lista de strings donde cada string es un chunk que respeta ambos límites"
 tested: true
 tests:
  - "contenido corto produce una sola parte"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: text
+    desc: "Texto a dividir en chunks"
+  - name: chunk_size
+    desc: "Tamaño objetivo de cada chunk en caracteres"
+  - name: overlap
+    desc: "Número de caracteres a solapar entre chunks consecutivos"
+output: "Lista de strings donde cada uno es un chunk con solapamiento"
 tested: true
 tests: ["texto corto cabe en 1 chunk", "texto largo con oraciones corta en punto", "texto cjk con separador ideografico", "texto sin separadores corta en chunk size exacto", "overlap funciona", "texto vacio retorna lista vacia"]
 test_file_path: "python/functions/core/split_text_into_chunks_test.py"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: text
+    desc: "String posiblemente envuelto en markdown code block"
+output: "String con los delimitadores ```json/``` removidos si estaban presentes"
 tested: true
 tests: ["JSON sin codeblock no cambia", "JSON con wrapper ```json es desenvuelto", "JSON con wrapper ``` solo es desenvuelto", "texto que no es JSON pasa sin cambio"]
 test_file_path: "python/functions/core/strip_markdown_codeblock_test.py"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: text
+    desc: "String posiblemente con tags <think>...</think>"
+output: "String con los think tags removidos"
 tested: true
 tests: ["texto sin tags no cambia", "texto con think tags los remueve", "tags multilinea son removidos", "multiples tags son removidos"]
 test_file_path: "python/functions/core/strip_think_tags_test.py"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [threading]
+params:
+  - name: key
+    desc: "Clave de traducción con dot-path notation (ej: 'report.done')"
+  - name: locale
+    desc: "Locale a usar (default: usa locale thread-local)"
+  - name: kwargs
+    desc: "Variables para interpolación en el template"
+output: "String traducido e interpolado, o la key si no se encuentra traducción"
 tested: true
 tests: ["key existente retorna traduccion", "key inexistente retorna la key", "interpolacion de variables", "dot-path profundo", "fallback a locale default"]
 test_file_path: "python/functions/core/t_test.py"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "Lista de la que tomar elementos"
+  - name: n
+    desc: "Número de elementos a tomar desde el inicio"
+output: "Lista con los primeros n elementos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,8 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [threading, uuid, datetime]
+params: []
+output: "Instancia singleton thread-safe para gestionar tareas de larga duración"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: rows
+    desc: "Lista de diccionarios a serializar como CSV"
+  - name: columns
+    desc: "Lista opcional de nombres de columnas (orden y filtrado)"
+  - name: delimiter
+    desc: "Carácter delimitador para campos"
+  - name: include_header
+    desc: "Si True, incluye fila de encabezados"
+output: "String con datos en formato CSV válido (RFC 4180)"
 tested: true
 tests:
  - "lista simple csv con header"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["json"]
+params:
+  - name: rows
+    desc: "Lista de diccionarios a serializar"
+output: "String en formato JSON Lines (newline-delimited JSON)"
 tested: true
 tests:
  - "lista de dicts jsonl"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: name
+    desc: "String en cualquier formato de naming (snake_case, camelCase, kebab-case, etc.)"
+output: "String convertido a PascalCase, o 'Unknown' si está vacío"
 tested: true
 tests:
  - "snake_case"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: structure
+    desc: "Árbol jerárquico con estructura anidada"
+output: "Lista plana de nodos en orden DFS (depth-first search)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "Lista potencialmente con elementos duplicados"
+output: "Lista sin duplicados preservando orden de primera aparición"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: url
+    desc: "String con URI SSH de git a validar (formato git@host:path)"
+output: "None si la URI es válida, lanza ValueError si es inválida"
 tested: true
 tests:
  - "URI valida"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: data
+    desc: "Diccionario a validar contra el schema"
+  - name: schema
+    desc: "Esquema JSON Schema (subset practico)"
+output: "Tupla (válido: bool, errores: list[str]) con lista de errores si hay"
 tested: true
 tests:
  - "schema simple con types y required"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "Estructura árbol a la que añadir IDs"
+  - name: node_id
+    desc: "Contador inicial para los IDs (default: 0)"
+output: "Próximo contador a usar después de asignar IDs"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "Primera lista a combinar"
+  - name: ys
+    desc: "Segunda lista a combinar"
+  - name: fn
+    desc: "Función que combina elementos: fn(x, y)"
+output: "Lista de resultados combinados, longitud igual a la lista más corta"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [re]
+params:
+  - name: input_str
+    desc: "string a analizar en busca de patrones de SQL injection"
+output: "tupla (is_threat, pattern) indicando si se detectó amenaza y el nombre del patrón"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math, collections]
+params:
+  - name: data
+    desc: "bytes cuya entropia de Shannon se desea calcular"
+output: "valor float de entropia entre 0 y 8 bits por byte"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [cryptography, struct]
+params:
+  - name: ciphertext
+    desc: "datos cifrados con envelope_encrypt o datos sin cifrar (passthrough si no comienzan con magic OVE1)"
+  - name: master_key
+    desc: "clave maestra KEK de 32 bytes para descifrar la file key"
+output: "bytes desencriptados, o bytes sin modificar si el magic no es OVE1"
 tested: true
 tests:
  - "decrypt de datos cifrados"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [cryptography, secrets, struct]
+params:
+  - name: plaintext
+    desc: "datos a cifrar con AES-256-GCM"
+  - name: master_key
+    desc: "clave maestra KEK de 32 bytes para cifrar la file key"
+output: "envelope binario con magic b'OVE1' conteniendo datos cifrados"
 tested: true
 tests:
  - "encrypt → decrypt roundtrip"
--- a/Show More
+++ b/Show More