trustgraph/docs/tech-specs/schema-refactoring-proposal.es.md

layout	title	parent
default	Propuesta de Refactorización del Directorio de Esquemas	Spanish (Beta)

Propuesta de Refactorización del Directorio de Esquemas

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Problemas Actuales

1. Estructura plana - Tener todos los esquemas en un solo directorio dificulta la comprensión de las relaciones.
2. Preocupaciones mixtas - Tipos centrales, objetos de dominio y contratos de API mezclados.
3. Nombres poco claros - Archivos como "object.py", "types.py", "topic.py" no indican claramente su propósito.
4. Sin capa clara - No es fácil ver qué depende de qué.

Estructura Propuesta

trustgraph-base/trustgraph/schema/
├── __init__.py
├── core/              # Tipos primitivos centrales utilizados en todas partes
│   ├── __init__.py
│   ├── primitives.py  # Error, Value, Triple, Field, RowSchema
│   ├── metadata.py    # Registro de metadatos
│   └── topic.py       # Utilitarios de tema
│
├── knowledge/         # Modelos del dominio de conocimiento y extracción
│   ├── __init__.py
│   ├── graph.py       # EntityContext, EntityEmbeddings, Triples
│   ├── document.py    # Document, TextDocument, Chunk
│   ├── knowledge.py   # Tipos de extracción de conocimiento
│   ├── embeddings.py  # Todos los tipos relacionados con la incorporación (movidos de múltiples archivos)
│   └── nlp.py         # Tipos de Definición, Tema, Relación, Hecho
│
└── services/          # Contratos de solicitud/respuesta de servicios
    ├── __init__.py
    ├── llm.py         # TextCompletion, Embeddings, Solicitudes/respuestas de Herramientas
    ├── retrieval.py   # Consultas/respuestas de GraphRAG, DocumentRAG
    ├── query.py       # Consultas/respuestas de GraphEmbeddingsRequest, DocumentEmbeddingsRequest
    ├── agent.py       # Solicitudes/respuestas del agente
    ├── flow.py        # Solicitudes/respuestas de flujo
    ├── prompt.py      # Solicitudes/respuestas del servicio de prompt
    ├── config.py      # Servicio de configuración
    ├── library.py     # Servicio de bibliotecario
    └── lookup.py      # Servicio de búsqueda

Cambios Clave

1. Organización jerárquica - Separación clara entre tipos centrales, modelos de conocimiento y contratos de servicio.

2. Nombres mejorados:

   • types.py → core/primitives.py (propósito más claro)
   • object.py → Dividir entre archivos apropiados según el contenido real
   • documents.py → knowledge/document.py (singular, consistente)
   • models.py → services/llm.py (qué tipo de modelos)
   • prompt.py → Dividir: partes del servicio a services/prompt.py, tipos de datos a knowledge/nlp.py

3. Agrupamiento lógico:

   • Todos los tipos de incorporación consolidados en knowledge/embeddings.py
   • Todos los contratos de servicio relacionados con LLM en services/llm.py
   • Separación clara de pares de solicitud/respuesta en el directorio de servicios
   • Grupos de tipos de extracción de conocimiento con otros modelos de dominio de conocimiento

4. Claridad de dependencias:

   • Los tipos centrales no tienen dependencias
   • Los modelos de conocimiento dependen solo de los centrales
   • Los contratos de servicio pueden depender de los centrales y de los modelos de conocimiento

Beneficios de la Migración

1. Navegación más fácil - Los desarrolladores pueden encontrar rápidamente lo que necesitan.
2. Mejor modularidad - Límites claros entre diferentes preocupaciones.
3. Importaciones más simples - Rutas de importación más intuitivas.
4. Futurizable - Fácil de agregar nuevos tipos de conocimiento o servicios sin desorden.

Cambios de Importación de Ejemplo

# Antes
from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest

# Después
from trustgraph.schema.core import Error, Triple
from trustgraph.schema.knowledge import GraphEmbeddings
from trustgraph.schema.services import TextCompletionRequest

Notas de Implementación

1. Mantener la compatibilidad hacia atrás manteniendo las importaciones en el __init__.py raíz.
2. Mover los archivos gradualmente, actualizando las importaciones según sea necesario.
3. Considerar agregar un legacy.py que importe todo para el período de transición.
4. Actualizar la documentación para reflejar la nueva estructura.

<function_calls> [{"id": "1", "content": "Examinar la estructura actual del directorio de esquemas", "status": "completed", "priority": "high"}, {"id": "2", "content": "Analizar los archivos de esquema y sus propósitos", "status": "completed", "priority": "high"}, {"id": "3", "content": "Proponer una estructura y nombres mejorados", "status": "completed", "priority": "high"}]