
package com.smartgwt.client.docs;

/**
 * <h3>AI Assist</h3>
 * AI Assist is the natural-language request layer of the Smart GWT AI system.  The user
 *  types (or dictates) a request, and a <i>delegator</i> routes it to whichever registered
 *  <i>service</i> is best suited to handle it.  Applications plug in their own services to
 *  extend the system with app-specific behavior.
 *  <p>
 *  <h3>Three layers</h3>
 *  <ul>
 *  <li><b>Entry points</b> &mdash; AIAssistItem (a FormItem with an inline AI icon),
 * {@link com.smartgwt.client.util.VoiceAssist} (dictation), or direct calls to {@link
 * com.smartgwt.client.ai.AI#delegate AI.delegate()}.</li>
 *  <li><b>Delegator</b> &mdash; AIDelegator, a lightweight CoTProcess that asks
 *      the AI which registered service best matches the user's intent and then invokes it.</li>
 * <li><b>Services</b> &mdash; pluggable units of work.  Each {@link
 * com.smartgwt.client.ai.AIServiceDescriptor}
 *      has a <code>name</code>, a natural-language <code>description</code>, and an
 *      <code>invoke(prompt, rationale, context)</code> function.  Built-in services are
 *      <code>"answerEngine"</code> (data queries) and <code>"buildUI"</code> (create new UI
 *      from a natural-language description).</li>
 *  </ul>
 * 
 *  <h3>Flow</h3>
 *  <pre>
 *  user prompt &rarr; isc.AI.delegate(prompt, context, callback)
 *      |
 *      +-- 0 services: logWarn and return
 *      +-- 1 service:  invoke directly (skip AI)
 *      +-- 2+ services: AIDelegator CoTProcess asks AI "which service?"
 *                                  then invokes service.invoke(prompt, rationale, context)
 *  </pre>
 * 
 *  <h3>Registering services</h3>
 *  A service is just a {@link com.smartgwt.client.ai.AIServiceDescriptor} &mdash; an object with
 *  <code>name</code>, <code>description</code>, and <code>invoke</code>.  The
 *  <code>description</code> is shown to the AI so it can decide whether this service is
 *  appropriate for a given request; keep it a concise sentence or two that names the class
 *  of requests this service handles and the class of requests it does <i>not</i>.
 *  <p>
 *  <b>Global services</b> are available regardless of which component has focus.  Register
 *  them with {@link com.smartgwt.client.ai.AI#registerAIService AI.registerAIService()}:
 *  
 *  <p>
 *  <b>Component-scoped services</b> are only available when the component (or one of its
 *  descendants) has focus.  They let a specific screen, form, or widget add its own AI
 *  capabilities without affecting the rest of the application, and they shadow any global
 * service of the same name.  Register them with {@link
 * com.smartgwt.client.widgets.Canvas#registerAIService Canvas.registerAIService()}:
 *  
 *  <p>
 *  <h3>Service discovery</h3>
 * When {@link com.smartgwt.client.ai.AI#delegate AI.delegate()} is called, it resolves the set of
 * available services by walking
 *  the component hierarchy from <code>context.focusCanvas</code> upward, merging each
 *  ancestor's services with the global registry.  Component-scoped services shadow global
 *  ones of the same name; nearest ancestor wins over farther.  See
 *  {@link com.smartgwt.client.ai.AI#getAIServicesForContext AI.getAIServicesForContext()}.
 * 
 *  <h3>Customizing the delegator</h3>
 *  The prompts the AIDelegator sends to the AI are fully customizable via
 * {@link com.smartgwt.client.ai.AI#delegatorPrompts delegatorPrompts} &mdash; you can override
 * the intro text, the primer before the
 *  service list, and the decision prompt itself.  No code changes are required.
 * 
 *  <h3>Invocation</h3>
 * {@link com.smartgwt.client.ai.AI#delegate AI.delegate()} is the primary entry point.  It
 * accepts the user's prompt, an
 *  optional context object (<code>{rootCanvas, focusCanvas}</code>), and an optional
 * completion callback.  Built-in UI &mdash; AIAssistItem and {@link
 * com.smartgwt.client.util.VoiceAssist}
 *  &mdash; route through it automatically; application code typically does not call it
 *  directly except when building its own entry points.
 * 
 *  <h3>Error handling</h3>
 * If no services are registered, {@link com.smartgwt.client.ai.AI#delegate AI.delegate()} logs a
 * warning and returns.  If only
 *  one service is registered, it is invoked directly with no AI call.  If the AI call fails
 *  (timeout, mock replay mismatch) or returns a service name that no longer matches any
 *  registered service, the first registered service is invoked as a fallback so the user's
 *  request is never silently dropped.
 */
public interface AiAssist {
}
