@memberjunction/graphql-dataprovider 2.91.0 → 2.93.0

package/dist/index.d.mts

@@ -5,6 +5,479 @@ import { UserViewEntityExtended } from '@memberjunction/core-entities';
 import { Observable } from 'rxjs';
 import { ActionParam, ActionResult, EntityActionInvocationParams, EntityActionResult } from '@memberjunction/actions-base';
 
+/**
+ * Client for executing AI operations through GraphQL.
+ * This class provides an easy way to execute AI prompts and agents from a client application.
+ *
+ * The GraphQLAIClient follows the same naming convention as other GraphQL clients
+ * in the MemberJunction ecosystem, such as GraphQLActionClient and GraphQLSystemUserClient.
+ *
+ * @example
+ * ```typescript
+ * // Create the client
+ * const aiClient = new GraphQLAIClient(graphQLProvider);
+ *
+ * // Run an AI prompt
+ * const promptResult = await aiClient.RunAIPrompt({
+ *   promptId: "prompt-id",
+ *   data: { context: "user data" },
+ *   temperature: 0.7
+ * });
+ *
+ * // Run an AI agent
+ * const agentResult = await aiClient.RunAIAgent({
+ *   agentId: "agent-id",
+ *   messages: [{ role: "user", content: "Hello" }],
+ *   sessionId: "session-123"
+ * });
+ * ```
+ */
+declare class GraphQLAIClient {
+    /**
+     * The GraphQLDataProvider instance used to execute GraphQL requests
+     * @private
+     */
+    private _dataProvider;
+    /**
+     * Creates a new GraphQLAIClient instance.
+     * @param dataProvider The GraphQL data provider to use for queries
+     */
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * Run an AI prompt with the specified parameters.
+     *
+     * This method invokes an AI prompt on the server through GraphQL and returns the result.
+     * Parameters are automatically serialized as needed, and results are parsed for consumption.
+     *
+     * @param params The parameters for running the AI prompt
+     * @returns A Promise that resolves to a RunAIPromptResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await aiClient.RunAIPrompt({
+     *   promptId: "prompt-id",
+     *   data: { key: "value" },
+     *   temperature: 0.7,
+     *   topP: 0.9
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Output:', result.output);
+     *   console.log('Parsed Result:', result.parsedResult);
+     * } else {
+     *   console.error('Error:', result.error);
+     * }
+     * ```
+     */
+    RunAIPrompt(params: RunAIPromptParams): Promise<RunAIPromptResult>;
+    /**
+     * Prepares variables for the AI prompt mutation
+     * @param params The prompt parameters
+     * @returns The prepared variables for GraphQL
+     * @private
+     */
+    private preparePromptVariables;
+    /**
+     * Processes the result from the AI prompt mutation
+     * @param result The raw GraphQL result
+     * @returns The processed RunAIPromptResult
+     * @private
+     */
+    private processPromptResult;
+    /**
+     * Handles errors in the AI prompt execution
+     * @param e The error
+     * @returns An error result
+     * @private
+     */
+    private handlePromptError;
+    /**
+     * Run an AI agent with the specified parameters.
+     *
+     * This method invokes an AI agent on the server through GraphQL and returns the result.
+     * The agent can maintain conversation context across multiple interactions.
+     *
+     * @param params The parameters for running the AI agent
+     * @returns A Promise that resolves to a RunAIAgentResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await aiClient.RunAIAgent({
+     *   agentId: "agent-id",
+     *   messages: [
+     *     { role: "user", content: "What's the weather like?" }
+     *   ],
+     *   sessionId: "session-123",
+     *   data: { location: "New York" }
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Response:', result.payload);
+     *   console.log('Execution time:', result.executionTimeMs, 'ms');
+     * } else {
+     *   console.error('Error:', result.errorMessage);
+     * }
+     * ```
+     */
+    RunAIAgent(params: RunAIAgentParams): Promise<RunAIAgentResult>;
+    /**
+     * Prepares variables for the AI agent mutation
+     * @param params The agent parameters
+     * @returns The prepared variables for GraphQL
+     * @private
+     */
+    private prepareAgentVariables;
+    /**
+     * Processes the result from the AI agent mutation
+     * @param result The raw GraphQL result
+     * @returns The processed RunAIAgentResult
+     * @private
+     */
+    private processAgentResult;
+    /**
+     * Handles errors in the AI agent execution
+     * @param e The error
+     * @returns An error result
+     * @private
+     */
+    private handleAgentError;
+    /**
+     * Execute a simple prompt without requiring a stored AI Prompt entity.
+     * This method is designed for interactive components that need quick AI responses.
+     *
+     * @param params The parameters for the simple prompt execution
+     * @returns A Promise that resolves to a SimplePromptResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await aiClient.ExecuteSimplePrompt({
+     *   systemPrompt: "You are a helpful assistant",
+     *   messages: [
+     *     { message: "What's the weather?", role: "user" }
+     *   ],
+     *   modelPower: "medium"
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Response:', result.result);
+     *   if (result.resultObject) {
+     *     console.log('Parsed JSON:', JSON.parse(result.resultObject));
+     *   }
+     * }
+     * ```
+     */
+    ExecuteSimplePrompt(params: ExecuteSimplePromptParams): Promise<SimplePromptResult>;
+    /**
+     * Generate embeddings for text using local embedding models.
+     * This method is designed for interactive components that need fast similarity calculations.
+     *
+     * @param params The parameters for embedding generation
+     * @returns A Promise that resolves to an EmbedTextResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await aiClient.EmbedText({
+     *   textToEmbed: ["Hello world", "How are you?"],
+     *   modelSize: "small"
+     * });
+     *
+     * console.log('Embeddings:', result.embeddings);
+     * console.log('Model used:', result.modelName);
+     * console.log('Dimensions:', result.vectorDimensions);
+     * ```
+     */
+    EmbedText(params: EmbedTextParams): Promise<EmbedTextResult>;
+}
+/**
+ * Parameters for executing a simple prompt
+ */
+interface ExecuteSimplePromptParams {
+    /**
+     * The system prompt to set context for the model
+     */
+    systemPrompt: string;
+    /**
+     * Optional message history
+     */
+    messages?: Array<{
+        message: string;
+        role: 'user' | 'assistant';
+    }>;
+    /**
+     * Preferred model names to use
+     */
+    preferredModels?: string[];
+    /**
+     * Power level for model selection
+     */
+    modelPower?: 'lowest' | 'medium' | 'highest';
+    /**
+     * Response format (e.g., "json")
+     */
+    responseFormat?: string;
+}
+/**
+ * Result from executing a simple prompt
+ */
+interface SimplePromptResult {
+    /**
+     * Whether the execution was successful
+     */
+    success: boolean;
+    /**
+     * The text response from the model
+     */
+    result?: string;
+    /**
+     * Parsed JSON object if the response contained JSON
+     */
+    resultObject?: any;
+    /**
+     * Name of the model used
+     */
+    modelName: string;
+    /**
+     * Error message if execution failed
+     */
+    error?: string;
+    /**
+     * Execution time in milliseconds
+     */
+    executionTimeMs?: number;
+}
+/**
+ * Parameters for generating text embeddings
+ */
+interface EmbedTextParams {
+    /**
+     * Text or array of texts to embed
+     */
+    textToEmbed: string | string[];
+    /**
+     * Size of the embedding model to use
+     */
+    modelSize: 'small' | 'medium';
+}
+/**
+ * Result from generating text embeddings
+ */
+interface EmbedTextResult {
+    /**
+     * Single embedding vector or array of vectors
+     */
+    embeddings: number[] | number[][];
+    /**
+     * Name of the model used
+     */
+    modelName: string;
+    /**
+     * Number of dimensions in each vector
+     */
+    vectorDimensions: number;
+    /**
+     * Error message if generation failed
+     */
+    error?: string;
+}
+/**
+ * Parameters for running an AI prompt
+ */
+interface RunAIPromptParams {
+    /**
+     * The ID of the AI prompt to run
+     */
+    promptId: string;
+    /**
+     * Data context to pass to the prompt (will be JSON serialized)
+     */
+    data?: Record<string, any>;
+    /**
+     * Override the default model ID
+     */
+    overrideModelId?: string;
+    /**
+     * Override the default vendor ID
+     */
+    overrideVendorId?: string;
+    /**
+     * Configuration ID to use
+     */
+    configurationId?: string;
+    /**
+     * Skip validation of the prompt
+     */
+    skipValidation?: boolean;
+    /**
+     * Template data for prompt templating (will be JSON serialized)
+     */
+    templateData?: Record<string, any>;
+    /**
+     * Response format (e.g., "json", "text")
+     */
+    responseFormat?: string;
+    /**
+     * Temperature parameter for the model (0.0 to 1.0)
+     */
+    temperature?: number;
+    /**
+     * Top-p sampling parameter
+     */
+    topP?: number;
+    /**
+     * Top-k sampling parameter
+     */
+    topK?: number;
+    /**
+     * Min-p sampling parameter
+     */
+    minP?: number;
+    /**
+     * Frequency penalty parameter
+     */
+    frequencyPenalty?: number;
+    /**
+     * Presence penalty parameter
+     */
+    presencePenalty?: number;
+    /**
+     * Random seed for reproducible outputs
+     */
+    seed?: number;
+    /**
+     * Stop sequences for the model
+     */
+    stopSequences?: string[];
+    /**
+     * Include log probabilities in the response
+     */
+    includeLogProbs?: boolean;
+    /**
+     * Number of top log probabilities to include
+     */
+    topLogProbs?: number;
+    /**
+     * Conversation messages (will be JSON serialized)
+     */
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /**
+     * ID of a previous prompt run to rerun from
+     */
+    rerunFromPromptRunID?: string;
+    /**
+     * Override the system prompt
+     */
+    systemPromptOverride?: string;
+}
+/**
+ * Result from running an AI prompt
+ */
+interface RunAIPromptResult {
+    /**
+     * Whether the prompt execution was successful
+     */
+    success: boolean;
+    /**
+     * The output from the prompt
+     */
+    output?: string;
+    /**
+     * Parsed result data (if applicable)
+     */
+    parsedResult?: any;
+    /**
+     * Error message if the execution failed
+     */
+    error?: string;
+    /**
+     * Execution time in milliseconds
+     */
+    executionTimeMs?: number;
+    /**
+     * Number of tokens used
+     */
+    tokensUsed?: number;
+    /**
+     * ID of the prompt run record
+     */
+    promptRunId?: string;
+    /**
+     * Raw result from the model
+     */
+    rawResult?: string;
+    /**
+     * Validation result data
+     */
+    validationResult?: any;
+    /**
+     * Chat completion result data
+     */
+    chatResult?: any;
+}
+/**
+ * Parameters for running an AI agent
+ */
+interface RunAIAgentParams {
+    /**
+     * The ID of the AI agent to run
+     */
+    agentId: string;
+    /**
+     * Conversation messages
+     */
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    /**
+     * Session ID for maintaining conversation context
+     */
+    sessionId: string;
+    /**
+     * Data context to pass to the agent (will be JSON serialized)
+     */
+    data?: Record<string, any>;
+    /**
+     * Template data for agent templating (will be JSON serialized)
+     */
+    templateData?: Record<string, any>;
+    /**
+     * ID of the last agent run for context continuity
+     */
+    lastRunId?: string;
+    /**
+     * Auto-populate the last run payload
+     */
+    autoPopulateLastRunPayload?: boolean;
+    /**
+     * Configuration ID to use
+     */
+    configurationId?: string;
+}
+/**
+ * Result from running an AI agent
+ */
+interface RunAIAgentResult {
+    /**
+     * Whether the agent execution was successful
+     */
+    success: boolean;
+    /**
+     * Error message if the execution failed
+     */
+    errorMessage?: string;
+    /**
+     * Execution time in milliseconds
+     */
+    executionTimeMs?: number;
+    /**
+     * The agent's response payload (parsed from JSON)
+     */
+    payload?: any;
+}
+
 /**************************************************************************************************************
  * The graphQLDataProvider provides a data provider for the entities framework that uses GraphQL to communicate
  * with the server.
@@ -67,7 +540,14 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
     private _client;
     private _configData;
     private _sessionId;
+    private _aiClient;
     get ConfigData(): GraphQLProviderConfigData;
+    /**
+     * Gets the AI client for executing AI operations through GraphQL.
+     * The client is lazily initialized on first access.
+     * @returns The GraphQLAIClient instance
+     */
+    get AI(): GraphQLAIClient;
     /**
      * This getter is not implemented for the GraphQLDataProvider class.
      */
@@ -498,6 +978,92 @@ declare class GraphQLSystemUserClient {
      * @returns Promise containing the result of the query deletion
      */
     DeleteQuery(ID: string, options?: DeleteQueryOptionsInput): Promise<DeleteQueryResult>;
+    /**
+     * Run an AI prompt with system user privileges.
+     * This method allows system-level execution of AI prompts without user authentication.
+     *
+     * @param params The parameters for running the AI prompt
+     * @returns A Promise that resolves to a RunAIPromptResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await systemClient.RunAIPrompt({
+     *   promptId: "prompt-id",
+     *   data: { systemData: "value" },
+     *   skipValidation: true
+     * });
+     * ```
+     */
+    RunAIPrompt(params: RunAIPromptParams): Promise<RunAIPromptResult>;
+    /**
+     * Run an AI agent with system user privileges.
+     * This method allows system-level execution of AI agents without user authentication.
+     *
+     * @param params The parameters for running the AI agent
+     * @returns A Promise that resolves to a RunAIAgentResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await systemClient.RunAIAgent({
+     *   agentId: "agent-id",
+     *   messages: [{ role: "system", content: "Process data" }],
+     *   sessionId: "system-session"
+     * });
+     * ```
+     */
+    RunAIAgent(params: RunAIAgentParams): Promise<RunAIAgentResult>;
+    /**
+     * Helper method to prepare prompt variables for GraphQL
+     * @private
+     */
+    private preparePromptVariables;
+    /**
+     * Helper method to prepare agent variables for GraphQL
+     * @private
+     */
+    private prepareAgentVariables;
+    /**
+     * Helper method to process prompt results
+     * @private
+     */
+    private processPromptResult;
+    /**
+     * Helper method to process agent results
+     * @private
+     */
+    private processAgentResult;
+    /**
+     * Execute a simple prompt without requiring a stored AI Prompt entity.
+     * This method allows system-level execution of simple prompts.
+     *
+     * @param params The parameters for the simple prompt execution
+     * @returns A Promise that resolves to a SimplePromptResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await systemClient.ExecuteSimplePrompt({
+     *   systemPrompt: "You are a data analyst",
+     *   modelPower: "medium"
+     * });
+     * ```
+     */
+    ExecuteSimplePrompt(params: ExecuteSimplePromptParams): Promise<SimplePromptResult>;
+    /**
+     * Generate embeddings using local embedding models.
+     * This method allows system-level generation of text embeddings.
+     *
+     * @param params The parameters for embedding generation
+     * @returns A Promise that resolves to an EmbedTextResult object
+     *
+     * @example
+     * ```typescript
+     * const result = await systemClient.EmbedText({
+     *   textToEmbed: ["System data", "Configuration"],
+     *   modelSize: "small"
+     * });
+     * ```
+     */
+    EmbedText(params: EmbedTextParams): Promise<EmbedTextResult>;
 }
 /**
  * Output type for GetData calls - contains results from executing multiple SQL queries
@@ -1469,4 +2035,4 @@ declare class GraphQLActionClient {
     private handleEntityActionError;
 }
 
-export { ActionItemInput, ActionItemOutput, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, FieldMapper, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, GraphQLActionClient, GraphQLDataProvider, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTransactionGroup, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, RoleInput, RolesAndUsersInput, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };
+export { ActionItemInput, ActionItemOutput, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, GraphQLAIClient, GraphQLActionClient, GraphQLDataProvider, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTransactionGroup, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, RoleInput, RolesAndUsersInput, type RunAIAgentParams, type RunAIAgentResult, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };