ASIGH.Assistant - Estructura del Proyecto

Versión: 1.0.0
Fecha: 2026-01-12
Proyecto: Sistema de Asistente Conversacional con RAG y Acceso a Datos

---

📁 Estructura de Carpetas

Assistant/
├── RCE/                            → Componentes Core (Repositorio de Conocimiento)
│   ├── Core/                       → Validación RCE y gestión de conceptos
│   ├── DocumentProcessing/         → Extractores de documentos (ASPX/Word)
│   ├── Chunking/                   → Generación de chunks para embeddings
│   └── Configuration/              → Configuración centralizada
│       ├── AssistantConstants.vb   → ✅ Constantes del sistema
│       └── assistant.config.json   → ✅ Configuración principal
│
├── RAG/                            → Sistema RAG (Retrieval-Augmented Generation)
│   ├── Ingestion/                  → Motores de ingesta de documentos
│   ├── Retrieval/                  → Búsqueda vectorial y recuperación
│   └── ExternalServices/           → Clientes APIs (Voyage, Qdrant, Claude)
│       ├── VoyageClient.vb         → ✅ Cliente Voyage AI (embeddings)
│       ├── QdrantClient.vb         → ✅ Cliente Qdrant (vector DB)
│       └── ClaudeClient.vb         → ✅ Cliente Claude API (LLM)
│
├── DataAccess/                     → Acceso seguro a datos operativos
│   ├── QueryCatalog/               → Gestión de catálogo de queries
│   │   └── QueryCatalogManager.vb  → ✅ Gestor del catálogo
│   ├── Executors/                  → Ejecución segura de queries
│   │   └── SafeQueryExecutor.vb    → ✅ Ejecutor con tenant isolation
│   └── Catalogs/                   → ✅ JSONs de queries predefinidas
│       ├── ventas_queries.json     → Queries de Ventas
│       ├── compras_queries.json    → Queries de Compras
│       ├── rrhh_queries.json       → Queries de RRHH
│       ├── inventario_queries.json → Queries de Inventario
│       └── finanzas_queries.json   → Queries de Finanzas
│
├── Conversation/                   → Lógica conversacional
│   ├── IntentClassifier.vb         → ✅ Clasificador de intención
│   └── ConversationManager.vb      → ✅ Gestor de conversaciones
│
├── UI/                             → Interfaz de usuario (futuro)
├── Admin/                          → Herramientas de administración
├── Logs/                           → Logs del sistema
│   ├── ingestion/                  → Logs de ingesta
│   ├── queries/                    → Logs de queries
│   └── errors/                     → Logs de errores
├── Data/                           → Datos estáticos
└── Scripts/                        → Scripts Python/SQL auxiliares

---

✅ Archivos Incluidos

Archivos de Configuración

• AssistantConstants.vb: Constantes globales del sistema
• assistant.config.json: Configuración centralizada (APIs, colecciones, features)

Archivos Stub VB.NET

Archivos stub básicos creados para empezar el desarrollo:

• RCE/Core/RCEValidator.vb
• RCE/Core/ConceptsCatalog.vb
• RCE/DocumentProcessing/IDocumentExtractor.vb
• RCE/DocumentProcessing/DocumentStructure.vb
• RAG/ExternalServices/VoyageClient.vb
• RAG/ExternalServices/QdrantClient.vb
• RAG/ExternalServices/ClaudeClient.vb
• DataAccess/QueryCatalog/QueryCatalogManager.vb
• DataAccess/Executors/SafeQueryExecutor.vb
• Conversation/IntentClassifier.vb
• Conversation/ConversationManager.vb

Catálogos de Queries (JSON)

Catálogos de ejemplo con queries predefinidas:

• ventas_queries.json (7 queries de ejemplo)
• compras_queries.json
• rrhh_queries.json
• inventario_queries.json
• finanzas_queries.json

---

🚀 Siguiente Paso: Integración en ASIGH.WEB

1. Extraer el ZIP

Extrae este ZIP en la raíz de tu proyecto ASIGH.WEB.

2. Configurar API Keys

Edita Assistant/RCE/Configuration/assistant.config.json y añade tus API keys:

