Referencia de tools

Energética expone 8 herramientas en tres grupos: 5 queries curadas, 2 de discovery y 1 de SQL abierto. Todas devuelven JSON serializado como texto.

Queries curadas

query_production

Producción mensual de petróleo, gas y agua por cuenca, empresa, formación y período (~18M registros).

Parámetro	Tipo	Notas
cuenca	string	Filtro por cuenca (p. ej. NEUQUINA, GOLFO SAN JORGE, CUYANA, AUSTRAL)
empresa	string	Empresa operadora (p. ej. YPF, PAN AMERICAN ENERGY, VISTA, TECPETROL)
formacion	string	Formación geológica (p. ej. VACA MUERTA, D-129, CENTENARIO)
fecha_desde	string	YYYY-MM
fecha_hasta	string	YYYY-MM
agrupar_por	enum	mes | anio | cuenca | empresa | formacion (default mes)
recurso	enum	petroleo | gas | agua | todos (default todos)

Devuelve: fecha, prod_petroleo_m3, prod_gas_miles_m3, prod_agua_m3, pozos_activos

query_wells

Búsqueda sobre ~50.000 pozos argentinos con ubicación, tipo, estado, profundidad y producción acumulada.

Parámetro	Tipo	Notas
empresa	string	Filtro por operadora (ILIKE)
cuenca	string	Filtro por cuenca
provincia	string	Provincia (NEUQUEN, CHUBUT, MENDOZA, etc.)
tipo_recurso	enum	PETROLEO | GAS | AMBOS
tipo_estado	string	Activo | Inactivo | Abandonado
formacion	string	Formación geológica
con_produccion	boolean	Sólo pozos con acumulada > 0
limit	number	1-1000 (default 100)

Devuelve: idpozo, sigla, nombre_propio, empresa, provincia, cuenca, area_concesion, formacion, tipo_pozo, tipo_estado, latitud, longitud, profundidad, petroleo_acumulado_m3, gas_acumulado_miles_m3, fecha_primera_prod

query_prices

Precios benchmark internacionales, crudo local argentino y tipos de cambio.

Parámetro	Tipo	Notas
serie	enum	Requerido. WTI, BRENT, HENRY_HUB, ESCALANTE, MEDANITO, USD_OFICIAL, USD_BLUE, USD_MEP, USD_CCL
fecha_desde	string	YYYY-MM-DD (intl/FX) o YYYY-MM (crudo local)
fecha_hasta	string	Mismo formato que fecha_desde
frecuencia	enum	diario | mensual | anual

query_investments

Inversiones upstream en Argentina por empresa, cuenca, año y concepto (MMUSD).

Parámetro	Tipo	Notas
empresa	string	Filtro por empresa (ILIKE)
cuenca	string	Filtro por cuenca
anio_desde	number	Año inicial
anio_hasta	number	Año final
concepto	string	perforacion, terminacion, infraestructura, etc.

query_trade

Balance comercial de hidrocarburos argentinos — exportaciones e importaciones de crudo, refinados y gas.

Parámetro	Tipo	Notas
anio	number	Filtro por año
flow	enum	export | import
producto	enum	crude (HS 2709) | refined (HS 2710) | gas (HS 2711)

Discovery

get_schema

Devuelve nombres de tablas, columnas, tipos, descripciones, unidades y valores de ejemplo. Usalo primero para entender qué datos hay disponibles.

Parámetro	Tipo	Notas
tabla	string	Opcional. Nombre de una tabla específica. Vacío para todas.

Cache de 1 hora (el esquema sólo cambia con el rebuild del pipeline).

get_data_freshness

Rango de fechas y conteo de registros por tabla. Sin parámetros. Cache de 1 hora.

SQL abierto

execute_sql

Abierto durante la beta. Ejecuta SQL de lectura (SELECT o WITH) contra la base DuckDB. Rate limit de 40 requests/día por IP.

Parámetro	Tipo	Notas
sql	string	Sentencia SELECT o WITH

Validación:

• Rechaza DDL/DML (DROP, ALTER, INSERT, UPDATE, DELETE, CREATE, GRANT, REVOKE)
• Bloquea patrones peligrosos (UNION, INFORMATION_SCHEMA, SLEEP, BENCHMARK, LOAD_FILE)
• Restringido al listado de tablas del catálogo
• Timeout de 30 segundos por query
• Inyecta LIMIT automáticamente (5.000-10.000 según tier) si falta

Respuestas de error

Los errores de tool devuelven isError: true con un mensaje legible:

• Timeout — la consulta excedió los 30s. Se sugiere agregar más filtros.
• Circuit breaker abierto — la BD no está disponible temporalmente.
• Validación SQL — consulta rechazada por el validador.
• Rate limit — excedido el cupo diario por IP (200/día curadas, 40/día execute_sql).