AI Agent Integration

interface AgentConfig {
  /**
   * Available AI models for the agent
   */
  models: ModelConfig[];
}

interface ModelConfig {
  /**
   * Model identifier/name
   * Used to reference the model in requests
   */
  name: string;
  
  /**
   * AI provider (currently only "openai" supported)
   */
  provider: string;
  
  /**
   * Specific model name from the provider
   * Examples: "gpt-4", "gpt-3.5-turbo", "gpt-4-turbo"
   */
  model: string;
  
  /**
   * API key for the provider
   * Should be kept secure and not committed to version control
   */
  apiKey: string;
}

// POST /apps/:appId/agent
interface AgentRequest {
  /**
   * User's natural language query or request
   * Examples: "Show me all users created today"
   *          "Delete all posts with empty content"
   *          "Create a new class called Product"
   */
  message: string;
  
  /**
   * Name of the AI model to use
   * Must match a configured model name
   */
  modelName: string;
  
  /**
   * Optional conversation ID for context
   * Allows multi-turn conversations with context
   */
  conversationId?: string;
  
  /**
   * Operation permissions for this request
   * Controls what the AI agent is allowed to do
   */
  permissions: AgentPermissions;
}

interface AgentPermissions {
  /**
   * Allow creating new objects/records
   */
  createObject: boolean;
  
  /**
   * Allow updating existing objects/records
   */
  updateObject: boolean;
  
  /**
   * Allow deleting objects/records
   */
  deleteObject: boolean;
  
  /**
   * Allow creating new classes/tables
   */
  createClass: boolean;
  
  /**
   * Allow deleting classes/tables
   */
  deleteClass: boolean;
}

interface AgentResponse {
  /**
   * AI-generated response to the user
   */
  response: string;
  
  /**
   * Conversation ID for continued context
   */
  conversationId: string;
  
  /**
   * Debug information including operations performed
   */
  debug: {
    timestamp: string;
    appId: string;
    modelUsed: string;
    operations: OperationLog[];
  };
}

interface OperationLog {
  operation: string;
  className?: string;
  resultCount?: number;
  timestamp: string;
}

/**
 * Query objects from a Parse class/table
 */
interface QueryClassFunction {
  name: 'queryClass';
  parameters: {
    className: string;                    // Parse class name
    where?: Record<string, any>;          // Query constraints
    limit?: number;                       // Max results (default 100, max 1000)
    skip?: number;                        // Skip results for pagination
    order?: string;                       // Sort field (prefix with '-' for desc)
    include?: string[];                   // Pointer fields to populate
    select?: string[];                    // Fields to select
  };
}

/**
 * Create a new object in a Parse class
 * Requires user confirmation via confirmed parameter
 */
interface CreateObjectFunction {
  name: 'createObject';
  parameters: {
    className: string;
    objectData: Record<string, any>;      // Required: Field values for new object
    confirmed: boolean;                   // Must be true after user confirmation
  };
}

/**
 * Update an existing object
 * Requires user confirmation via confirmed parameter
 */
interface UpdateObjectFunction {
  name: 'updateObject';
  parameters: {
    className: string;
    objectId: string;                     // Parse object ID
    objectData: Record<string, any>;      // Fields to update
    confirmed: boolean;                   // Must be true after user confirmation
  };
}

/**
 * Delete a single object by ID
 * Requires user confirmation via confirmed parameter
 */
interface DeleteObjectFunction {
  name: 'deleteObject';
  parameters: {
    className: string;
    objectId: string;                     // Parse object ID to delete
    confirmed: boolean;                   // Must be true after user confirmation
  };
}

/**
 * Get schema information for Parse classes
 */
interface GetSchemaFunction {
  name: 'getSchema';
  parameters: {
    className?: string;                   // Optional: specific class, or all if omitted
  };
}

/**
 * Count objects in a Parse class
 */
interface CountObjectsFunction {
  name: 'countObjects';
  parameters: {
    className: string;
    where?: Record<string, any>;          // Optional query constraints
  };
}

/**
 * Create a new Parse class/table
 * Requires user confirmation via confirmed parameter
 */
interface CreateClassFunction {
  name: 'createClass';
  parameters: {
    className: string;
    fields?: Record<string, string>;      // Field definitions (name -> type)
    confirmed: boolean;                   // Must be true after user confirmation
  };
}

/**
 * Delete an entire Parse class/table and all its data
 * Requires user confirmation via confirmed parameter
 */
interface DeleteClassFunction {
  name: 'deleteClass';
  parameters: {
    className: string;
    confirmed: boolean;                   // Must be true after user confirmation
  };
}

// Basic OpenAI integration
const dashboardWithAI = new ParseDashboard({
  apps: [{
    serverURL: 'http://localhost:1337/parse',
    appId: 'myAppId',
    masterKey: 'myMasterKey',
    appName: 'My App'
  }],
  agent: {
    models: [
      {
        name: 'gpt-4',
        provider: 'openai',
        model: 'gpt-4',
        apiKey: process.env.OPENAI_API_KEY
      }
    ]
  }
});

