{"id":34549480,"url":"https://github.com/686f6c61/pg-index-agents","last_synced_at":"2026-04-11T06:42:38.395Z","repository":{"id":327797492,"uuid":"1109521108","full_name":"686f6c61/pg-index-agents","owner":"686f6c61","description":"Sistema de agentes inteligentes para analisis y optimizacion automatica de indices en PostgreSQL","archived":false,"fork":false,"pushed_at":"2026-04-09T08:58:40.000Z","size":1984,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-11T06:42:36.524Z","etag":null,"topics":["ai-agents","database-optimization","fastapi","langgraph","llm","nextjs","postgresql","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/686f6c61.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T23:19:29.000Z","updated_at":"2026-02-12T18:50:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/686f6c61/pg-index-agents","commit_stats":null,"previous_names":["686f6c61/pg-index-agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/686f6c61/pg-index-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/686f6c61%2Fpg-index-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/686f6c61%2Fpg-index-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/686f6c61%2Fpg-index-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/686f6c61%2Fpg-index-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/686f6c61","download_url":"https://codeload.github.com/686f6c61/pg-index-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/686f6c61%2Fpg-index-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31671629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","database-optimization","fastapi","langgraph","llm","nextjs","postgresql","python"],"created_at":"2025-12-24T07:45:53.072Z","updated_at":"2026-04-11T06:42:38.380Z","avatar_url":"https://github.com/686f6c61.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PG Index Agents\n\n[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Next.js](https://img.shields.io/badge/Next.js-15-black.svg)](https://nextjs.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14+-336791.svg)](https://www.postgresql.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)\n[![LangGraph](https://img.shields.io/badge/LangGraph-Agent_Framework-orange.svg)](https://github.com/langchain-ai/langgraph)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nSistema de agentes inteligentes para analisis y optimizacion automatica de indices en PostgreSQL.\n\nEste proyecto es una prueba de concepto que explora la aplicacion de modelos de lenguaje en tareas de administracion de bases de datos. El sistema utiliza multiples agentes especializados que colaboran para analizar, diagnosticar y proponer mejoras en la estructura de indices de una base de datos PostgreSQL.\n\n![Databases Overview](assets/PG%20Index%20Agents%2001.png)\n\n## Tabla de contenidos\n\n- [Hipotesis](#hipotesis)\n- [Arquitectura](#arquitectura)\n- [Sistema de agentes](#sistema-de-agentes)\n- [Stack tecnologico](#stack-tecnologico)\n- [Estructura del proyecto](#estructura-del-proyecto)\n- [Requisitos](#requisitos)\n- [Instalacion](#instalacion)\n- [Bases de datos de ejemplo](#bases-de-datos-de-ejemplo)\n- [Uso](#uso)\n- [API REST](#api-rest)\n- [Niveles de autonomia](#niveles-de-autonomia)\n- [Contribuciones](#contribuciones)\n- [Licencia](#licencia)\n\n---\n\n## Hipotesis\n\nLa gestion de indices en bases de datos PostgreSQL es un proceso complejo que tradicionalmente requiere expertise de administradores de bases de datos especializados. Este proyecto plantea la hipotesis de que un sistema multi-agente con capacidades de inteligencia artificial puede automatizar gran parte de este trabajo.\n\nLos objetivos especificos son:\n\n- Analizar automaticamente la estructura y patrones de uso de una base de datos\n- Detectar anomalias y oportunidades de optimizacion de indices\n- Generar propuestas de indices con justificaciones comprensibles\n- Mantener la salud de los indices existentes de forma proactiva\n- Recomendar estrategias de particionamiento para tablas de gran volumen\n\n---\n\n## Arquitectura\n\nEl sistema sigue una arquitectura cliente-servidor con separacion clara entre el backend de procesamiento y el frontend de visualizacion.\n\n```\n                                    +------------------+\n                                    |    Frontend      |\n                                    |    (Next.js)     |\n                                    +--------+---------+\n                                             |\n                                             | HTTP/REST\n                                             |\n                                    +--------v---------+\n                                    |    Backend       |\n                                    |    (FastAPI)     |\n                                    +--------+---------+\n                                             |\n                         +-------------------+-------------------+\n                         |                   |                   |\n                +--------v-------+  +--------v-------+  +--------v-------+\n                |   PostgreSQL   |  |    SQLite      |  |   OpenRouter   |\n                |   (Target DB)  |  |   (State)      |  |   (LLM API)    |\n                +----------------+  +----------------+  +----------------+\n```\n\nEl backend mantiene su estado interno en una base de datos SQLite separada, lo que permite analizar cualquier base de datos PostgreSQL sin modificarla. La comunicacion con modelos de lenguaje se realiza a traves de OpenRouter, permitiendo utilizar diferentes proveedores de LLM.\n\n---\n\n## Sistema de agentes\n\nEl sistema esta compuesto por cinco agentes especializados que trabajan de forma coordinada. Cada agente tiene un proposito especifico y genera artefactos que pueden ser consumidos por otros agentes o presentados al usuario.\n\n| Agente | Proposito | Artefactos |\n|--------|-----------|------------|\n| Explorer | Analiza la estructura de la base de datos, clasifica tablas por criticidad y detecta anomalias iniciales | Clasificaciones, grafo de dependencias, anomalias |\n| Observer | Monitorea metricas de rendimiento, analiza patrones de queries y genera senales de alerta | Senales, metricas, patrones detectados |\n| Architect | Procesa senales y anomalias para generar propuestas concretas de indices con justificaciones | Propuestas SQL, estimaciones de impacto |\n| Gardener | Mantiene la salud de indices existentes, detecta bloat y programa tareas de mantenimiento | Tareas de mantenimiento, recomendaciones |\n| Partitioner | Analiza tablas grandes para recomendar estrategias de particionamiento | Informes de particionamiento, planes de migracion |\n\n### Flujo de trabajo\n\nEl flujo tipico de analisis sigue esta secuencia:\n\n```\nExplorer --\u003e Observer --\u003e Architect --\u003e Gardener --\u003e Partitioner\n```\n\nCada agente puede ejecutarse de forma independiente, pero los resultados son mas completos cuando se ejecutan en secuencia, ya que cada uno enriquece el contexto disponible para el siguiente.\n\n![Database Dashboard](assets/PG%20Index%20Agents%2002.png)\n\nCada agente incluye informacion detallada sobre su flujo de trabajo, los datos que recopila y el output que genera:\n\n![Agent Info Modal](assets/PG%20Index%20Agents%2003.png)\n\n---\n\n## Stack tecnologico\n\n### Backend\n\nEl backend esta desarrollado en Python y utiliza las siguientes tecnologias:\n\n| Tecnologia | Version | Proposito |\n|------------|---------|-----------|\n| Python | 3.11+ | Lenguaje de programacion |\n| FastAPI | 0.100+ | Framework web asincronico |\n| SQLAlchemy | 2.0+ | ORM y conexion a bases de datos |\n| LangChain | 0.1+ | Orquestacion de modelos de lenguaje |\n| Pydantic | 2.0+ | Validacion de datos y configuracion |\n| psycopg2 | 2.9+ | Driver nativo de PostgreSQL |\n\n### Frontend\n\nEl frontend esta desarrollado en TypeScript con React y utiliza las siguientes tecnologias:\n\n| Tecnologia | Version | Proposito |\n|------------|---------|-----------|\n| Next.js | 15 | Framework React con App Router |\n| TypeScript | 5.0+ | Tipado estatico |\n| Tailwind CSS | 3.4+ | Framework de estilos utilitarios |\n| React Flow | 11+ | Visualizacion de grafos |\n| Lucide React | - | Iconografia |\n\n### Infraestructura\n\n| Componente | Proposito |\n|------------|-----------|\n| PostgreSQL 14+ | Base de datos objetivo a analizar |\n| SQLite | Almacenamiento de estado interno |\n| OpenRouter | Gateway para acceso a modelos de lenguaje |\n\n---\n\n## Estructura del proyecto\n\n```\nAgentes_Indices/\n├── backend/\n│   ├── agents/                 # Implementacion de los 5 agentes\n│   │   ├── explorer.py         # Agente de exploracion y clasificacion\n│   │   ├── observer.py         # Agente de monitoreo y senales\n│   │   ├── architect.py        # Agente de propuestas de indices\n│   │   ├── gardener.py         # Agente de mantenimiento\n│   │   └── partitioner.py      # Agente de particionamiento\n│   ├── api/\n│   │   └── routes.py           # Endpoints REST de la API\n│   ├── core/\n│   │   ├── config.py           # Configuracion y variables de entorno\n│   │   ├── database.py         # Conexiones a bases de datos\n│   │   ├── state.py            # Gestion de estado persistente\n│   │   ├── llm.py              # Integracion con modelos de lenguaje\n│   │   ├── executor.py         # Orquestador de agentes\n│   │   └── background.py       # Sistema de tareas en segundo plano\n│   ├── services/\n│   │   ├── metadata.py         # Extraccion de metadatos de PostgreSQL\n│   │   └── ai_explainer.py     # Generacion de explicaciones con IA\n│   ├── main.py                 # Punto de entrada de la aplicacion\n│   └── requirements.txt        # Dependencias Python\n├── frontend/\n│   ├── src/\n│   │   ├── app/                # Paginas de la aplicacion (App Router)\n│   │   ├── components/         # Componentes React reutilizables\n│   │   ├── hooks/              # Hooks personalizados\n│   │   └── lib/                # Utilidades y cliente API\n│   ├── package.json            # Dependencias Node.js\n│   └── tailwind.config.ts      # Configuracion de Tailwind\n├── scripts/\n│   ├── download_stackexchange.py   # Descarga de datos de Stack Exchange\n│   ├── import_stackoverflow.py     # Importacion automatica con tamanos\n│   ├── import_to_postgres.py       # Importacion de XML a PostgreSQL\n│   └── import_airbnb.py            # Importacion de datos de Airbnb\n└── start.sh                    # Script de inicio rapido\n```\n\n---\n\n## Requisitos\n\nAntes de instalar el proyecto, asegurate de tener instalados los siguientes componentes:\n\n| Requisito | Version minima | Proposito |\n|-----------|----------------|-----------|\n| PostgreSQL | 14 | Base de datos objetivo |\n| Python | 3.11 | Backend |\n| Node.js | 18 | Frontend |\n| p7zip | - | Descompresion de datos de ejemplo |\n| wget | - | Descarga de datos (opcional) |\n\nPara sistemas basados en Debian/Ubuntu, puedes instalar los requisitos con:\n\n```bash\nsudo apt update\nsudo apt install postgresql p7zip-full python3-pip nodejs npm wget\n```\n\n---\n\n## Instalacion\n\n### Clonar el repositorio\n\n```bash\ngit clone https://github.com/686f6c61/pg-index-agents.git\ncd pg-index-agents\n```\n\n### Configurar el backend\n\nEl backend requiere un entorno virtual de Python y la configuracion de variables de entorno.\n\n```bash\ncd backend\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\nCrea el archivo de configuracion copiando el ejemplo:\n\n```bash\ncp .env.example .env\n```\n\nEdita el archivo `.env` con tu configuracion:\n\n```env\n# API de OpenRouter para acceso a modelos de lenguaje\nOPENROUTER_API_KEY=tu_api_key\n\n# Conexion a la base de datos objetivo\nPG_TARGET_HOST=localhost\nPG_TARGET_PORT=5432\nPG_TARGET_DATABASE=nombre_de_tu_base_de_datos\nPG_TARGET_USER=tu_usuario\nPG_TARGET_PASSWORD=tu_password\n```\n\n### Configurar el frontend\n\n```bash\ncd frontend\nnpm install\n```\n\n### Iniciar la aplicacion\n\nPuedes iniciar ambos servicios con el script de inicio:\n\n```bash\n./start.sh\n```\n\nO iniciarlos por separado en terminales diferentes:\n\n```bash\n# Terminal 1 - Backend\ncd backend\nsource venv/bin/activate\npython main.py\n\n# Terminal 2 - Frontend\ncd frontend\nnpm run dev\n```\n\nEl backend estara disponible en `http://localhost:8000` y el frontend en `http://localhost:3000`.\n\n---\n\n## Bases de datos de ejemplo\n\nEl proyecto incluye scripts para importar tres conjuntos de datos de ejemplo que permiten probar las capacidades del sistema.\n\n### Stack Exchange (metodo rapido)\n\nEste metodo descarga automaticamente sitios de Stack Exchange de diferentes tamanos. Es la opcion recomendada para comenzar.\n\n| Tamano | Sitio | Registros aproximados |\n|--------|-------|----------------------|\n| small | coffee.stackexchange | 5,000 posts |\n| medium | dba.stackexchange | 75,000 posts |\n| large | serverfault | 350,000 posts |\n\n```bash\nsudo -u postgres createdb stackoverflow_sample\ncd backend \u0026\u0026 source venv/bin/activate\ncd ../scripts\npython import_stackoverflow.py --sample-size medium\n```\n\n### Stack Overflow completo (metodo manual)\n\nPara analisis a escala real, puedes descargar el dataset completo de Stack Overflow desde archive.org. Este metodo requiere aproximadamente 30GB de espacio en disco para la descarga y 150GB para los datos descomprimidos.\n\n```bash\ncd scripts\npython download_stackexchange.py\nsudo -u postgres createdb stackexchange\npython import_to_postgres.py\n```\n\nEl script de descarga presenta un menu interactivo con las siguientes opciones:\n\n- Full: Posts, Users, Comments, Votes, Badges, Tags (30GB)\n- Core: Posts y Users (21GB)\n- DBA Site: Sitio de administradores de bases de datos (500MB)\n- Custom: Seleccion manual de archivos\n\n### Airbnb\n\nLos datos de Inside Airbnb son utiles para probar el agente de particionamiento, ya que incluyen tablas con millones de registros.\n\n```bash\nsudo -u postgres createdb airbnb_sample\ncd scripts\npython import_airbnb.py --city amsterdam --skip-calendar\n```\n\nLa opcion `--skip-calendar` omite la tabla de calendario, que puede contener varios millones de filas.\n\n---\n\n## Uso\n\nUna vez iniciada la aplicacion, accede a `http://localhost:3000` en tu navegador.\n\n### Pantalla principal\n\nLa pantalla principal muestra las bases de datos configuradas. Haz clic en una base de datos para acceder a su panel de analisis.\n\n### Panel de base de datos\n\nEl panel de base de datos contiene las siguientes secciones:\n\n| Seccion | Descripcion |\n|---------|-------------|\n| Resumen | Estadisticas generales de la base de datos |\n| Agentes | Panel de control para ejecutar cada agente |\n| Propuestas | Lista de propuestas de indices pendientes de aprobacion |\n| Reportes | Informes detallados generados por los agentes |\n\n### Ejecucion de agentes\n\nPara ejecutar un agente, seleccionalo en el panel de agentes y haz clic en el boton de ejecucion. El agente se ejecutara en segundo plano y podras ver su progreso en tiempo real.\n\nLos resultados de cada agente se muestran en la pestana correspondiente. Las propuestas de indices generadas por el Architect requieren aprobacion manual antes de ejecutarse.\n\n### Deteccion de anomalias\n\nEl sistema detecta automaticamente anomalias como indices faltantes, indices no utilizados, e indices redundantes, clasificandolas por severidad:\n\n![Anomalies Detection](assets/PG%20Index%20Agents%2004.png)\n\n### Grafo de dependencias\n\nVisualizacion interactiva de las relaciones entre tablas, mostrando foreign keys y dependencias inferidas:\n\n![Dependencies Graph](assets/PG%20Index%20Agents%2005.png)\n\n### Senales y analisis con IA\n\nLas senales detectadas por el Observer incluyen explicaciones generadas por IA que ayudan a entender el problema y su solucion:\n\n![Signals with AI](assets/PG%20Index%20Agents%2006.png)\n\nEl analisis detallado incluye diagnostico del problema, causa raiz, solucion recomendada y justificacion tecnica:\n\n![Detailed AI Analysis](assets/PG%20Index%20Agents%2007.png)\n\n### Tareas de mantenimiento\n\nEl Gardener genera tareas de mantenimiento con explicaciones detalladas sobre por que son necesarias:\n\n![Maintenance Tasks](assets/PG%20Index%20Agents%2008.png)\n\n### Recomendaciones de particionamiento\n\nEl Partitioner analiza tablas grandes y genera recomendaciones de particionamiento con comandos SQL listos para ejecutar:\n\n![Partitioning Recommendations](assets/PG%20Index%20Agents%2009.png)\n\n### Informe ejecutivo\n\nResumen ejecutivo generado por IA con el estado general de la base de datos, hallazgos principales y prioridades recomendadas:\n\n![Executive Report](assets/PG%20Index%20Agents%2010.png)\n\n### Configuracion y datos de ejemplo\n\nLa pagina de Setup incluye instrucciones para importar bases de datos de ejemplo:\n\n![Setup Page](assets/PG%20Index%20Agents%2011.png)\n\n### Monitor de actividad\n\nPanel de monitoreo de jobs en background y logs del sistema en tiempo real:\n\n![Activity Monitor](assets/PG%20Index%20Agents%2012.png)\n\n---\n\n## API REST\n\nEl backend expone una API REST documentada con OpenAPI. Puedes acceder a la documentacion interactiva en `http://localhost:8000/docs`.\n\n### Endpoints principales\n\n| Metodo | Endpoint | Descripcion |\n|--------|----------|-------------|\n| GET | /api/databases | Lista todas las bases de datos configuradas |\n| GET | /api/databases/{id} | Obtiene detalles de una base de datos |\n| POST | /api/databases/{id}/agents/{agent}/run | Ejecuta un agente |\n| GET | /api/databases/{id}/analyses | Obtiene los analisis realizados |\n| GET | /api/databases/{id}/proposals | Lista las propuestas de indices |\n| POST | /api/proposals/{id}/approve | Aprueba y ejecuta una propuesta |\n| POST | /api/proposals/{id}/reject | Rechaza una propuesta |\n| GET | /api/jobs | Lista los trabajos en ejecucion |\n| GET | /api/logs | Obtiene los logs del sistema |\n\n---\n\n## Niveles de autonomia\n\nEl sistema soporta cuatro niveles de autonomia que determinan el grado de intervencion humana requerido.\n\n| Nivel | Nombre | Comportamiento |\n|-------|--------|----------------|\n| 0 | Observacion | Solo analiza e informa, sin generar propuestas |\n| 1 | Asistido | Genera propuestas que requieren aprobacion manual |\n| 2 | Confianza | Ejecuta automaticamente propuestas de bajo riesgo |\n| 3 | Autonomo | Ejecuta todas las propuestas automaticamente |\n\nEl nivel de autonomia se configura por base de datos y puede ajustarse en tiempo de ejecucion desde el panel de configuracion.\n\nPara entornos de produccion, se recomienda comenzar con el nivel 1 (Asistido) y aumentar gradualmente segun la confianza en las propuestas del sistema.\n\n---\n\n## Contribuciones\n\nLas contribuciones son bienvenidas. Para contribuir al proyecto, sigue estos pasos:\n\n1. Haz un fork del repositorio\n2. Crea una rama para tu funcionalidad (`git checkout -b feature/nueva-funcionalidad`)\n3. Realiza tus cambios y anade tests si corresponde\n4. Asegurate de que el codigo sigue el estilo del proyecto\n5. Envia un pull request con una descripcion clara de los cambios\n\n### Guia de estilo\n\nEl codigo Python sigue las convenciones de PEP 8. El codigo TypeScript sigue las convenciones del proyecto con ESLint configurado.\n\nLos mensajes de commit deben ser descriptivos y seguir el formato:\n\n```\ntipo: descripcion breve\n\nDescripcion detallada si es necesaria.\n```\n\nDonde tipo puede ser: feat, fix, docs, refactor, test, chore.\n\n---\n\n## Licencia\n\nEste proyecto se distribuye bajo la licencia MIT. Consulta el archivo LICENSE para mas detalles.\n\n---\n\n## Autor\n\nDesarrollado por [686f6c61](https://github.com/686f6c61) como prueba de concepto para la aplicacion de inteligencia artificial en la administracion de bases de datos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F686f6c61%2Fpg-index-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F686f6c61%2Fpg-index-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F686f6c61%2Fpg-index-agents/lists"}