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,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["collections"]
+params:
+  - name: rows
+    desc: "lista de dicts donde cada dict representa una fila (ej: [{'dept': 'eng', 'salary': 100}, ...])"
+  - name: group_by
+    desc: "lista de nombres de columnas para agrupar (ej: ['dept']). Pueden ser multiples columnas."
+  - name: aggs
+    desc: "dict de columna -> funcion de agregacion (ej: {'salary': 'mean'}). Soporta: sum, mean, count, min, max, first, last, collect"
+output: "lista de dicts donde cada dict es un grupo con sus resultados de agregacion"
 tested: true
 tests:
  - "Group by una columna con sum"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "lista de valores numericos de una serie temporal (ej: precios diarios, cantidades de eventos)"
+  - name: lag
+    desc: "numero de periodos para desplazar (ej: 1 para autocorrelacion con el valor anterior). Debe ser positivo."
+output: "coeficiente de autocorrelacion normalizado en rango [-1, 1]. 1.0=correlacion perfecta, 0.0=sin correlacion"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: entity_presets
+    desc: "lista de dicts describiendo tipos de entidad (ej: [{'type_ref': 'osint_person_go_cybersecurity', 'label': 'Person', 'metadata_fields': ['name', 'alias']}])"
+output: "string con seccion del system prompt describiendo los entity types en formato legible para LLM"
 tested: true
 tests:
  - "lista con varios presets"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: relation_types
+    desc: "lista de nombres de tipos de relacion permitidos (ej: ['funds', 'employs', 'owns', 'communicates_with'])"
+output: "string con una linea describiendo los tipos de relacion permitidos en formato legible para LLM"
 tested: true
 tests:
  - "lista con varios tipos"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "lista de valores numericos a recortar"
+  - name: lo
+    desc: "limite inferior (minimo permitido). Valores menores seran reemplazados por lo."
+  - name: hi
+    desc: "limite superior (maximo permitido). Valores mayores seran reemplazados por hi."
+output: "lista de valores con todos los elementos recortados al rango [lo, hi]"
 tested: false
 tests: []
 test_file_path: ""
@@ -19,6 +19,14 @@ returns_optional: false
 error_type: ""
 imports:
  - uuid
+params:
+  - name: candidates
+    desc: "lista de EntityCandidate a deduplicar. Cada uno tiene name, type_ref, confidence."
+  - name: name_threshold
+    desc: "umbral de similitud para fuzzy matching de nombres en rango [0, 1] (tipico: 0.85). Mayor = mas estricto."
+  - name: same_type_only
+    desc: "si True, solo mergea candidatos con el mismo type_ref. Si False, mergea por similitud ignoring tipo."
+output: "DeduplicationResult con entidades mergeadas, mapas de resolucion de IDs (name_to_id) y log de merges realizados"
 tested: true
 tests:
  - "John Smith y Smith, John se mergean"
@@ -16,6 +16,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: relations
+    desc: "lista de RelationCandidate con from_name, to_name, relation_type, description, confidence"
+  - name: entity_id_map
+    desc: "dict producido por deduplicate_entities mapando nombres mergeados a IDs canonicos (ej: {'john smith': 'entity_001'})"
+output: "lista de RelationCandidate deduplicadas, con from_id y to_id resueltos al entity_id_map, sin self-loops"
 tested: true
 tests:
  - "dos relaciones identicas se colapsan en una"
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math]
+params:
+  - name: history
+    desc: "lista de dicts con metricas historicas (ej: [{'records_out': 100, 'duration_ms': 500}, ...])"
+  - name: current
+    desc: "dict con metricas actuales a comparar (ej: {'records_out': 50, 'duration_ms': 2000})"
+  - name: fields
+    desc: "lista de nombres de campos a monitorizar en current vs history (ej: ['records_out', 'duration_ms'])"
+  - name: threshold
+    desc: "umbral de z-score para declarar drift (tipico: 2.0-3.0). Mayor = menos sensible."
+output: "lista de dicts con {field, current, mean, std, z_score, drifted} para cada campo monitoreado"
 tested: true
 tests:
  - "campo con drift claro (z > threshold)"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math]
