Pretensor

Pretensor OSS

Pretensor OSS inspecciona PostgreSQL y Snowflake, con soporte opcional para el conector de BigQuery, construye un grafo de conocimiento Kuzu de tablas, columnas, claves foráneas, uniones inferidas y metadatos relacionados, y expone ese grafo a herramientas de IA a través de un servidor MCP (Model Context Protocol). Los agentes consultan el contexto del esquema y buscan sin emitir SQL crudo contra tu almacén de grafos.

Estado: Beta. Pretensor está en PyPI como pretensor; 0.1.0 es la primera versión no alfa. Las banderas de CLI, las herramientas MCP y el esquema del grafo pueden cambiar entre versiones menores. Fija versiones exactas hasta 1.0.0. Consulta docs/releases.md para la política de versionado.

¿Para quién es esto?

• Analistas de datos que usan IA para explorar almacenes de datos.
• Ingenieros de datos cansados de copiar y pegar DDLs en el chat.
• Arquitectos de datos que necesitan contexto de esquema fundamentado para agentes.
• Cualquiera que alimente esquemas de bases de datos a un LLM manualmente.

Requisitos previos

• Python 3.11 o 3.12 (3.13 aún no probado).
• Una base de datos accesible para pretensor index. Cada controlador de base de datos se distribuye como un extra: PostgreSQL vía pretensor[postgres], Snowflake vía pretensor[snowflake], BigQuery vía pretensor[bigquery].

Instalación

# Indexing PostgreSQL? Install the postgres extra:
pip install 'pretensor[postgres]'
# or, inside a uv-managed environment:
uv pip install 'pretensor[postgres]'

Aviso: los controladores de base de datos no están incluidos en la instalación base. Una instalación simple de pip install pretensor instala la CLI y el servidor MCP pero ningún controlador de base de datos. pretensor index postgresql://… fallará en el momento de la conexión con Postgres connector requires psycopg2. Install the Postgres extra: pip install 'pretensor[postgres]' (o pip install psycopg2-binary). Instala el extra que coincida con tu base de datos (postgres, snowflake, bigquery o mysql), o pretensor[all-connectors] para todos ellos.

Las funciones opcionales se exponen como extras:

Extra	Añade	Úsalo cuando
pretensor[postgres]	psycopg2-binary	Estás indexando PostgreSQL. Requerido: una instalación simple no tiene controlador de Postgres.
pretensor[snowflake]	snowflake-sqlalchemy	Estás indexando un almacén de Snowflake.
pretensor[bigquery]	google-cloud-bigquery	Estás indexando BigQuery.
pretensor[clustering]	leidenalg	Quieres detección de comunidades Leiden durante la indexación. Sin esto, Pretensor recurre a igraph Louvain (funciona, pero sin ajuste de resolución).
pretensor[embeddings]	onnxruntime, transformers, huggingface-hub, numpy	Quieres embeddings ONNX locales (Snowflake/snowflake-arctic-embed-xs, 384-dim). Con el extra instalado, pretensor index calcula embeddings de tablas automáticamente (opta por no hacerlo con --no-embeddings o PRETENSOR_EMBEDDINGS_DISABLED=1), la herramienta MCP semantic_search ejecuta clasificación por similitud coseno contra los vectores de tablas indexados, y la herramienta query gana un rerank híbrido BM25+coseno RRF. Los pases experimentales conscientes de embeddings de la capa de inteligencia (mezcla de clústeres, voto de clasificación de roles, uniones candidatas semánticas) siguen siendo alternativas de configuración opt-in. Sin el extra, semantic_search sigue registrada pero devuelve un envoltorio estructurado fallback_bm25; la salida heurística es byte-idéntica a versiones anteriores.

Combina extras con separación por comas, p. ej. pip install 'pretensor[postgres,clustering]'.

Pruébalo sin instalar:

uvx --from pretensor pretensor --help

