@memberjunction/skip-types 2.43.0 → 2.45.0

package/readme.md

@@ -19,45 +19,52 @@ npm install @memberjunction/skip-types
 Types used for making requests to the Skip API:
 
 - `SkipAPIRequest` - Base interface for Skip API requests
-- `SkipAPIRequestContext` - Context information for Skip API requests
-- `SkipAPIRequestFilter` - Filter parameters for Skip requests
-- `SkipAPIRequestSort` - Sort parameters for Skip requests
-- `SkipAPIEntityQueryRequest` - Request for entity data queries
-- `SkipAPIDataContextItemRequest` - Request for data context items
-- `SkipAPIConversationRequest` - Request for conversation management
-- `SkipAPIFetchImageRequest` - Request for image fetching
+- `SkipAPIRequestAPIKey` - API key configuration for LLM vendors
+- `SkipAPIRunScriptRequest` - Request to run an existing script
+- `SkipRequestPhase` - Defines the different phases of Skip requests:
+  - `initial_request` - Starting a new conversation or after component creation
+  - `clarify_question_response` - Responding to Skip's clarifying questions
+  - `data_gathering_response` - Returning requested data to Skip
+  - `data_gathering_failure` - Reporting data gathering errors
+  - `run_existing_script` - Running previously processed scripts
+  - `chat_with_a_record` - Simple record chatting feature
 
 ### Response Types
 
 Types used for handling responses from the Skip API:
 
 - `SkipAPIResponse` - Base interface for Skip API responses
-- `SkipAPIEntityQueryResponse` - Response with entity query results
-- `SkipAPIConversationResponse` - Response for conversation operations
-- `SkipAPIImageResponse` - Response for image operations
-- `SkipAPIErrorResponse` - Error response structure
 - `MJAPISkipResult` - Response format from MJAPI to the UI
-- `SkipResponsePhase` - Defines the different phases of Skip responses
+- `SkipResponsePhase` - Defines the different phases of Skip responses:
+  - `status_update` - Status update during processing
+  - `clarifying_question` - Skip needs more information
+  - `data_request` - Skip needs additional data
+  - `analysis_complete` - Analysis finished with results
+  - `chat_with_a_record_complete` - Record chat completed
 
 ### Message and Conversation Types
 
 - `SkipMessage` - Individual message in a conversation with Skip
+  - Includes role, content, conversationDetailID
+  - Optional: error, hiddenToUser, userRating, userFeedback, reflectionInsights
 - `SkipConversation` - Collection of messages forming a conversation
-- `SkipRequestPhase` - Defines the different phases of Skip requests
-- `SkipConversationDetail` - Detailed conversation information
-- `SkipConversationStatus` - Conversation status enum
+  - Includes id, name, userId, messages array
+  - Optional: description, artifacts
 
-### Report Types
+### Component Types
 
-Types for Skip-generated reports and visualizations:
+Types for Skip-generated components and visualizations:
 
-- `SkipHTMLReport` - HTML-based report generated by Skip
-- `SkipHTMLReportCallbacks` - Interface for callbacks from HTML reports
-- `SkipHTMLReportInitFunction` - Initialization function for HTML reports
-- `SkipReportAction` - Actions that can be performed on reports
-- `SkipReportEvent` - Events that can occur in reports
-- `SkipReportCallbackResponse` - Response from report callbacks
-- `SimpleDataContext` - Simplified data context for HTML reports
+- `SkipComponent` - Component generated by Skip
+- `SkipComponentCallbacks` - Interface for callbacks from components:
+  - `RefreshData()` - Refresh the data context
+  - `OpenEntityRecord(entityName, key)` - Open a specific record
+  - `UpdateUserState(userState)` - Update user-specific state
+  - `NotifyEvent(eventName, eventData)` - Send custom events
+- `SkipComponentInitFunction` - Initialization function for components
+- `SkipComponentObject` - Interface exposed by components
+- `SkipComponentOption` - Alternative component options
+- `SimpleDataContext` - Simplified data context for components
 
 ### Learning Cycle Types
 