+params:
+  - name: data
+    desc: "lista de valores numericos para detectar outliers"
+  - name: threshold
+    desc: "umbral de z-score absoluto (tipico: 2.0 para 95% confianza, 3.0 para 99%). Mayor = menos sensible."
+output: "lista de booleanos paralela a data, True donde |z-score| > threshold"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,18 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: before
+    desc: "lista de dicts con entities antes de cambios (ej: [{'id': '1', 'name': 'Alice', 'status': 'active'}, ...])"
+  - name: after
+    desc: "lista de dicts con entities despues de cambios, misma estructura que before"
+  - name: key
+    desc: "nombre del campo que identifica cada entity (tipico: 'id'). Debe existir en todas las entities."
+  - name: ignore_fields
+    desc: "lista opcional de campos a ignorar en la comparacion (ej: ['created_at', 'updated_at'])"
+  - name: compare_fields
+    desc: "lista opcional de campos SOLO a comparar (si se da, tiene prioridad sobre ignore_fields)"
+output: "dict con {added, removed, modified, unchanged, summary} describiendo los cambios campo a campo"
 tested: true
 tests:
  - "entity añadida"
@@ -14,6 +14,18 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: before
+    desc: "lista de dicts con relaciones antes (ej: [{'source_id': 'A', 'target_id': 'B', 'relation_type': 'knows', 'weight': 1.0}, ...])"
+  - name: after
+    desc: "lista de dicts con relaciones despues, misma estructura que before"
+  - name: key
+    desc: "tupla de 3 nombres de campo que forman la identidad de una relacion (defecto: ('source_id', 'target_id', 'relation_type'))"
+  - name: ignore_fields
+    desc: "lista opcional de campos a ignorar en comparacion (ej: ['timestamp'])"
+  - name: compare_fields
+    desc: "lista opcional de campos SOLO a comparar (si se da, prioridad sobre ignore_fields)"
+output: "dict con {added, removed, modified, unchanged} describiendo cambios en relaciones"
 tested: true
 tests:
  - "relacion añadida"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [numpy, scipy]
+params:
+  - name: arrivals
+    desc: "lista de conteos de eventos por periodo (ej: [0, 1, 3, 2, 0, 1, ...] eventos por tick). Reflect actividad temporal."
+  - name: max_lag
+    desc: "numero maximo de lags para calcular autocorrelacion (tipico: 30). Mayor = mas precision pero mas ruido."
+output: "dict con {alpha, beta, branching_ratio, acf} estimados parametros del proceso Hawkes"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [numpy]
+params:
+  - name: values
+    desc: "lista de valores numericos positivos donde se sospecha cola pesada (ej: tamanios de ordenes, ingresos). Debe haber >10 valores."
+  - name: x_min_percentile
+    desc: "percentil a partir del cual considerar la cola (tipico: 90.0 para considerar el 10% superior)"
+output: "dict con {alpha, x_min, n_tail} donde alpha es el exponente estimado (menor = cola mas pesada)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [warnings, typing.Callable]
+params:
+  - name: text
+    desc: "texto fuente para extraccion (ej: documento, parrafo, chunk de OSINT). Puede contener multiples entidades."
+  - name: entity_schema
+    desc: "lista de dicts describiendo tipos validos (ej: [{'type_ref': 'osint_person_go_cybersecurity', 'label': 'Person'}])"
+  - name: llm_chat_json
+    desc: "callable que toma list[dict] con messages OpenAI-format y retorna dict con clave 'entities'. Inyeccion de dependencia del LLM."
+  - name: language_instruction
+    desc: "instruccion de lenguaje para el LLM (defecto: 'Respond in English.'). Ej: 'Responde en Español.'"
+output: "lista de EntityCandidate extraidas, cada una con name, type_ref, confidence, atributos"
 tested: true
 tests:
  - "texto con entidades claras retorna EntityCandidate"