Una nota sobre versiones. Desde 0.1.0 en adelante, pip install pretensor simple se resuelve a la última versión no alfa, y las pre-versiones requieren --pre (p. ej. pip install --pre pretensor). Fija una versión específica (p. ej. pretensor==<version>) si quieres una instalación determinista. Consulta la insignia de PyPI arriba para la última versión.

Si quieres hackear Pretensor en lugar de usarlo, consulta la configuración para colaboradores en CONTRIBUTING.md para el flujo de git clone + make install.

Inicio rápido

pip install 'pretensor[postgres]'
pretensor init

init encuentra tu conexión de base de datos, la indexa, vincula tu código y registra pretensor con Claude o Cursor. ¿Prefieres manejarlo tú mismo? Cada paso sigue siendo una bandera: consulta guides/quickstart.md.

Escanea código de aplicación (analyze)

pretensor analyze path/to/service-repo --connection mydb

analyze escanea los archivos Python (.py) y SQL (.sql) de un repositorio: extrae literales de cadena SQL del código fuente Python vía el AST de la biblioteca estándar (no se ejecuta código) y lee archivos .sql simples completos, resuelve las referencias de tablas de cada declaración con sqlglot, y vincula el código emisor con las tablas coincidentes en el grafo como consumidores externos: servicio, archivo, rango de líneas, operación de lectura/escritura y una puntuación de confianza. El texto SQL crudo nunca se almacena, solo una huella digital. Los resultados alimentan la herramienta MCP consumers y enriquecen impact, para que un agente pueda responder "¿qué servicios consumen esta tabla?" con procedencia.

Banderas útiles: --service etiqueta el repositorio escaneado (por defecto usa el nombre del directorio), --default-schema establece el esquema asumido para nombres de tablas no calificados, --dry-run previsualiza sin escribir, --json emite un resumen legible por máquina. Un comentario # noqa: pretensor-analyze en o sobre una declaración la excluye.

Herramientas MCP

Nombre	Rol
list_databases	Lista conexiones de base de datos indexadas con conteos de tablas y antigüedad.
schema	Inspecciona etiquetas de nodos, tipos de aristas y propiedades disponibles antes de escribir Cypher.
query	Búsqueda de palabras clave BM25 sobre metadatos de tablas y entidades. Rerank híbrido BM25 + coseno RRF cuando [embeddings] está instalado y las tablas tienen vectores.
semantic_search	Clasificación por coseno sobre embeddings SchemaTable indexados. Requiere pretensor[embeddings]; devuelve un envoltorio estructurado de respaldo BM25 cuando el extra está ausente o no se han incrustado tablas.
cypher	Cypher de Kuzu de solo lectura para una base de datos indexada; las cláusulas de mutación se rechazan.
context	Contexto completo para una tabla física, incluyendo columnas, uniones, linaje y metadatos de clúster. Cada relación lleva procedencia confidence + source. El argumento opcional include_similar muestra vecinos más cercanos entre clústeres cuando hay embeddings presentes.
traverse	Rutas de unión entre dos tablas físicas. Cada paso lleva procedencia confidence + source. Cuando es ambiguo y las tablas tienen embeddings, clasifica rutas empatadas por similitud de embeddings.
impact	Tablas posteriores alcanzables desde una tabla vía aristas de FK y uniones inferidas. Cada tabla alcanzada lleva los consumidores de código externos encontrados por pretensor analyze.
consumers	Ubicaciones de código externas (servicio, archivo, rango de líneas, operación de lectura/escritura, confianza) que consumen una tabla, desde pretensor analyze.
detect_changes	Compara el esquema de base de datos en vivo con la última instantánea indexada sin mutar el grafo.
compile_metric	Compila YAML de capa semántica en SQL validado para una base de datos indexada. La cadena de error incluye una lista de sugerencias "¿quisiste decir: …?" cuando una métrica, tabla o nombre de columna no resuelto tiene coincidencias cercanas.
validate_sql	Valida SQL contra el grafo indexado antes de la ejecución.

