lebotfrancais/conversação-análise

  # Conversation Analysis Integration

## Overview

This integration provides enhanced conversation analysis capabilities for your Botpress bot. It serves as a replacement for the AGI/Connor integration, offering more flexibility and control over table configuration, including customizable row factors and LLM model selection.

## Features

- **Flexible Table Management**: Create or duplicate conversation analysis tables with custom configurations
- **Customizable Row Factor**: Choose your preferred row factor for table optimization
- **LLM Model Selection**: Select from different LLM models for conversation analysis
- **AI-Powered Analysis**: Automatically analyze conversations for topics, sentiment, resolution status, and escalations
- **Comprehensive Schema**: Built-in schema for tracking conversation transcripts, summaries, and metadata

## Actions

### 1. Duplicate Table (`duplicate`)

Use this action when you want to preserve existing conversation data from an AGI/Connor integration table.

**When to use:**
- You're migrating from AGI/Connor integration
- You want to keep existing conversation analysis data
- You need to create a copy of an existing table with different settings

**Parameters:**
- `sourceTableId` (required): ID of the existing table to duplicate
- `newTableName` (required): Name for the new duplicated table
- `factor` (optional, default: 3): Row factor for table optimization
- `tags` (optional): Custom tags to apply to the new table
- `frozen` (optional, default: false): Whether the table should be frozen

### 2. Create From Scratch (`createFromScratch`)

Use this action when you want to start fresh with a new conversation analysis table.

**When to use:**
- Setting up a new bot
- You don't need to preserve old conversation data
- Starting a fresh conversation analysis implementation

**Parameters:**
- `tableName` (required): Name for the new table
- `factor` (optional, default: 5): Row factor for table optimization
- `tags` (optional): Custom tags to apply to the table
- `frozen` (optional, default: false): Whether the table should be frozen

## Table Schema

The integration creates tables with the following conversation analysis fields:

- **Topics**: AI-identified topics from user conversations
- **Summary**: AI-generated conversation summaries
- **Resolved**: Boolean indicating if the issue was resolved
- **Sentiment**: Overall conversation sentiment (very positive, positive, neutral, negative, very negative)
- **Transcript**: Complete conversation transcript with sender information
- **Escalations**: Moments when conversations were escalated
- **Conversation ID**: Unique identifier for each chat session
- **Date**: Timestamp field for tracking when conversations occurred (preserves original dates during duplication)

## Migration from AGI/Connor Integration

If you're currently using the AGI/Connor integration and want to migrate:

1. **Identify your source table**: by default it's 'Int_Connor_Conversations_Table' (named 'conversations' in the Tables tab) -> get the exact tableId
2. **Use the duplicate action**: Run the `duplicate` action 
3. **Configure settings**: Set your preferred row factor and tags
4. **Update your bot**: Replace the AGI/Connor integration with this one in your bot configuration


## Benefits Over AGI/Connor Integration

- **Customizable Row Factor**: Unlike the fixed settings in AGI/Connor, you can optimize table performance
- **Flexible LLM Selection**: Choose the best LLM model for your use case
- **Enhanced Control**: More granular control over table settings and configurations
- **Better Migration Path**: Seamless migration from existing setups with preserved timestamps
- **Improved Schema**: More comprehensive conversation analysis fields with date tracking
- **Timestamp Preservation**: Original conversation dates are preserved during table duplication

## Getting Started

1. Install the integration in your Botpress workspace
2. Choose between `duplicate` (for migration) or `createFromScratch` (for new setups)
3. Configure your preferred settings (row factor, tags, etc.)
4. Start analyzing conversations with enhanced flexibility and control

## Create the hook
You have to create a hook to populate the table at the end of each conversation (triggered after timeout). 
If needed, change `conversationAnalysisTable` for the real name of your table.

Hook `after conversation end` :

```javascript
const results = await conversationAnalysisTable.createRecord({
    conversationId: event.conversationId,
    transcript: event.state.session.history.length
      ? event.state.session.history.map((h) => ({ sender: h.sender, preview: h.preview }))
      : [{ sender: 'user', preview: event.preview }],
    
    // Automatically set the current date when creating new records
    date: new Date().toISOString(),

    // Added required fields with appropriate defaults for computed columns
    topics: null, // array
    summary: null, // string
    resolved: null, // boolean
    escalations: null // array
  })
```

### Important Notes:
- **Date Field**: The `date` field is automatically populated with the current timestamp when new conversations are recorded
- **Duplication**: When duplicating tables, original conversation dates from the source table are preserved in the `date` field
- **Migration**: This ensures you maintain historical accuracy when migrating from AGI/Connor integration