apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-07-09 05:12:12 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

update more languages

Browse source 
Signed-off-by: Alex Jenkins <kjenkins60@gatech.edu>
This commit is contained in:
Alex Jenkins 2026-04-11 01:08:44 +00:00
parent 835acaa70e
commit 16c2f12a54
249 changed files with 117186 additions and 186 deletions
Download patch file Download diff file Expand all files Collapse all files

151
docs/tech-specs/flow-configurable-parameters.es.md
View file

@ -1,3 +1,4 @@
<<<<<<< HEAD
# Especificación Técnica de Parámetros Configurables para Flow Blueprint
## Resumen
@ -10,11 +11,26 @@ La integración admite cuatro casos de uso principales:
1. **Selección de Modelo**: Permitir a los usuarios elegir diferentes modelos LLM (por ejemplo, `gemma3:8b`, `gpt-4`, `claude-3`) para los procesadores.
2. **Configuración de Recursos**: Ajustar los parámetros del procesador, como los tamaños de lote, los tamaños de lote y los límites de concurrencia.
=======
# Especificación Técnica de Parámetros Configurables para el Blueprint de Flujo
## Resumen
Esta especificación describe la implementación de parámetros configurables para blueprints de flujo en TrustGraph. Los parámetros permiten a los usuarios personalizar los parámetros del procesador en el momento de la ejecución del flujo, proporcionando valores que reemplazan los marcadores de posición de parámetros en la definición del blueprint del flujo.
Los parámetros funcionan mediante la sustitución de variables de plantilla en los parámetros del procesador, de manera similar a como funcionan las variables `{id}` y `{class}`, pero con valores proporcionados por el usuario.
La integración admite cuatro casos de uso principales:
1. **Selección de Modelo**: Permitir a los usuarios elegir diferentes modelos de LLM (por ejemplo, `gemma3:8b`, `gpt-4`, `claude-3`) para los procesadores.
2. **Configuración de Recursos**: Ajustar los parámetros del procesador, como los tamaños de lote, los tamaños de fragmento y los límites de concurrencia.
>>>>>>> 82edf2d (New md files from RunPod)
3. **Ajuste del Comportamiento**: Modificar el comportamiento del procesador a través de parámetros como la temperatura, el número máximo de tokens o los umbrales de recuperación.
4. **Parámetros Específicos del Entorno**: Configurar puntos finales, claves de API o URL específicas de la región para cada implementación.
## Objetivos
<<<<<<< HEAD
**Configuración Dinámica del Procesador**: Permitir la configuración en tiempo de ejecución de los parámetros del procesador a través de la sustitución de parámetros.
**Validación de Parámetros**: Proporcionar verificación de tipos y validación para los parámetros en el momento de la ejecución del flujo.
**Valores Predeterminados**: Admitir valores predeterminados sensatos, al tiempo que se permite la sobrescritura para usuarios avanzados.
@ -27,19 +43,41 @@ La integración admite cuatro casos de uso principales:
## Antecedentes
Los flow blueprints en TrustGraph ahora admiten parámetros de procesador que pueden contener valores fijos o marcadores de posición de parámetros. Esto crea una oportunidad para la personalización en tiempo de ejecución.
=======
**Configuración Dinámica del Procesador**: Permitir la configuración en tiempo de ejecución de los parámetros del procesador mediante la sustitución de parámetros.
**Validación de Parámetros**: Proporcionar verificación de tipos y validación para los parámetros en el momento de la ejecución del flujo.
**Valores Predeterminados**: Admitir valores predeterminados razonables, al tiempo que se permite la sobrescritura para usuarios avanzados.
**Sustitución de Plantillas**: Reemplazar sin problemas los marcadores de posición de parámetros en los parámetros del procesador.
**Integración de la Interfaz de Usuario**: Permitir la entrada de parámetros a través de interfaces de API y de la interfaz de usuario.
**Seguridad de Tipos**: Asegurar que los tipos de parámetros coincidan con los tipos de parámetros del procesador esperados.
**Documentación**: Esquemas de parámetros auto-documentados dentro de las definiciones de blueprints de flujo.
**Compatibilidad con Versiones Anteriores**: Mantener la compatibilidad con los blueprints de flujo existentes que no utilizan parámetros.
## Antecedentes
Los blueprints de flujo en TrustGraph ahora admiten parámetros de procesador que pueden contener valores fijos o marcadores de posición de parámetros. Esto crea una oportunidad para la personalización en tiempo de ejecución.
>>>>>>> 82edf2d (New md files from RunPod)
Los parámetros de procesador actuales admiten:
Valores fijos: `"model": "gemma3:12b"`
Marcadores de posición de parámetros: `"model": "gemma3:{model-size}"`
Esta especificación define cómo se:
<<<<<<< HEAD
Declaran en las definiciones de flow blueprint.
=======
Declaran en las definiciones de blueprints de flujo.
>>>>>>> 82edf2d (New md files from RunPod)
Validan cuando se ejecutan los flujos.
Sustituyen en los parámetros del procesador.
Exponen a través de las API y la interfaz de usuario.
Al aprovechar los parámetros de procesador parametrizados, TrustGraph puede:
<<<<<<< HEAD
Reducir la duplicación de flow blueprints mediante el uso de parámetros para las variaciones.
=======
Reducir la duplicación de blueprints de flujo mediante el uso de parámetros para las variaciones.
>>>>>>> 82edf2d (New md files from RunPod)
Permitir a los usuarios ajustar el comportamiento del procesador sin modificar las definiciones.
Admitir configuraciones específicas del entorno a través de los valores de los parámetros.
Mantener la seguridad de tipos a través de la validación del esquema de parámetros.
@ -51,7 +89,11 @@ Mantener la seguridad de tipos a través de la validación del esquema de parám
El sistema de parámetros configurables requiere los siguientes componentes técnicos:
1. **Definición del Esquema de Parámetros**
<<<<<<< HEAD
Definiciones de parámetros basadas en JSON Schema dentro de los metadatos del flow blueprint.
=======
Definiciones de parámetros basadas en esquemas JSON dentro de los metadatos del blueprint de flujo.
>>>>>>> 82edf2d (New md files from RunPod)
Definiciones de tipos que incluyen cadenas, números, booleanos, enumeraciones y tipos de objetos.
Reglas de validación que incluyen valores mínimos/máximos, patrones y campos obligatorios.
@ -80,10 +122,17 @@ El sistema de parámetros configurables requiere los siguientes componentes téc
Módulo: trustgraph-flow/trustgraph/flow/launcher.py
5. **Formularios de Parámetros de la Interfaz de Usuario**
<<<<<<< HEAD
Generación dinámica de formularios a partir de los metadatos de los parámetros del flujo.
Visualización ordenada de parámetros utilizando el campo `order`.
Etiquetas descriptivas de parámetros utilizando el campo `description`.
Validación de entrada contra las definiciones de tipo de parámetro.
=======
Generación dinámica de formularios a partir de metadatos de parámetros del flujo.
Visualización ordenada de parámetros utilizando el campo `order`.
Etiquetas descriptivas de parámetros utilizando el campo `description`.
Validación de entrada contra definiciones de tipos de parámetros.
>>>>>>> 82edf2d (New md files from RunPod)
Preajustes y plantillas de parámetros.
Módulo: trustgraph-ui/components/flow-parameters/
@ -217,6 +266,7 @@ Los diagramas de flujo definen los metadatos de los parámetros con referencias
}
```
<<<<<<< HEAD
La sección `parameters` mapea los nombres de parámetros específicos del flujo (claves) a objetos de metadatos de parámetros que contienen:
`type`: Referencia a la definición de parámetro definida centralmente (por ejemplo, "llm-model")
`description`: Descripción legible por humanos para su visualización en la interfaz de usuario
@ -237,6 +287,28 @@ Herencia de valores de parámetros para configuraciones relacionadas
#### Solicitud de inicio de flujo
La API de inicio de flujo acepta parámetros utilizando los nombres de parámetros del flujo:
=======
La sección `parameters` asigna nombres de parámetros específicos del flujo (claves) a objetos de metadatos de parámetros que contienen:
`type`: Referencia a la definición de parámetro definida centralmente (por ejemplo, "llm-model").
`description`: Descripción legible por humanos para su visualización en la interfaz de usuario.
`order`: Orden de visualización para los formularios de parámetros (los números más bajos aparecen primero).
`advanced` (opcional): Marcador booleano que indica si este es un parámetro avanzado (por defecto: falso). Cuando se establece en verdadero, la interfaz de usuario puede ocultar este parámetro de forma predeterminada o colocarlo en una sección "Avanzado".
`controlled-by` (opcional): Nombre de otro parámetro que controla el valor de este parámetro cuando está en modo simple. Cuando se especifica, este parámetro hereda su valor del parámetro de control, a menos que se anule explícitamente.
Este enfoque permite:
Definiciones de tipos de parámetros reutilizables en múltiples plantillas de flujo.
Gestión y validación centralizadas de tipos de parámetros.
Descripciones y orden de parámetros específicos del flujo.
Experiencia de interfaz de usuario mejorada con formularios de parámetros descriptivos.
Validación de parámetros coherente en todos los flujos.
Adición fácil de nuevos tipos de parámetros estándar.
Interfaz de usuario simplificada con separación de modo básico/avanzado.
Herencia de valores de parámetros para configuraciones relacionadas.
#### Solicitud de inicio del flujo
La API de inicio del flujo acepta parámetros utilizando los nombres de parámetros del flujo:
>>>>>>> 82edf2d (New md files from RunPod)
```json
{
@ -252,8 +324,13 @@ La API de inicio de flujo acepta parámetros utilizando los nombres de parámetr
Nota: En este ejemplo, `llm-rag-model` no se proporciona explícitamente, pero heredará el valor "claude-3" de `llm-model` debido a su relación `controlled-by`. De manera similar, `chunk-overlap` podría heredar un valor calculado basado en `chunk-size`.
<<<<<<< HEAD
El sistema realizará lo siguiente:
1. Extraer metadatos de parámetros de la definición de la plantilla de flujo.
=======
El sistema realizará las siguientes acciones:
1. Extraer metadatos de parámetros de la definición de la plantilla del flujo.
>>>>>>> 82edf2d (New md files from RunPod)
2. Mapear los nombres de los parámetros del flujo a sus definiciones de tipo (por ejemplo, `llm-model` → tipo `llm-model`).
3. Resolver las relaciones de control (por ejemplo, `llm-rag-model` hereda de `llm-model`).
4. Validar los valores proporcionados por el usuario y los valores heredados en función de las definiciones de tipo de los parámetros.
@ -268,7 +345,11 @@ Cuando se inicia un flujo, el sistema realiza los siguientes pasos de resolució
1. **Carga de la plantilla del flujo**: Cargar la definición de la plantilla del flujo y extraer los metadatos de los parámetros.
2. **Extracción de metadatos**: Extraer `type`, `description`, `order`, `advanced` y `controlled-by` para cada parámetro definido en la sección `parameters` de la plantilla del flujo.
3. **Búsqueda de la definición de tipo**: Para cada parámetro en la plantilla del flujo:
<<<<<<< HEAD
Recuperar la definición de tipo del parámetro del almacén de esquema/configuración utilizando el campo `type`.
=======
Recuperar la definición de tipo del parámetro del almacén de esquemas/configuración utilizando el campo `type`.
>>>>>>> 82edf2d (New md files from RunPod)
Las definiciones de tipo se almacenan con el tipo "parameter-type" en el sistema de configuración.
Cada definición de tipo contiene el esquema del parámetro, el valor predeterminado y las reglas de validación.
4. **Resolución del valor predeterminado**:
@ -292,7 +373,11 @@ El conjunto completo de parámetros (incluidos los valores predeterminados aplic
La resolución de parámetros se realiza al inicio del flujo, no en el momento de la instanciación del procesador.
Los parámetros obligatorios sin valores predeterminados DEBEN provocar que el inicio del flujo falle con un mensaje de error claro.
<<<<<<< HEAD
#### Herencia de parámetros con control
=======
#### Herencia de parámetros con "controlled-by"
>>>>>>> 82edf2d (New md files from RunPod)
El campo `controlled-by` permite la herencia de valores de parámetros, lo que es especialmente útil para simplificar las interfaces de usuario al tiempo que se mantiene la flexibilidad:
@ -313,7 +398,11 @@ En el modo básico/simple: Los parámetros con `controlled-by` pueden estar ocul
En el modo avanzado: Se muestran todos los parámetros y se pueden configurar individualmente.
Cuando cambia un parámetro de control, los parámetros dependientes se actualizan automáticamente, a menos que se anulen explícitamente.
<<<<<<< HEAD
#### Integración de Pulsar
=======
#### Integración con Pulsar
>>>>>>> 82edf2d (New md files from RunPod)
1. **Operación de inicio de flujo**
La operación de inicio de flujo de Pulsar debe aceptar un campo `parameters` que contenga un mapa de valores de parámetros.
@ -371,7 +460,11 @@ El servicio de configuración de flujo (`trustgraph-flow/trustgraph/config/servi
Esta función debe:
Extraer los metadatos de los parámetros de la sección `parameters` del plano de flujo.
<<<<<<< HEAD
Para cada parámetro, obtener la definición de tipo de la tienda de configuración.
=======
Para cada parámetro, obtener la definición de tipo del almacén de configuración.
>>>>>>> 82edf2d (New md files from RunPod)
Aplicar los valores predeterminados para cualquier parámetro que no sea proporcionado por el usuario.
Manejar las relaciones de herencia de `controlled-by`.
Devolver el conjunto de parámetros completo.
@ -384,50 +477,86 @@ El servicio de configuración de flujo (`trustgraph-flow/trustgraph/config/servi
3. **Obtención del Tipo de Parámetro**
Las definiciones de tipo de parámetro se almacenan en la configuración con el tipo "parameter-type".
<<<<<<< HEAD
Cada definición de tipo contiene un esquema, un valor predeterminado y reglas de validación.
=======
Cada definición de tipo contiene el esquema, el valor predeterminado y las reglas de validación.
>>>>>>> 82edf2d (New md files from RunPod)
Almacenar en caché los tipos de parámetro utilizados con frecuencia para reducir las búsquedas en la configuración.
#### Integración del Sistema de Configuración
3. **Almacenamiento de Objetos de Flujo**
<<<<<<< HEAD
Cuando un flujo se agrega al sistema de configuración por el componente de flujo en el administrador de configuración, el objeto de flujo debe incluir los valores de parámetros resueltos.
El administrador de configuración debe almacenar tanto los parámetros originales proporcionados por el usuario como los valores resueltos (con los valores predeterminados aplicados).
Los objetos de flujo en el sistema de configuración deben incluir:
`parameters`: Los valores de parámetros resueltos finales utilizados para el flujo.
=======
Cuando un flujo se agrega al sistema de configuración por el componente de flujo en el administrador de configuración, el objeto de flujo debe incluir los valores de parámetro resueltos.
El administrador de configuración debe almacenar tanto los parámetros originales proporcionados por el usuario como los valores resueltos (con los valores predeterminados aplicados).
Los objetos de flujo en el sistema de configuración deben incluir:
`parameters`: Los valores de parámetro resueltos finales utilizados para el flujo.
>>>>>>> 82edf2d (New md files from RunPod)
#### Integración de la CLI
4. **Comandos de la CLI de la Biblioteca**
Los comandos de la CLI que inician flujos necesitan soporte de parámetros:
<<<<<<< HEAD
Aceptar valores de parámetros a través de indicadores de línea de comandos o archivos de configuración.
=======
Aceptar valores de parámetro a través de indicadores de línea de comandos o archivos de configuración.
>>>>>>> 82edf2d (New md files from RunPod)
Validar los parámetros contra las definiciones del plano de flujo antes de la presentación.
Soporte para la entrada de archivos de parámetros (JSON/YAML) para conjuntos de parámetros complejos.
Los comandos de la CLI que muestran flujos deben mostrar información de parámetros:
<<<<<<< HEAD
Mostrar los valores de parámetros utilizados cuando se inició el flujo.
Mostrar los parámetros disponibles para un plano de flujo.
Mostrar los esquemas y valores predeterminados de validación de parámetros.
=======
Mostrar los valores de parámetro utilizados cuando se inició el flujo.
Mostrar los parámetros disponibles para un plano de flujo.
Mostrar los esquemas de validación y los valores predeterminados de los parámetros.
>>>>>>> 82edf2d (New md files from RunPod)
#### Integración de la Clase Base del Procesador
5. **Soporte de ParameterSpec**
Las clases base del procesador deben admitir la sustitución de parámetros a través del mecanismo ParametersSpec existente.
La clase ParametersSpec (ubicada en el mismo módulo que ConsumerSpec y ProducerSpec) debe mejorarse si es necesario para admitir la sustitución de plantillas de parámetros.
<<<<<<< HEAD
Los procesadores deben poder invocar ParametersSpec para configurar sus parámetros con los valores de parámetros resueltos en el momento del lanzamiento del flujo.
La implementación de ParametersSpec debe:
Aceptar configuraciones de parámetros que contengan marcadores de posición de parámetros (por ejemplo, `{model}`, `{temperature}`).
Admitir la sustitución de parámetros en tiempo de ejecución cuando se instancia el procesador.
Validar que los valores sustituidos coincidan con los tipos y restricciones esperados.
Proporcionar manejo de errores para referencias de parámetros faltantes o no válidos.
=======
Los procesadores deben poder invocar ParametersSpec para configurar sus parámetros con los valores de parámetro resueltos en el momento del inicio del flujo.
La implementación de ParametersSpec debe:
Aceptar configuraciones de parámetros que contengan marcadores de posición de parámetros (por ejemplo, `{model}`, `{temperature}`).
Admitir la sustitución de parámetros en tiempo de ejecución cuando se instancia el procesador.
Validar que los valores sustituidos coincidan con los tipos y las restricciones esperadas.
Proporcionar el manejo de errores para las referencias de parámetros faltantes o no válidas.
>>>>>>> 82edf2d (New md files from RunPod)
#### Reglas de Sustitución
Los parámetros utilizan el formato `{parameter-name}` en los parámetros del procesador.
Los nombres de los parámetros en los parámetros coinciden con las claves en la sección `parameters` del flujo.
La sustitución se produce junto con la sustitución de `{id}` y `{class}`.
<<<<<<< HEAD
Las referencias de parámetros no válidas dan como resultado errores en el momento del lanzamiento.
La validación de tipos se basa en la definición de parámetro almacenada de forma centralizada.
**IMPORTANTE**: Todos los valores de parámetros se almacenan y transmiten como cadenas.
=======
Las referencias de parámetros no válidas dan como resultado errores en el momento del inicio.
La validación de tipos se basa en la definición de parámetro almacenada de forma centralizada.
**IMPORTANTE**: Todos los valores de los parámetros se almacenan y transmiten como cadenas.
>>>>>>> 82edf2d (New md files from RunPod)
Los números se convierten a cadenas (por ejemplo, `0.7` se convierte en `"0.7"`).
Los booleanos se convierten a cadenas en minúsculas (por ejemplo, `true` se convierte en `"true"`).
Esto es requerido por el esquema de Pulsar que define `parameters = Map(String())`.
@ -452,6 +581,7 @@ Pruebas de integración para la sustitución de parámetros en los parámetros d
Pruebas de extremo a extremo para el lanzamiento de flujos con diferentes valores de parámetros.
Pruebas de la interfaz de usuario para la generación y validación de formularios de parámetros.
Pruebas de rendimiento para flujos con muchos parámetros.
<<<<<<< HEAD
Casos extremos: parámetros faltantes, tipos no válidos, referencias de parámetros no definidos.
## Plan de Migración
@ -459,12 +589,25 @@ Casos extremos: parámetros faltantes, tipos no válidos, referencias de paráme
1. El sistema debe seguir soportando planos de flujo sin parámetros
declarados.
2. El sistema debe seguir soportando flujos sin parámetros especificados:
=======
Casos extremos: parámetros faltantes, tipos inválidos, referencias de parámetros no definidos.
## Plan de Migración
1. El sistema debe continuar admitiendo planos de flujo sin parámetros
declarados.
2. El sistema debe continuar admitiendo flujos sin parámetros especificados:
>>>>>>> 82edf2d (New md files from RunPod)
Esto funciona para flujos sin parámetros y para flujos con parámetros
(que tienen valores predeterminados).
## Preguntas Abiertas
<<<<<<< HEAD
P: ¿Deben los parámetros soportar objetos anidados complejos o limitarse a tipos simples?
=======
P: ¿Deben los parámetros admitir objetos anidados complejos o limitarse a tipos simples?
>>>>>>> 82edf2d (New md files from RunPod)
R: Los valores de los parámetros se codificarán como cadenas, por lo que probablemente
queremos limitarnos a cadenas.
@ -476,10 +619,18 @@ P: ¿Cómo manejar los conflictos entre los nombres de los parámetros y las var
`id` y `class`?
R: No es válido especificar "id" y "class" al iniciar un flujo.
<<<<<<< HEAD
P: ¿Debemos soportar parámetros calculados (derivados de otros parámetros)?
=======
P: ¿Debemos admitir parámetros calculados (derivados de otros parámetros)?
>>>>>>> 82edf2d (New md files from RunPod)
R: Solo la sustitución de cadenas para evitar inyecciones extrañas y casos límite.
## Referencias
Especificación de JSON Schema: https://json-schema.org/
<<<<<<< HEAD
Especificación de la Definición del Plano de Flujo: docs/tech-specs/flow-class-definition.md
=======
Especificación de la definición del plano de flujo: docs/tech-specs/flow-class-definition.md
>>>>>>> 82edf2d (New md files from RunPod)