# Especificación Técnica de Parámetros Configurables para Flow Blueprint
## Resumen
Esta especificación describe la implementación de parámetros configurables para flow blueprints 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 flow blueprint.
Los parámetros funcionan a través de la sustitución de variables de plantilla en los parámetros del procesador, de manera similar a cómo 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 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.
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.
**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.
**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 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 flow blueprint.
**Compatibilidad con Versiones Anteriores**: Mantener la compatibilidad con los flow blueprints existentes que no utilizan parámetros.
## 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.
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
`order`: Orden de visualización para los formularios de parámetros (los números más bajos aparecen primero)
`advanced` (opcional): Bandera booleana 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 consistente 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 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:
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`.
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.
5. Sustituir los valores resueltos en los parámetros del procesador durante la instanciación del flujo.
### Detalles de implementación
#### Proceso de resolución de parámetros
Cuando se inicia un flujo, el sistema realiza los siguientes pasos de resolución de parámetros:
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:
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**:
Para cada parámetro definido en la plantilla del flujo:
Comprobar si el usuario ha proporcionado un valor para este parámetro.
Si no se proporciona ningún valor del usuario, utilizar el valor `default` de la definición de tipo del parámetro.
Crear un mapa de parámetros completo que contenga tanto los valores proporcionados por el usuario como los valores predeterminados.
5.**Resolución de la herencia de parámetros** (relaciones de control):
Para los parámetros con el campo `controlled-by`, comprobar si se ha proporcionado un valor explícito.
Si no se proporciona ningún valor explícito, heredar el valor del parámetro de control.
Si el parámetro de control también no tiene valor, utilizar el valor predeterminado de la definición de tipo.
Validar que no existan dependencias circulares en las relaciones `controlled-by`.
6.**Validación**: Validar el conjunto completo de parámetros (proporcionados por el usuario, predeterminados y heredados) en función de las definiciones de tipo.
7.**Almacenamiento**: Almacenar el conjunto completo de parámetros resueltos con la instancia del flujo para su trazabilidad.
8.**Sustitución de plantillas**: Reemplazar los marcadores de posición de parámetros en los parámetros del procesador con los valores resueltos.
9.**Instanciación del procesador**: Crear procesadores con los parámetros sustituidos.
**Notas importantes de implementación**:
El servicio de flujo DEBE combinar los parámetros proporcionados por el usuario con los valores predeterminados de las definiciones de tipo de parámetros.
El conjunto completo de parámetros (incluidos los valores predeterminados aplicados) DEBE almacenarse con el flujo para su trazabilidad.
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.
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:
**Escenario de ejemplo**:
El parámetro `llm-model` controla el modelo LLM primario.
El parámetro `llm-rag-model` tiene el valor `"controlled-by": "llm-model"`.
En el modo simple, establecer `llm-model` en "gpt-4" establece automáticamente `llm-rag-model` en "gpt-4" también.
En el modo avanzado, los usuarios pueden anular `llm-rag-model` con un valor diferente.
**Reglas de resolución**:
1. Si un parámetro tiene un valor proporcionado explícitamente, utilizar ese valor.
2. Si no hay ningún valor explícito y `controlled-by` está establecido, utilizar el valor del parámetro de control.
3. Si el parámetro de control no tiene valor, recurrir al valor predeterminado de la definición de tipo.
4. Las dependencias circulares en las relaciones `controlled-by` dan como resultado un error de validación.
**Comportamiento de la interfaz de usuario**:
En el modo básico/simple: Los parámetros con `controlled-by` pueden estar ocultos o mostrarse como de solo lectura con el valor heredado.
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.
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.
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.
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.
