Análisis de la base de código Python del sistema RAG

Este sistema analiza código Python mediante árboles de sintaxis abstracta (AST), almacena la información extraída (funciones, clases, llamadas, variables, etc.) en una base de datos vectorial de Weaviate y proporciona herramientas para consultar y comprender el código base mediante un servidor de Protocolo de Contexto de Modelo (MCP). Aprovecha los modelos Gemini de Google para generar incrustaciones y descripciones/respuestas en lenguaje natural.

Características

• Escaneo de código: Analiza archivos Python para identificar elementos de código (funciones, clases, importaciones, llamadas, asignaciones) y sus relaciones. Extractos:
  • Información básica: nombre, tipo, ruta de archivo, números de línea, fragmento de código, cadena de documentación.
  • Detalles de función/método: parámetros, tipo de retorno, firma, decoradores.
  • Información del alcance: UUID del ámbito principal (clase/función), ID legible (por ejemplo, file:type:name:line ), nombres de clase base.
  • Información de uso: accesos a atributos dentro de los ámbitos, relaciones de llamadas (rastreadas parcialmente).
• Almacenamiento vectorial: utiliza Weaviate para almacenar elementos de código y sus incrustaciones vectoriales (cuando la generación de LLM está habilitada).
• Enriquecimiento LLM (Opcional y en segundo plano): Genera descripciones semánticas e incrustaciones para funciones y clases mediante Gemini. Ahora se ejecuta como tareas en segundo plano que se activan tras el escaneo o manualmente. Se puede activar o desactivar mediante el archivo .env .
• Refinamiento automático (opcional y en segundo plano): cuando la generación de LLM está habilitada, se refinan automáticamente las descripciones de funciones nuevas o actualizadas utilizando el contexto (llamadores, llamados, hermanos, variables relacionadas) como parte del procesamiento en segundo plano.
• Preguntas y respuestas de RAG: responde preguntas en lenguaje natural sobre el código base mediante generación aumentada por recuperación (requiere funciones LLM habilitadas y procesamiento en segundo plano completado).
• Aclaraciones del usuario: permite a los usuarios agregar notas manuales a elementos de código específicos.
• Visualización: genera gráficos de llamadas MermaidJS basados en relaciones almacenadas.
• Servidor MCP: expone capacidades de análisis y consulta a través de herramientas MCP, administrando bases de código y un contexto de base de código activo.
• Vigilante de Archivos (Integrado): Se inicia automáticamente al escanear una base de código ( scan_codebase ) y se detiene al seleccionar otra base de código ( select_codebase ) o al eliminarla ( delete_codebase ). Activa el reanálisis y las actualizaciones de la base de datos de la base de código activa cuando sus archivos cambian. También se puede controlar manualmente mediante las herramientas start_watcher y stop_watcher .
• Dependencias de la base de código: permite definir dependencias entre las bases de código escaneadas ( add_codebase_dependency , remove_codebase_dependency ).
• Consulta entre bases de código: permite realizar búsquedas ( find_element ) y formular preguntas ( ask_question ) en toda la base de código activa y sus dependencias declaradas.

Configuración

1. Entorno: asegúrese de que Python 3.10+ y Docker estén instalados.
2. Weaviate: Inicie la instancia de Weaviate usando Docker Compose:
   docker-compose up -d
3. Dependencias: Instalar paquetes de Python:
   pip install -r requirements.txt
4. Clave API y configuración: Cree un archivo .env en la raíz del proyecto y añada su clave API de Gemini. También puede configurar otros ajustes:
   # --- Required --- GEMINI_API_KEY=YOUR_API_KEY_HERE # --- Optional --- # Set to true to enable background LLM description generation and refinement GENERATE_LLM_DESCRIPTIONS=true # Max concurrent background LLM tasks (embeddings/descriptions/refinements) LLM_CONCURRENCY=5 # ANALYZE_ON_STARTUP is no longer used. Scanning is done via the scan_codebase tool. # Specify Weaviate connection details if not using defaults # WEAVIATE_HOST=localhost # WEAVIATE_PORT=8080 # WEAVIATE_GRPC_PORT=50051 # Specify alternative Gemini models if desired # GENERATION_MODEL_NAME="models/gemini-pro" # EMBEDDING_MODEL_NAME="models/embedding-001" # Adjust Weaviate batch size # WEAVIATE_BATCH_SIZE=100 # SEMANTIC_SEARCH_LIMIT=5 # SEMANTIC_SEARCH_DISTANCE=0.7 # Watcher polling interval (seconds) # WATCHER_POLLING_INTERVAL=5
5. Ejecutar servidor MCP: Inicie el servidor en una terminal independiente:
   python src/code_analysis_mcp/mcp_server.py
   (Asegúrese de que esta terminal permanezca en funcionamiento para que las herramientas estén disponibles)

Descripción general de la arquitectura

Este sistema analiza el código Python, almacena la información extraída en una base de datos vectorial Weaviate y proporciona herramientas para consultar y comprender el código base mediante un servidor de Protocolo de Contexto de Modelo (MCP). Aprovecha los modelos Gemini de Google para generar incrustaciones y descripciones/respuestas en lenguaje natural.

Los módulos principales son:

• code_scanner.py : encuentra archivos Python, los analiza usando AST, extrae elementos estructurales (funciones, clases, importaciones, llamadas, etc.) y prepara datos para Weaviate.
• weaviate_client.py : administra la conexión a Weaviate, define el esquema de datos ( CodeFile , CodeElement , CodebaseRegistry ) y proporciona funciones para cargar, consultar, actualizar y eliminar datos por lotes.
• rag.py : Implementa la Generación Aumentada por Recuperación (RAG) para responder preguntas sobre el código base. Utiliza la búsqueda semántica para encontrar elementos relevantes del código y un LLM para sintetizar una respuesta.
• mcp_server.py : configura el servidor FastMCP, administra bases de código en una colección CodebaseRegistry , maneja el contexto de base de código activo ( ACTIVE_CODEBASE_NAME ), integra lógica de observación de archivos (incluido inicio/detención automáticos), administra dependencias de base de código y expone funcionalidades de análisis como herramientas MCP con descripciones detalladas de argumentos.
• visualization.py : genera gráficos de llamadas MermaidJS basados en relaciones almacenadas.

El sistema utiliza la función multiinquilino de Weaviate para las colecciones CodeFile y CodeElement , donde el ID del inquilino es el codebase_name definido por el usuario. Una colección independiente, CodebaseRegistry , no multiinquilino, rastrea los metadatos de la base de código (nombre, directorio, estado, resumen, estado del observador, dependencias). La variable global ACTIVE_CODEBASE_NAME del servidor determina el inquilino principal de la base de código para las consultas. Las herramientas de consulta ( find_element y ask_question ) pueden buscar opcionalmente en la base de código activa y sus dependencias declaradas almacenadas en el registro. La herramienta list_codebases permite ver el estado y las dependencias de todas las bases de código.

El procesamiento LLM en segundo plano se utiliza para generar descripciones semánticas e incrustaciones para elementos de código. Esta función es opcional y se puede activar o desactivar mediante el archivo .env .

Se puede recuperar información detallada sobre las herramientas disponibles y sus argumentos directamente desde el servidor MCP utilizando métodos de introspección MCP estándar una vez que el servidor esté en ejecución.