@@ -17,6 +17,18 @@ returns:
 returns_optional: false
 error_type: "error_go_core"
 imports: [logging, sys, os, typing]
+params:
+  - name: text
+    desc: "texto fuente para extraccion de relaciones entre entidades (ej: documento OSINT, parrafo descriptivo)"
+  - name: entities
+    desc: "lista de EntityCandidate ya extraidas (ej: output de extract_entities_llm). Valida que las relaciones refieran entidades reales."
+  - name: relation_types
+    desc: "lista de nombres de relacion permitidos (ej: ['employs', 'funds', 'owns']). No permitidas se remapean a 'related_to'."
+  - name: llm_chat_json
+    desc: "callable que toma list[dict] mensajes y retorna dict con clave 'relations'. Inyeccion de dependencia del LLM."
+  - name: language_instruction
+    desc: "instruccion de lenguaje para el LLM (defecto: 'Respond in English.')"
+output: "lista de RelationCandidate con from_name, to_name, relation_type, description, confidence"
 tested: true
 tests:
  - "texto con dos entidades relacionadas"
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "lista de valores numericos para agrupar en buckets"
+  - name: buckets
+    desc: "numero de buckets a crear (ej: 5, 10, 100). Mayor = histograma mas detallado."
+output: "lista de conteos con len(resultado) == buckets, cada elemento es el numero de valores en ese bucket"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,16 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math, datetime]
+params:
+  - name: active_count
+    desc: "numero de accesos/activaciones de un item (ej: 150 views). Mayor count = score mas alto."
+  - name: updated_at
+    desc: "datetime de la ultima actualizacion. Si None, retorna siempre 0.0."
+  - name: now
+    desc: "datetime actual (defecto: ahora). Usar parametro explicitamente para tests deterministas."
+  - name: half_life_days
+    desc: "vida media para el decaimiento exponencial (defecto: 7.0 dias). Menor = decaimiento mas rapido."
+output: "hotness score en rango [0, 1]. Combina frecuencia (active_count) y recencia (dias desde updated_at)."
 tested: true
 tests:
  - "active_count=0, updated_at reciente"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math]
+params:
+  - name: data
+    desc: "lista de valores numericos con posibles None o NaN que requieren imputacion"
+output: "lista de misma longitud con None y NaN reemplazados por la media de los valores validos"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: start
+    desc: "valor inicial del rango (ej: 0.0)"
+  - name: stop
+    desc: "valor final del rango, incluido (ej: 1.0)"
+  - name: num
+    desc: "numero de puntos a generar (ej: 5). Si num=1, retorna [start]."
+output: "lista de num valores equiespaciados entre start y stop (ambos inclusive)"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,18 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: rows
+    desc: "lista de dicts en formato ancho (ej: [{'region': 'US', 'q1': 10, 'q2': 20}])"
+  - name: id_vars
+    desc: "lista de columnas a mantener como identificadores (ej: ['region']). No se derriten."
+  - name: value_vars
+    desc: "lista de columnas a derretir (ej: ['q1', 'q2']). Si None, derrite todas excepto id_vars."
+  - name: var_name
+    desc: "nombre de la columna que contendra los nombres de columnas derretidas (defecto: 'variable')"
+  - name: value_name
+    desc: "nombre de la columna que contendra los valores (defecto: 'value')"
+output: "lista de dicts en formato largo, donde cada id_var + value_var genera una fila"
 tested: true
 tests:
  - "Melt basico"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [sys, os]