{
  "apis": {
    "voyage": {
      "api_key": "TU_VOYAGE_API_KEY_AQUI"
    },
    "qdrant": {
      "endpoint": "https://TU_CLUSTER.qdrant.io:6333",
      "api_key": "TU_QDRANT_API_KEY_AQUI"
    },
    "claude": {
      "api_key": "TU_CLAUDE_API_KEY_AQUI"
    }
  }
}

3. Agregar Referencias en Visual Studio

1. Abre tu proyecto ASIGH.WEB en Visual Studio
2. Añade los archivos .vb a tu proyecto
3. Configura los Namespaces:
   • ASIGH_IW.RCE.Core
   • ASIGH_IW.RCE.Configuration
   • ASIGH_IW.RAG.ExternalServices
   • ASIGH_IW.DataAccess.QueryCatalog
   • ASIGH_IW.DataAccess.Executors
   • ASIGH_IW.Conversation

4. Instalar Dependencias NuGet

Install-Package Newtonsoft.Json
Install-Package System.Net.Http

5. Cargar Configuración al Inicio

En Global.asax.vb:

Sub Application_Start(sender As Object, e As EventArgs)
    ' Cargar configuración del asistente
    Dim configPath = Server.MapPath("~/Assistant/RCE/Configuration/assistant.config.json")
    AssistantConfig.Load(configPath)
End Sub

---

📖 Uso de Constantes

Ejemplo 1: Validar tipo de concepto

Imports ASIGH_IW.Core

If conceptType = AssistantConstants.CONCEPT_TYPE_TEMA Then
    ' Procesar tema
End If

Ejemplo 2: Usar colección correcta

Dim collection = AssistantConstants.COLLECTION_AYUDAS
Dim results = qdrantClient.Search(collection, vector, 5)

Ejemplo 3: Logging con niveles

Logger.Log(AssistantConstants.LOG_LEVEL_INFO, "Proceso completado")

---

🔧 Desarrollo por Fases

Fase 1: Core Infrastructure ✅

Incluido en este ZIP:

• Estructura de carpetas completa
• Archivos de constantes
• Configuración centralizada
• Stubs básicos

Fase 2A: Ingesta ASPX (Siguiente)

A desarrollar:

• AspxExtractor completo
• AspxIngestionEngine
• Integración con Voyage AI
• Integración con Qdrant

Fase 2B: Ingesta Word

A desarrollar:

• WordExtractor
• WordIngestionEngine
• Script Python extract_word.py

Fase 3: Data Access + Conversation

A desarrollar:

• SafeQueryExecutor completo
• IntentClassifier completo
• ConversationManager completo
• Interfaz de usuario (ChatControl.ascx)

---

📝 Notas Importantes

Archivos .gitkeep

Las carpetas vacías contienen archivos .gitkeep para mantener la estructura en Git.

Namespaces

Todos los archivos usan el namespace ASIGH_IW.* para mantener consistencia con tu proyecto.

TODOs

Los archivos stub contienen Throw New NotImplementedException() como placeholder. Reemplaza esto con la lógica real durante el desarrollo.

Configuración

El archivo assistant.config.json contiene valores de ejemplo. NO comitees este archivo con API keys reales a control de versiones.

---

🔒 Seguridad

API Keys

• Nunca comitees assistant.config.json con API keys reales
• Usa variables de entorno o Azure Key Vault en producción

Tenant Isolation

• Todas las queries SQL deben incluir ClienteId = @ClienteId
• SafeQueryExecutor validará esto automáticamente

Logging

• Los logs NO deben contener información sensible
• Usa niveles apropiados (DEBUG solo en desarrollo)

---

📞 Soporte

Para dudas sobre la estructura o implementación, consulta:

• ARQUITECTURA-UNIFICADA.md (documento de diseño completo)
• ESTRUCTURA-CARPETAS-ASIGH-WEB.md (explicación detallada)

---

📜 Licencia

Este código es parte del proyecto ASIGH.WEB
© 2026 Advanced Business Consulting Systems SL

---

¡Listo para empezar el desarrollo! 🚀