
package com.smartgwt.client.docs;

/**
 * <h3>Integrating AI Technology</h3>
 * AI technology is woven into the Smart GWT Framework, not only at a base level, but also
 *  systemically. With only minimal changes to application code, surprisingly sophisticated,
 *  AI-powered enhancements can be enabled that have the ability to turn the users of your
 *  application into power users. For example, users of your application can use natural language
 *  to:
 *  <ul>
 * <li>Filter a {@link com.smartgwt.client.widgets.grid.ListGrid} according to their description
 * of the records to include or exclude.
 * <li>Add a custom field to a <code>ListGrid</code>, combining data from the underlying
 * dataSource or augmenting
 *      the data with AI-provided knowledge.
 * <li>Sort the data of a <code>ListGrid</code> according to the user's description of how the
 * data should be ordered.
 * <li>Build a custom {@link com.smartgwt.client.widgets.DataBoundComponent} using available
 * dataSources according to the user's
 *      description of what they would like to see.
 *  </ul>
 * 
 *  <h3>The <code>AIEngine</code> class</h3>
 * Communication with AI services is performed by instances of the {@link
 * com.smartgwt.client.ai.AIEngine} class.  Several
 * engines are built-in and don't require registration.  Call {@link
 * com.smartgwt.client.ai.AI#getSupportedEngineIds AI.getSupportedEngineIds()} to
 *  retrieve the current list of built-in engine IDs at runtime, or
 * {@link com.smartgwt.client.ai.AI#getSupportedEngineData AI.getSupportedEngineData()} for full
 * engine configuration including each engine's
 *  <code>apiKeyProperty</code>.
 *  <p>
 *  Each provider requires a developer API key - not the login credentials or OAuth token
 *  associated with a paid consumer account such as ChatGPT Plus or Claude Pro.  Consult your
 *  provider's developer documentation to obtain a separate API key, then set it in your
 * {@link com.smartgwt.client.docs.Server_properties server configuration file} using the property
 * name given
 * by the <code>apiKeyProperty</code> field returned by {@link
 * com.smartgwt.client.ai.AI#getSupportedEngineData AI.getSupportedEngineData()}.
 *  <p>
 *  Note that some built-in engines do not support vision requests.  Call
 * {@link com.smartgwt.client.ai.AIEngine#canSupportVisionRequests
 * AIEngine.canSupportVisionRequests()} on a retrieved engine instance to check.
 * 
 *  <h3>Enabling AI</h3>
 *  AI is disabled by default. To enable AI within your application, just set
 * {@link com.smartgwt.client.ai.AI#defaultEngineId defaultEngineId} to a different engine ID if
 * you don't like the default, and then
 *  set {@link com.smartgwt.client.ai.AI#disabled disabled} to <code>false</code>.
 *  <p>
 *  Here is sample Smart GWT code that enables AI using GPT-4.1:
 *  <pre>
 *  AI.setDefaultEngineId("gpt-4.1");
 *  AI.setDisabled(false);</pre>
 *  <b>Note:</b> If your application will need to ask AI to analyze images,
 *  you'll need an <code>AIEngine</code> that supports vision requests.  Call
 * {@link com.smartgwt.client.ai.AIEngine#canSupportVisionRequests
 * AIEngine.canSupportVisionRequests()} on a retrieved engine instance to check, or you
 *  can register your own engine (covered below).
 * 
 *  <h3>AWS Bedrock</h3>
 *  Amazon Bedrock is not a model in itself but a managed service that provides access to 
 *  multiple foundation models through a single AWS API. Instead of interacting directly with 
 *  a specific AI vendor (as you would with OpenAI, Anthropic or Gemini), you connect to 
 *  Bedrock and select which underlying model to use; Bedrock supports many such models, 
 *  including Mistral, Meta Llama, Amazon's own Titan and Nova engines, Deepseek, and others
 *  (including OpenAI GPT and Anthropic Claude, which you can also connect to directly).
 *  <p>
 *  Therefore, Bedrock is an intermediary layer rather than the actual model provider.  The 
 *  most important thing about Bedrock integration into Smart GWT is that it gives you access
 *  to a wide selection of models from numerous different AI providers, without the need for 
 *  native support for all those different providers.  It also means that billing is done 
 *  through your AWS account rather than directly with the company that is providing the 
 *  underlying AI service.
 *  <p>
 *  Bedrock integration requies a couple of additional <code>server.properties</code> entries,
 *  in addition to the API key:<ul>
 * <li><code><b>Bedrock.api.aws.region</b></code>  Like other AWS services, Bedrock is a regional 
 *      service, so we must connect to the endpoint of the region where you want the inference
 *      to run.  Provide a valid AWS region in this property - for example <code>us-east-2</code>
 *      or <code>eu-central-1</code></li>
 * <li><code><b>Bedrock.api.model</b></code>  As mentioned above, Bedrock itself is not an AI
 * model,
 *      so you must provide the name of the model to use.  This must be a valid modelId or ARN 
 *      that you have access to through the AWS account associated with your API key.  This is 
 *      not a completely straightforward topic and you should consult AWS Bedrock documentation
 *      to work out the correct modelId or ARN to specify</li>
 *  </ul>
 * 
 *  <h3>Adding your own AIEngine</h3>
 * If the built-in {@link com.smartgwt.client.ai.AIEngine AI Engines} aren't enough, even with
 * Bedrock support, you 
 *  can implement your own for the generative AI service that you would like to use, and 
 * {@link com.smartgwt.client.ai.AI#registerEngine register} it with the Framework.  You can then
 * set your engine's
 *  ID into {@link com.smartgwt.client.ai.AI#defaultEngineId defaultEngineId}.
 *  <p>
 * You can also {@link com.smartgwt.client.ai.AI#unregisterEngine unregister} an engine, or grab
 * the
 *  <code>AIEngine</code> instance of a built-in or manually registered engine by passing the ID
 *  to {@link com.smartgwt.client.ai.AI#getEngine AI.getEngine()}.
 * 
 *  <h3>AI Component Views and <code>AIServiceMode</code></h3>
 * AI can be used to set up the view settings of a {@link
 * com.smartgwt.client.widgets.grid.ListGrid}, such as filters, sorts,
 *  and record hilites, according to the user's natural-language request for how the records
 *  should be filtered, sorted, and hilited. These AI-generated view settings are saved in the
 *  component {@link com.smartgwt.client.docs.ViewState}.
 *  <p>
 * With each AI component view feature, there is an associated {@link
 * com.smartgwt.client.types.AIServiceMode}
 *  setting that controls the mode for how AI should respond to user requests:
 *  <table border="1">
 *    <tbody>
 *      <tr>
 *        <td>Filtering</td>
 *   <td>{@link com.smartgwt.client.widgets.grid.ListGrid#getFilterViaAIMode filterViaAIMode}</td>
 *      </tr>
 *      <tr>
 *        <td>Sorting</td>
 *  <td>{@link com.smartgwt.client.widgets.DataBoundComponent#getSortViaAIMode sortViaAIMode}</td>
 *      </tr>
 *      <tr>
 *        <td>Hiliting</td>
 *   <td>{@link com.smartgwt.client.widgets.grid.ListGrid#getHiliteViaAIMode hiliteViaAIMode}</td>
 *      </tr>
 *    </tbody>
 *  </table>
 *  <p>
 *  With respect to AI component views, the supported AI service modes are:
 *  <ul>
 *  <li>AI Assist - AI drives existing UI on the user's behalf according to the request.
 *  An example of this is: AI converts the user's description of what records they would like
 * to see into {@link com.smartgwt.client.data.AdvancedCriteria} that is then set as the filter
 * criterion of a
 *  <code>DataBoundComponent</code>.
 *  <li>AIDE (AI Data Enhance) - per-record augmentation or enhancements provided via AI.
 *  Examples of this are AI-generated fields, where the field values are not derived from the
 *  records, but rather, supplied via AI.
 *  <li>Hybrid - a combination of AI Assist and AIDE, where AI decides whether AI Assist,
 *  AIDE, or some combination of both approaches should be used to best respond to the request.
 *  </ul>
 *  <p>
 *  The amount of interaction with AI is lowest in AI Assist mode. AIDE requires more interaction
 *  with AI, and Hybrid mode requires the most amount of interaction. More interaction with AI
 *  generally requires more time to process the component view request.
 * 
 *  <h4>Requirements for AI Component Views to be Enabled</h4>
 * With respect to a particular {@link com.smartgwt.client.widgets.DataBoundComponent}, the
 * requirements for AI component views
 *  to be enabled are:
 *  <ul>
 *  <li>AI must be enabled: {@link com.smartgwt.client.ai.AI#isEnabled AI.isEnabled()}
 *  <li>A globally-installed {@link com.smartgwt.client.data.DataSource} with a primary key and
 * {@link com.smartgwt.client.data.DataSource#supportsAdvancedCriteria supporting
 * AdvancedCriteria} must be set.
 *  <li>The <code>DataSource</code> cannot have a composite primary key.
 *  <li>The number of data-records must be known, and the total number of records must be less
 * than the DBC's {@link com.smartgwt.client.widgets.DataBoundComponent#getAiMaxRecords
 * aiMaxRecords}.
 *  </ul>
 * 
 *  <h3>Best Practices for Integrating AI</h3>
 *  Smart GWT handles the process of assembling the context to AI automatically. There
 *  are, however, places where you can add application-specific context to improve AI's
 *  understanding of your application:
 *  <ul>
 * <li>{@link com.smartgwt.client.data.DataSource#getDescription DataSource.description} - An
 * overview description of the data source.
 * <li>{@link com.smartgwt.client.data.DataSource#getSampleData DataSource.sampleData} - Example
 * records that illustrate typical values, formats,
 *  and relationships in the data source.
 * <li>{@link com.smartgwt.client.data.DataSourceField#getDescription DataSourceField.description}
 * - A description of a particular data source field.
 *  </ul>
 *  See the linked APIs for guidance on the type of information to include in each attribute.
 *  <p>
 *  <strong>Important:</strong> Providing inaccurate or misleading information in these
 *  attributes can degrade AI performance and produce poor results.
 */
public interface IntegratingAI {
}