@@ -66,25 +73,42 @@ Types for Skip-generated reports and visualizations:
 - `SkipAPIAgentNote` - Notes that Skip can generate during learning
 - `SkipAPIAgentNoteType` - Types of notes Skip can generate
 - `SkipAPIAgentRequest` - Format for Skip's human-in-the-loop requests
+- `SkipLearningCycleQueryChange` - Query changes during learning
+- `SkipLearningCycleRequestChange` - Request changes during learning
+- `SkipLearningCycleNoteChange` - Note changes during learning
 
 ### Data Types
 
 - `SkipDataRequest` - Format for Skip to request additional data
-- `SkipDataRequestType` - Types of data requests Skip can make
+- `SkipDataRequestType` - Types of data requests Skip can make:
+  - `sql` - Fully executable SQL statement
+  - `stored_query` - Stored query from Queries entity
 - `SkipSubProcessResponse` - Results from sandboxed script execution
 - `SkipEntityInfo` - Entity metadata information for Skip
 - `SkipEntityFieldInfo` - Field metadata for entities
+- `SkipEntityFieldValueInfo` - Possible values for entity fields
 - `SkipEntityRelationshipInfo` - Relationship metadata for entities
-- `SkipDataContextItem` - Data context item structure
-- `SkipDataContextItemType` - Types of data context items
-- `SkipDataContextItemSource` - Source of data context items
+- `SkipQueryInfo` - Stored query information
+- `SkipQueryFieldInfo` - Field information for queries
+- `SkipColumnInfo` - Column information for report data
 
 ### Specialized Response Types
 
 - `SkipAPIAnalysisCompleteResponse` - Response for completed analysis
+  - Includes dataContext, resultType, executionResults
+  - Optional: component, drillDown, scriptText, newDataItems
 - `SkipAPIClarifyingQuestionResponse` - Response when Skip needs clarification
 - `SkipAPIDataRequestResponse` - Response when Skip needs more data
 - `SkipAPIChatWithRecordResponse` - Response for chat-with-record feature
+- `SkipAPIAnalysisDrillDown` - Drill-down information for reports
+- `SkipAPIAnalysisDrillDownFilter` - Individual drill-down filter
+
+### Artifact Types
+
+- `SkipAPIArtifact` - Artifact information with versions
+- `SkipAPIArtifactType` - Artifact type definition
+- `SkipAPIArtifactVersion` - Version information for artifacts
+- `SkipAPIArtifactRequest` - Request to create/update artifacts
 
 ## Usage Examples
 
@@ -148,17 +172,17 @@ function handleSkipResponse(result: MJAPISkipResult) {
         // Handle plot data from executionResults.plotData
         renderPlot(response.executionResults.plotData);
       } else if (response.resultType === "html") {
-        // Handle custom HTML report
-        renderHTML(response.executionResults.htmlReport);
+        // Handle custom component
+        renderComponent(response.component);
       }
     } else if (result.ResponsePhase === SkipResponsePhase.clarifying_question) {
       // Handle clarifying questions
       const questionResponse = JSON.parse(result.Result) as SkipAPIClarifyingQuestionResponse;
-      promptUserForAnswer(questionResponse.question);
+      promptUserForAnswer(questionResponse.clarifyingQuestion);
     } else if (result.ResponsePhase === SkipResponsePhase.data_request) {
       // Handle data requests
       const dataRequest = JSON.parse(result.Result) as SkipAPIDataRequestResponse;
-      fetchAdditionalData(dataRequest.dataRequests);
+      fetchAdditionalData(dataRequest.dataRequest);
     }
   } else {
     console.error("Skip API request failed:", result.Status);
@@ -166,22 +190,22 @@ function handleSkipResponse(result: MJAPISkipResult) {
 }
 ```
 
-### Working with Skip HTML Reports and Callbacks
+### Working with Skip Components and Callbacks
 
 ```typescript
 import { 
-  SkipHTMLReportInitFunction, 
+  SkipComponentInitFunction, 
   SimpleDataContext, 
-  SkipHTMLReportCallbacks 
+  SkipComponentCallbacks 
 } from '@memberjunction/skip-types';
 
 // Init function that would be called by the container application
-const initReport: SkipHTMLReportInitFunction = (
+const initComponent: SkipComponentInitFunction = (
   data: SimpleDataContext, 
   userState?: any, 
-  callbacks?: SkipHTMLReportCallbacks
+  callbacks?: SkipComponentCallbacks
 ) => {
-  // Initialize the report with the data
+  // Initialize the component with the data
   renderChart(data.data_item_1);
   
   // Set up event handlers that use callbacks
@@ -193,33 +217,102 @@ const initReport: SkipHTMLReportInitFunction = (
     callbacks?.OpenEntityRecord('Customer', { ID: 123 });
   });
   
-  document.getElementById('drill-down').addEventListener('click', () => {
-    callbacks?.DrillDown('SalesRegion', 'Northeast');
-  });
-  
-  document.getElementById('export-data').addEventListener('click', () => {
-    callbacks?.ExportData('csv');
-  });
-  
   // Update user state when something changes
   const newState = { selectedRegion: 'North' };
   callbacks?.UpdateUserState(newState);
 };
 
 // Register the init function globally so it can be called from the container
-window.initSkipReport = initReport;
+window.initSkipComponent = initComponent;
+```
+
+### Working with Learning Cycles
+
+```typescript
+import { 
+  SkipAPILearningCycleRequest,
+  SkipAPILearningCycleResponse,
+  SkipConversation
+} from '@memberjunction/skip-types';
+
+// Create a learning cycle request
+const learningRequest: SkipAPILearningCycleRequest = {
+  organizationId: "org-456",
+  learningCycleId: "cycle-123",
+  newConversations: conversationsSinceLastCycle,
+  entities: entityMetadata,
+  queries: storedQueries,
+  notes: existingNotes,
+  noteTypes: availableNoteTypes,
+  requests: existingRequests,
+  lastLearningCycleDate: lastCycleDate,
+  apiKeys: [
+    {
+      vendorDriverName: "AnthropicLLM",
+      apiKey: "YOUR_API_KEY"
+    }
+  ]
+};
+
+// Handle learning cycle response
+function handleLearningResponse(response: SkipAPILearningCycleResponse) {
+  if (response.success) {
+    // Process note changes
+    response.noteChanges.forEach(change => {
+      if (change.changeType === 'add') {
+        addNote(change.note);
+      } else if (change.changeType === 'update') {
+        updateNote(change.note);
+      } else if (change.changeType === 'delete') {
+        deleteNote(change.note);
+      }
+    });
+    
+    // Process query changes
+    response.queryChanges.forEach(change => {
+      // Handle query additions, updates, deletions
+    });
+    
+    // Process request changes
+    response.requestChanges.forEach(change => {
+      // Handle request changes
+    });
+  } else {
+    console.error("Learning cycle failed:", response.error);
+  }
+}
 ```
 
+## Supported LLM Vendors
+
+The `vendorDriverName` in `SkipAPIRequestAPIKey` supports the following AI providers:
+- `OpenAILLM` - OpenAI models
+- `MistralLLM` - Mistral AI models
+- `GeminiLLM` - Google Gemini models
+- `AnthropicLLM` - Anthropic Claude models
+- `GroqLLM` - Groq models
+
 ## Dependencies
 
 This package relies on the following MemberJunction packages:
+- `@memberjunction/core` - Core MemberJunction types (CompositeKey)
 - `@memberjunction/core-entities` - Core entity definitions
 - `@memberjunction/data-context` - Data context types and utilities
 
+## TypeScript Configuration
+
+This package is built with TypeScript and includes type definitions. No additional @types packages are required.
+
 ## Contributing
 
 Contributions to extend or improve the type definitions are welcome. Please ensure that any additions maintain backward compatibility and follow the established naming conventions.
 
+### Naming Conventions
+- Use PascalCase for class and interface names
+- Prefix Skip-specific types with `Skip`
+- Use descriptive names that clearly indicate the type's purpose
+- Group related types together in the source file
+
 ## License
 
 ISC