feat(infra): auto-commit con 56 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-21 14:22:55 +02:00
parent c1071a82b3
commit 32c7336bf6
56 changed files with 5307 additions and 100 deletions
@@ -0,0 +1,78 @@
+---
+name: query_osint_db
+kind: function
+lang: py
+domain: datascience
+version: "1.0.0"
+purity: impure
+signature: "def query_osint_db(sql: str, base_url: str = 'http://127.0.0.1:8771', timeout: int = 30) -> dict"
+description: "Ejecuta un SELECT contra el service osint_db (DuckDB, FastAPI single-writer en 127.0.0.1:8771) por HTTP POST a /api/query y devuelve {status, columns, rows, row_count} sin lanzar. Normaliza service caido a un error claro."
+tags: [duckdb, osint, http, query, readonly]
+params:
+  - name: sql
+    desc: "Sentencia SQL a ejecutar. Pensada para SELECT read-only; el osint_db la corre con una conexion DuckDB en modo solo lectura, asi que una escritura falla a nivel de service."
+  - name: base_url
+    desc: "URL base del service osint_db. Default 'http://127.0.0.1:8771'. Se le anade '/api/query' al hacer el POST."
+  - name: timeout
+    desc: "Timeout por peticion en segundos (default 30). El osint_db es local (loopback): si tarda mas, mejor degradar que colgar al llamante."
+output: "dict. En exito reenvia el cuerpo del service: {status:'ok', columns:[str,...], rows:[{col:val,...},...], row_count:int, truncated:bool}. En error (sin lanzar): {status:'error', error:str}. Service inalcanzable -> error 'osint_db service not reachable on <url>: <detalle>'."
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: true
+tests: ["test_query_ok_devuelve_cuerpo_del_service", "test_query_error_de_dominio_se_reenvia", "test_service_caido_devuelve_error_claro", "test_base_url_custom_se_respeta", "test_http_error_con_cuerpo_json_se_reenvia"]
+test_file_path: "python/functions/datascience/query_osint_db_test.py"
+file_path: "python/functions/datascience/query_osint_db.py"
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join("python", "functions"))
+from datascience.query_osint_db import query_osint_db
+
+res = query_osint_db("SELECT COUNT(*) FROM personas")
+# {'status': 'ok', 'columns': ['count_star()'], 'rows': [{'count_star()': 545}],
+#  'row_count': 1, 'truncated': False}
+print(res["rows"])
+```
+
+Lanzable directo:
+
+```bash
+./fn run query_osint_db_py_datascience
+# o pasandole el SQL como arg:
+python/.venv/bin/python3 python/functions/datascience/query_osint_db.py "SELECT COUNT(*) FROM personas"
+```
+
+## Cuando usarla
+
+Cuando necesites leer la verdad OSINT que vive en el service osint_db (DuckDB, fuente
+de verdad del proyecto osint: personas, dominios, network_scans, etc.). Sustituye el
+patron inline repetido `curl -s -X POST 127.0.0.1:8771/api/query ...` por una sola
+llamada con retorno estructurado. Usala antes de escribir un heredoc/curl a mano
+contra ese endpoint.
+
+## Gotchas
+
+- El service `osint_db` debe estar arriba (escucha en `127.0.0.1:8771`). Si esta
+  caido, la funcion NO lanza: devuelve `{status:'error', error:'osint_db service not
+  reachable on <url>: ...'}`. Comprueba el status antes de leer `rows`.
+- `osint_db` es **single-writer**: el endpoint `/api/query` es estrictamente
+  read-only (abre una conexion DuckDB read_only separada). Desde aqui usa **solo
+  SELECT** — una escritura fallara a nivel de service.
+- El service responde **siempre HTTP 200**; el status real del dominio viaja en el
+  cuerpo (`status: 'ok'|'error'`). La funcion reenvia ese cuerpo tal cual en exito.
+- El `max_rows` del service tiene tope (default 500, max 10000); para volcados
+  grandes pagina o usa la maestra directamente.
+
+## Notas
+
+Solo stdlib (urllib, json): wrapper de transporte puro, sin dependencias de runtime.
+Sigue la convencion de retorno de `pg_query_py_infra` y `duckdb_query_readonly`
+(`{status:'ok'|'error', ...}`). El service osint_db vive en
+`projects/osint/apps/osint_db/` y su `/api/query` delega en `duckdb_query_readonly`.