+params:
+  - name: graphs
+    desc: "lista de grafos, cada uno con estructura {entities: [...], relations: [...]}"
+  - name: entity_key
+    desc: "campo de entity que se usa para fuzzy matching (defecto: 'name'). Determina similitud."
+  - name: similarity_threshold
+    desc: "umbral de similitud Levenshtein normalizado [0, 1] para mergear (tipico: 0.85). Mayor = mas estricto."
+output: "dict con estructura {entities: [...], relations: [...], merge_log: [...]}, grafo mergeado y deduplicado"
 tested: true
 tests:
  - "dos grafos con entity duplicada → merge"
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: data
+    desc: "lista de valores numericos a normalizar en el rango [0, 1]"
+output: "lista de valores escalados al rango [0, 1] usando min-max normalization. Min->0, Max->1, valores intermedios proporcionales."
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [json, sqlite3]
+params:
+  - name: db_path
+    desc: "path a operations.db (ej: 'apps/my_analysis/operations.db')"
+  - name: namespace
+    desc: "prefijo URI para formar IRIs (defecto: 'http://osint.local/'). Ej: 'http://mi-empresa.com/osint/'"
+output: "lista de tuplas (subject, predicate, object) en formato RDF. Subjects y objetos son URIs con namespace, predicados son literales."
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [json, sqlite3]
+params:
+  - name: db_path
+    desc: "path a operations.db (ej: 'apps/my_analysis/operations.db')"
+output: "dict con estructura {nodes: [...], edges: [...]} compatible con sigma.js/graphology. Nodos tienen id, label, color, size, type."
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math]
+params:
+  - name: xs
+    desc: "lista de valores numericos de la primera variable (ej: [1, 2, 3])"
+  - name: ys
+    desc: "lista de valores numericos de la segunda variable, misma longitud que xs"
+output: "coeficiente de correlacion de Pearson en rango [-1, 1]. 1.0=correlacion perfecta positiva, -1.0=negativa, 0.0=sin correlacion"
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,18 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: ["collections"]
+params:
+  - name: rows
+    desc: "lista de dicts en formato largo (ej: [{'region': 'US', 'product': 'A', 'sales': 10}, ...])"
+  - name: index
+    desc: "columna que sera el indice de filas en la tabla pivote (ej: 'region'). Valores unicos -> filas."
+  - name: columns
+    desc: "columna cuyos valores unicos se expanden como nuevas columnas (ej: 'product'). Valores unicos -> columnas."
+  - name: values
+    desc: "columna con los valores a agregar en las celdas (ej: 'sales')"
+  - name: agg
+    desc: "funcion de agregacion si hay multiples valores por celda (defecto: 'sum'). Otras: count, mean, min, max, first, last."
+output: "lista de dicts en formato ancho, donde el indice y las columnas expandidas forman el schema"
 tested: true
 tests:
  - "Pivot basico con sum"
@@ -14,6 +14,14 @@ returns: []
 returns_optional: false
 error_type: "error_go_core"
 imports: [json, os]
+params:
+  - name: graph_data
+    desc: "dict en formato sigma.js con {nodes: [...], edges: [...]} (ej: output de ops_to_sigma_json_py_datascience)"
+  - name: output_path
+    desc: "path absoluto donde guardar el HTML (ej: '/tmp/osint_graph.html'). Directorio debe existir."
+  - name: title
+    desc: "titulo del grafo que aparece en la visualizacion (defecto: 'OSINT Graph')"
+output: "string con el path absoluto del archivo HTML escrito. Archivo es standalone y abre en cualquier navegador."
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,12 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: []
+params:
+  - name: xs
+    desc: "lista de valores para crear ventanas (ej: [1, 2, 3, 4, 5])"
+  - name: size
+    desc: "tamanio de cada ventana (ej: 3). Debe ser positivo y <= len(xs)."
+output: "lista de listas, cada una una ventana de tamanio size. Resultado tiene len(xs) - size + 1 ventanas."
 tested: false
 tests: []
 test_file_path: ""
@@ -14,6 +14,10 @@ returns: []
 returns_optional: false
 error_type: ""
 imports: [math]
+params:
+  - name: data
+    desc: "lista de valores numericos a estandarizar"
+output: "lista de misma longitud con datos transformados a media=0 y desviacion estandar=1 (z-scores)"
 tested: false
 tests: []
 test_file_path: ""