// Multiple AI models
const multiModelConfig = {
  apps: [{ /* app config */ }],
  agent: {
    models: [
      {
        name: 'gpt-4-turbo',
        provider: 'openai',
        model: 'gpt-4-turbo',
        apiKey: process.env.OPENAI_API_KEY
      },
      {
        name: 'gpt-3.5',
        provider: 'openai', 
        model: 'gpt-3.5-turbo',
        apiKey: process.env.OPENAI_API_KEY
      }
    ]
  }
};

// Environment-based configuration
const envAgentConfig = {
  apps: [{ /* app config */ }],
  agent: JSON.parse(process.env.PARSE_DASHBOARD_AGENT || '{}')
};

# AI Agent configuration via environment variable
export PARSE_DASHBOARD_AGENT='{
  "models": [
    {
      "name": "gpt-4",
      "provider": "openai",
      "model": "gpt-4",
      "apiKey": "sk-your-openai-api-key-here"
    }
  ]
}'

# Or using separate environment variables
export OPENAI_API_KEY=sk-your-openai-api-key-here

// Example of calling the AI agent from frontend code
async function queryAIAgent(appId, message, permissions) {
  const response = await fetch(`/apps/${appId}/agent`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Requested-With': 'XMLHttpRequest'
    },
    body: JSON.stringify({
      message: message,
      modelName: 'gpt-4',
      permissions: permissions
    })
  });
  
  return await response.json();
}

// Safe read-only query
const readOnlyResult = await queryAIAgent('myAppId', 
  'Show me all users created in the last 7 days', 
  {
    createObject: false,
    updateObject: false,
    deleteObject: false,
    createClass: false,
    deleteClass: false
  }
);

// Query with write permissions
const writeResult = await queryAIAgent('myAppId',
  'Create a new user with username "john_doe" and email "john@example.com"',
  {
    createObject: true,
    updateObject: false,
    deleteObject: false,
    createClass: false,
    deleteClass: false
  }
);

// Administrative query
const adminResult = await queryAIAgent('myAppId',
  'Create a new class called "Product" with fields: name (string), price (number), category (string)',
  {
    createObject: true,
    updateObject: true,
    deleteObject: false,
    createClass: true,
    deleteClass: false
  }
);

// Data retrieval queries
const queries = [
  "Show me all users who signed up today",
  "Find posts with more than 100 likes",
  "List all products in the 'electronics' category",
  "Get the top 10 users by score",
  "Show me users who haven't logged in for 30 days"
];

// Data modification queries  
const modifications = [
  "Update all users with empty bio to have bio 'No bio provided'",
  "Delete all posts marked as spam",
  "Create a new category called 'Featured'",
  "Set all draft posts to published status",
  "Add a 'verified' field to the User class"
];

// Analytics and reporting queries
const analytics = [
  "How many users signed up each day this week?",
  "What's the average rating for products in each category?",
  "Show me the most popular posts by likes",
  "Generate a summary of user activity patterns",
  "What are the top 5 most common user locations?"
];

// Multi-turn conversation with context
let conversationId = null;

// First query
const result1 = await fetch('/apps/myAppId/agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: "Show me all users from New York",
    modelName: 'gpt-4',
    permissions: { /* read-only permissions */ }
  })
});

const response1 = await result1.json();
conversationId = response1.conversationId;

// Follow-up query with context
const result2 = await fetch('/apps/myAppId/agent', {
  method: 'POST', 
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: "Now show me only the ones who signed up this month",
    modelName: 'gpt-4',
    conversationId: conversationId,  // Maintains context
    permissions: { /* read-only permissions */ }
  })
});

// Strict read-only access
const readOnlyPermissions = {
  createObject: false,
  updateObject: false,
  deleteObject: false,
  createClass: false,
  deleteClass: false
};

// Limited write access (safe operations only)
const limitedWritePermissions = {
  createObject: true,   // Allow creating objects
  updateObject: true,   // Allow updating objects
  deleteObject: false,  // Prevent deletions
  createClass: false,   // Prevent schema changes
  deleteClass: false    // Prevent schema deletions
};

// Full administrative access (use with caution)
const adminPermissions = {
  createObject: true,
  updateObject: true,
  deleteObject: true,   // Dangerous: allows data deletion
  createClass: true,    // Dangerous: allows schema changes
  deleteClass: true     // Very dangerous: allows removing entire classes
};

// Secure API key handling
const secureConfig = {
  agent: {
    models: [
      {
        name: 'gpt-4',
        provider: 'openai',
        model: 'gpt-4',
        apiKey: process.env.OPENAI_API_KEY  // Never hardcode keys
      }
    ]
  }
};

// Environment file (.env)
// OPENAI_API_KEY=sk-your-secret-key-here
// Never commit .env files to version control

// Different AI permissions for different users
const userBasedAI = {
  users: [
    {
      user: 'admin',
      pass: 'adminPass',
      // Admin gets full AI access
    },
    {
      user: 'editor',
      pass: 'editorPass',
      // Editor gets limited AI access
    },
    {
      user: 'viewer', 
      pass: 'viewerPass',
      readOnly: true
      // Viewer gets read-only AI access
    }
  ]
};