Referencia
Propiedades y métodos clave
Los miembros que usarás con más frecuencia.
Un proveedor necesita las unidades de IA de la edición Enterprise o All-Access, o el pack sgcAI, y solo funcionan en Windows. El analizador integrado responde en todas las plataformas sin proveedor. La unidad se compila cuando SGC_HTML está definido, algo que sgcVer.inc no hace para Android e iOS, y sgcHTML es un pack autónomo, que se vende de forma independiente de sgcWebSockets.
Dónde asignarlo
AIAssistant existe en TsgcHTMLComponent_Grid, TsgcHTMLComponent_DataTable, TsgcHTMLComponent_PivotTable, TsgcHTMLComponent_Form y TsgcHTMLComponent_InlineAIPrompt. AIQueryEnabled existe en el grid, la tabla de datos y la tabla dinámica: renderiza la barra de consulta, el chip de «interpretado como» y el control para limpiar. El formulario no tiene AIQueryEnabled, usa el asistente para el pegado inteligente, y InlineAIPrompt lo usa para su respuesta. Mientras no haya un asistente asignado, un grid no renderiza ningún marcado de IA.
Qué sale de la máquina
Una pregunta sobre un grid o una tabla dinámica envía los nombres de las columnas, los títulos, los tipos y hasta tres valores de muestra por columna, cada uno recortado a 40 caracteres. Nada más, sea cual sea la configuración. Las filas solo salen mediante las llamadas que tratan de filas, y solo cuando AllowRowDataToProvider es True, algo que no ocurre por defecto: SuggestColumnValues y Summarize devuelven entonces False y no envían nada, y MaxRows limita lo que pueden llevar. El pegado inteligente envía el texto que una persona pegó y el nombre, la etiqueta y el tipo de cada campo, y ningún valor del formulario.
La validación es la frontera
Todo lo que devuelve un proveedor se trata como texto hostil. Cada nombre de columna debe coincidir con tu lista de permitidos, por nombre exacto y sin distinguir entre mayúsculas y minúsculas. Cada operador debe ser uno de los 13 de TsgcHTMLAIOperator, cada agregado uno de sum, count, avg, min y max, y cada valor se convierte según el tipo de su columna: un valor que no se puede convertir descarta toda su operación. Un estilo de resaltado debe ser uno de primary, secondary, success, danger, warning, info, light o dark. Los límites se acotan a MaxLimit, hay como máximo 32 filtros, 32 ordenaciones y 32 resaltados, se eliminan los caracteres de control, y todo lo desconocido se descarta en silencio. Si no sobrevive nada, se borra el conjunto completo, explicación incluida. Un prompt injection produce un conjunto vacío o parcial, nunca una excepción.
El modelo de operaciones
TsgcHTMLGridOps contiene Filters, Sorts, Highlights, GroupBy, Limit y Explanation. TsgcHTMLPivotOps contiene Rows, Columns, Measure, Aggregate y Explanation. TsgcHTMLAIColumns es la lista de permitidos: Add(aName, aDataType, aCaption) por cada columna, con AddSample para las muestras. Ambas clases de operaciones ofrecen IsEmpty, ToText y ToJSON, y FromJSON es la frontera completa solo cuando le pasas las columnas, así que vuelve a validar todo lo que leas de un navegador contra la lista de permitidos vigente.
Elegir un proveedor
Provider es uno de aiprOpenAI (el valor por defecto), aiprAnthropic, aiprGemini, aiprDeepSeek, aiprOllama, aiprGrok y aiprMistral, los siete de TsgcAIChatProvider en sgcAI_Chat. Establece APIKey o BaseUrl y el asistente es propietario de un TsgcAI_Chat configurado a partir de Provider, APIKey, Model (vacío conserva el valor por defecto del chat) y BaseUrl. O asigna tu propio componente de chat a Chat, que solo se declara donde las unidades de IA están compiladas. Cada llamada pide una salida estructurada que sigue un esquema JSON, y tu chat se restaura después. HasProvider indica en qué caso estás.
Alternativa basada en reglas
Sin proveedor, el asistente responde con su propio analizador, y UseRuleBasedFallback (activado por defecto) le permite responder también cuando falla una llamada al proveedor. Lee cláusulas de la forma columna operador valor unidas por and o una coma, además de sort by, group by, top N, between A and B y highlight, y para una tabla dinámica las filas, las columnas y el agregado. Acepta las grafías habituales en inglés de cada operador y cualquiera de los dos separadores decimales. Una pregunta que no entiende no produce ninguna operación y la página conserva sus filas. SuggestColumnValues y Summarize no tienen alternativa.
SmartPaste(aText, aFields, aValues) asigna el texto pegado a un conjunto de campos. Establece SmartPasteEnabled en TsgcHTMLComponent_Form y renderiza una zona de pegado; ProcessSmartPaste(aText) entrega el texto al asistente, escribe lo que vuelve en los campos por nombre y los marca como rellenados por IA, con una pequeña insignia en la etiqueta. El analizador basado en reglas lo responde sin proveedor, y los saltos de línea sobreviven al viaje hasta el servidor.
Asistente de columna
SuggestColumnValues(aPrompt, aRows, aValues) maneja el asistente de columna del grid. Una columna cuyo AIMode no es acOff renderiza un control de sugerencia, ProcessAIColumnValues(aColumnName) pide un valor por cada fila visible en una sola llamada, y las respuestas se convierten en AIProposals con un control Aceptar y otro Rechazar. La biblioteca no escribe nada: una propuesta aceptada dispara OnAIColumnValues y tu aplicación la guarda. La llamada envía filas, así que necesita un proveedor y AllowRowDataToProvider activado.
Ajustes de respuesta y eventos
Language establece el idioma del texto libre, y vacío significa la configuración regional de la petición. CacheMinutes (5) responde desde la caché a una pregunta idéntica sobre un conjunto de columnas idéntico, y ClearCache la vacía. MaxLimit (1000) no se puede subir por encima de 1000. OnBeforeQuery(Sender, aPrompt, aAllow) ve el prompt completo antes de cada llamada al proveedor y la bloquea cuando estableces aAllow en False. Ningún método lanza una excepción: un fallo del proveedor llega a OnAIError(Sender, E, aHandled).
Contrato con el host
No hay ruta HTTP. Cada control es un formulario data-sgc-ws-send y tu aplicación despacha según action: gridAIQuery, gridAIClear, gridAIColumn, gridAIAccept, gridAIReject, pivotAIQuery, pivotAIClear, formSmartPaste y las cuatro acciones del prompt en línea. Responde con el componente renderizado de nuevo como un fragmento fuera de banda. Un conjunto de componentes es un usuario, así que asígnalos por sesión, y mantén en el servidor la autorización de lo que hace una acción.