Confianza y procedencia de uniones

context (por relación) y traverse (por paso de ruta) ambos informan cómo se derivó una unión, para que un agente pueda decidir cuánto confiar en ella antes de escribir SQL:

• confidence — una puntuación de 0.0–1.0. Las claves foráneas declaradas siempre reportan 1.0; las uniones inferidas llevan la puntuación producida por el pase que las encontró.
• source — cómo se derivó la unión:
  • declared_fk — una restricción de clave foránea real en la base de datos. Siempre confianza 1.0.
  • heuristic — inferida de convenciones de nomenclatura y superposición de tipos de columna.
  • llm_inferred — inferida por un pase de LLM sobre metadatos de esquema.
  • embedding — inferida de similitud de vectores entre descripciones de columna/tabla.
  • statistical — un candidato heurístico o de LLM cuya confianza fue re-puntuada usando superposición de valores muestreados; la fuente de hipótesis original se pliega en este valor una vez que el pase estadístico lo ajusta.
  • entity_link — pasos de puente entre bases de datos en traverse derivados de un enlace SAME_ENTITY confirmado, no una unión dentro de la misma base de datos.
• reasoning — una justificación corta y legible por humanos opcional para uniones inferidas (ausente para FKs declaradas, donde la restricción misma es la justificación).

Los agentes deberían preferir declared_fk y aristas de alta confianza al componer SQL, y tratar la confianza por debajo de 0.5 como especulativa — verifica con validate_sql (o inspecciona reasoning) antes de confiar en ella.

Adaptadores de frameworks de agentes

Los agentes que no se ejecutan sobre MCP aún pueden acceder a las herramientas del grafo. Pretensor expone schema, context, traverse, impact, query y validate_sql como objetos de herramienta nativos para LangChain, LlamaIndex y Google ADK. No se requiere un proceso de servidor MCP. Los adaptadores llaman a las mismas funciones subyacentes que usa el servidor MCP, por lo que la salida es idéntica.

from pathlib import Path
from pretensor.integrations import load_langchain_tools  # or load_llamaindex_tools, load_adk_tools

tools = load_langchain_tools(Path(".pretensor"))

Instala el extra correspondiente (pretensor[langchain], pretensor[llama-index] o pretensor[google-adk]). El archivo docs/agent-framework-adapters.md tiene un ejemplo completo por framework.

Arquitectura

src/pretensor/ está organizado por subsistema:

• connectors/: introspección específica de base de datos (PostgreSQL, Snowflake, BigQuery)
• core/: almacén de grafos Kuzu, escritura de esquema, descubrimiento de relaciones
• intelligence/: inteligencia de grafos determinista (clasificación, agrupamiento, precomputación de rutas de unión; el código de plantillas de métricas existe pero no es parte del flujo de indexación OSS por defecto)
• enrichment/: pases opcionales de enriquecimiento de grafos (manifiesto dbt, escáner de código analyze)
• mcp/: servidor MCP, herramientas, recursos
• cli/: CLI de Typer (init, index, reindex, analyze, serve, list, quickstart, export, validate, sync-grants, add, remove, más el grupo de subcomandos semantic)

Estado

Pretensor es software temprano:

• El paquete en PyPI se llama pretensor. 0.1.0 es la primera versión no alfa; las pre-versiones publicadas después requieren --pre para instalarse.
• No hay garantía de estabilidad SemVer antes de 1.0.0, por lo que las banderas de CLI, las herramientas MCP y el esquema del grafo pueden cambiar entre versiones. Fija versiones exactas.
• Prueba las actualizaciones en un entorno de staging antes del uso en producción.

Progreso y notas de versión: CHANGELOG.md.

Contribuciones

Consulta CONTRIBUTING.md. Problemas de seguridad: consulta SECURITY.md.

Pruebas

make verify

También hay comandos individuales disponibles:

make test      # pytest
make lint      # ruff check
make typecheck # pyright

Licencia

MIT: consulta LICENSE.