This file is a merged representation of the entire codebase, combining all repository files into a single document.
Generated by Repopack on: 2024-12-04T15:47:05.581Z

<file_summary>
This section contains a summary of this file.

<purpose>
This file contains a packed representation of the entire repository's contents.
It is designed to be easily consumable by AI systems for analysis, code review,
or other automated processes.
</purpose>

<file_format>
The content is organized as follows:
1. This summary section
2. Repository information
3. Repository structure
4. Repository files, each consisting of:
  - File path as an attribute
  - Full contents of the file
</file_format>

<usage_guidelines>
- This file should be treated as read-only. Any changes should be made to the
  original repository files, not this packed version.
- When processing this file, use the file path to distinguish
  between different files in the repository.
- Be aware that this file may contain sensitive information. Handle it with
  the same level of security as you would the original repository.
</usage_guidelines>

<notes>
- Some files may have been excluded based on .gitignore rules and Repopack's
  configuration.
- Binary files are not included in this packed representation. Please refer to
  the Repository Structure section for a complete list of file paths, including
  binary files.
</notes>

<additional_info>

For more information about Repopack, visit: https://github.com/yamadashy/repopack
</additional_info>

</file_summary>

<repository_structure>
docs/
  Integrations/
    WordPress/
      _category_.json
      eveai_chat_plugin.md
      eveai_sync_plugin.md
      WordPress Basics.md
    _category_.json
  Library/
    _category_.json
    library_basics.md
    processors.md
    retrievers.md
  Specialists/
    _category_.json
    q_a_rag_specialist.md
    specialists_introduction.md
  introduction.md
.gitignore
.repopackignore
docusaurus.config.js
package.json
README.md
repopack.config.json
sidebars.js
</repository_structure>

<repository_files>
This section contains the contents of the repository's files.

<file path="docs/Integrations/WordPress/_category_.json">
{
  "label": "WordPress Integrations",
  "position": 1,
  "link": {
    "type": "generated-index",
    "description": "Learn about the WordPress integration possibilities of Evie"
  }
}
</file>

<file path="docs/Integrations/WordPress/eveai_chat_plugin.md">
---
id: chat-plugin
title: Chat Integration Plugin
description: Add AI chat capabilities to your WordPress site
sidebar_label: Chat Integration
sidebar_position: 3
---

# Chat Integration Plugin (eveai_chat)

The eveai_chat plugin enables you to add Evie's intelligent chat capabilities to any page or post on your WordPress site, allowing visitors to interact with your content through natural language conversations.

## Configuration

After installing and activating the plugin, configure the connection settings:

![Chat Plugin Settings](/img/wordpress-chat-settings.png)

### Connection Settings

| Setting | Description |
|---------|-------------|
| Tenant ID | Your unique tenant identifier (found in API key email) |
| API Key | Your authentication key (found in API key email) |
| Socket URL | Evie's WebSocket endpoint (`https://evie.askeveai.com/`) |
| Auth URL | Authentication endpoint (`https://evie.askeveai.com/api`) |

Click "Save Settings" to store your configuration.

## Adding Chat Widgets

Once configured, you can add chat widgets to your pages or posts using a simple shortcode:

```
[eveai_chat language="en" languages="en,nl,fr,de,es" specialist_id="1"]
```

### Shortcode Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| language | Default chat language | `language="en"` |
| languages | Available languages (comma-separated) | `languages="en,nl,fr,de"` |
| specialist_id | ID of the Q&A RAG Specialist to use | `specialist_id="1"` |

Example implementation on a page:

![Chat Widget Implementation](/img/wordpress-chat-shortcode.png)

## Chat Widget Behavior

### Language Support
- Users can switch languages during conversations via a dropdown menu
- Language changes take effect immediately for new messages
- Previous messages remain in their original language
- Available languages are determined by your Evie tenant configuration

### Conversation Management
- Each page refresh starts a new conversation
- Conversations don't persist across page navigations
- No usage limits are currently implemented

### Widget Display
- Widget appears where the shortcode is placed in your content
- Default height is 75vh (75% of viewport height)
- Supports multiple widgets per page
  - Each widget can have different language and specialist settings
  - All widgets use the same tenant configuration

## Implementation Guidelines

### Best Practices
1. **Specialist Selection**:
   - Use Q&A RAG Specialists only
   - Ensure specialist doesn't require additional parameters
   - Verify specialist ID before implementation
   
2. **Widget Placement**:
   - Consider user experience when placing widgets
   - Test on different screen sizes
   - Avoid placing multiple widgets too close together

3. **Language Configuration**:
   - Set appropriate default language for your audience
   - Only include languages supported by your tenant
   - Provide clear language selection options

### Customization

The widget's appearance can be customized by modifying the plugin's CSS:

1. Locate `eveai-chat-style.css` in the plugin directory
2. Modify styles to match your website's design
3. Test changes across different devices and screen sizes

:::note
Detailed customization instructions are beyond the scope of this documentation. For advanced customization needs, please consult your development team.
:::

## Technical Considerations

- Widgets are displayed at shortcode location
- Multiple widgets can be used within one WordPress instance
  - All widgets must use the same tenant
  - Different specialists can be used for different widgets
- Mobile responsiveness should be considered when placing widgets
- Page refreshes will reset conversations

```mermaid
flowchart TB
    A[Configure Plugin Settings] -->|Save| B[Add Shortcode to Page]
    B --> C[Configure Widget Parameters]
    C --> D[Test Implementation]
    D --> E[Customize Appearance]
    style B fill:#3ecc5f,stroke:#333,stroke-width:2px
```

## Troubleshooting

| Issue | Possible Solution |
|-------|------------------|
| Widget not appearing | Verify shortcode syntax |
| Connection errors | Check API credentials |
| Invalid specialist errors | Verify specialist_id exists and is a Q&A RAG Specialist |
| Language not available | Confirm language is enabled in tenant configuration |

For additional support or custom implementation needs, contact your Evie support representative.
</file>

<file path="docs/Integrations/WordPress/eveai_sync_plugin.md">
---
id: sync-plugin
title: Content Synchronization Plugin
description: Automatically sync your WordPress content with Evie
sidebar_label: Content Sync
sidebar_position: 2
---

# Content Synchronization Plugin (eveai_sync)

The eveai_sync plugin automatically synchronizes your WordPress content with Evie's knowledge base, ensuring that your AI interactions always have access to your latest content.

## Configuration

After installing and activating the plugin, you'll need to configure several settings to connect with Evie:

![Sync Plugin Settings](/img/wordpress-sync-settings.png)

### Basic Settings

| Setting | Description |
|---------|-------------|
| API URL | The base URL for Evie's API (`https://eveai.askeveai.com`) |
| Tenant ID | Your unique tenant identifier (found in your API key email) |
| API Key | Your authentication key for the API (found in your API key email) |
| Catalog ID | The ID of the Evie catalog where content will be stored |
| Default Language | The primary language of your content |
| Excluded Categories | Comma-separated list of WordPress categories to exclude from syncing |

Click "Save Settings" to store your configuration.

## Initial Content Sync

When setting up the plugin for the first time, you'll need to perform an initial bulk sync of your existing content:

1. Configure all settings as described above
2. Click the "Start Bulk Sync" button
3. Wait for the sync to complete
   - A log will be displayed after the sync finishes
   - The process cannot be interrupted once started
   - All published posts and pages (except excluded categories) will be uploaded to Evie

```mermaid
flowchart TB
    A[Configure Settings] -->|Save| B[Start Bulk Sync]
    B --> C[Upload Content]
    C --> D[Process Content]
    D --> E[Sync Complete]
    style B fill:#3ecc5f,stroke:#333,stroke-width:2px
```

## Automatic Synchronization

After the initial setup, the plugin automatically maintains synchronization between your WordPress site and Evie:

### What Gets Synced?

✅ **Synchronized**:
- Published posts and pages
- Content updates to existing posts/pages
- HTML content and formatting

❌ **Not Synchronized**:
- Draft content
- Private or password-protected content
- Posts/pages in excluded categories

### Sync Behaviors

The plugin handles different content changes automatically:

| Action in WordPress | Result in Evie                         |
|--------------------|----------------------------------------|
| New post/page published | Creates new document in Evie           |
| Existing content updated | Creates a new document version in Evie |
| Content deleted | Marks document as invalid in Evie*     |

*Note: Documents are never deleted from Evie to preserve historical interaction context.

### Processing Status

While content synchronization happens automatically, the actual processing in Evie occurs asynchronously:
- Content is immediately sent to Evie when changes occur
- Processing status can be monitored in Evie's administrative interface
- Final processing time depends on network conditions and content complexity

## Resetting the Integration

If you need to start fresh (for example, when switching to a different catalog), you can reset the integration:

1. Click the "Reinitialize Site" button
2. All Evie metadata will be removed from your WordPress site
3. Sync status for all content will be reset
4. You can then reconfigure the plugin and perform a new bulk sync

:::caution
Reinitializing the site only affects the WordPress-Evie connection metadata. It does not delete any content from either WordPress or Evie.
:::

## Best Practices

To get the most out of the content synchronization:

1. **Initial Setup**:
   - Configure and test settings before starting bulk sync
   - Choose excluded categories carefully

2. **Content Management**:
   - Publish content only when it's ready for AI consumption
   - Maintain consistent content structure for better AI interactions

3. **Monitoring**:
   - Regularly check Evie's administrative interface for processing status
   - Review AI interactions to ensure content is being utilized effectively

## Technical Considerations

- The plugin handles HTML content, preserving your content's formatting
- No special catalog configuration is required in Evie
- There are no size limitations for WordPress sites
- Network connectivity affects sync speed and reliability
</file>

<file path="docs/Integrations/WordPress/WordPress Basics.md">
---
id: wordpress-overview
title: WordPress Integration
description: Overview of Evie's WordPress integration capabilities
sidebar_label: Overview
sidebar_position: 1
---

# WordPress Integration

Evie offers seamless integration with WordPress through two dedicated plugins that help you enhance your WordPress site with AI capabilities. These plugins allow you to both synchronize your content with Evie's knowledge base and provide intelligent chat functionality to your visitors.

## Available Plugins

### Content Synchronization (eveai_sync)
The content synchronization plugin automatically keeps your Evie knowledge base up-to-date with your WordPress content:
- Syncs posts and pages to Evie's Standard Catalog
- Maintains versioning of your content
- Ensures your AI interactions always use the latest content

### Chat Integration (eveai_chat)
Add intelligent chat capabilities to your WordPress site:
- Easy-to-integrate chat widget
- Powered by Evie's Q&A RAG Specialist
- Supports multiple languages
- Simple configuration and setup

## Prerequisites

Before you can use either plugin, you'll need:

1. A WordPress website
2. An Evie account with API access
3. An API key from Ask Eve AI

## Getting Started

### Obtaining Your API Key

To use the WordPress plugins, you'll need an API key from Ask Eve AI. You can ask your AskEveAI administrator to provide you
with an API Key. After the request, you'll receive an email containing:
- Your tenant information
- A unique API key
- Enabled services information

Here's an example of the API key email you'll receive:

![API Key Email Example](/img/wordpress-api-email.png)

:::important
Store your API key securely. It cannot be retrieved once the email is gone.
:::

```mermaid
flowchart LR
    A[Request API Access] -->|Receive Email| B[API Key]
    B --> C[Configure Plugins]
    C --> D[Start Using Integration]
```

### Installation

Both plugins can be [downloaded here](https://www.dropbox.com/scl/fo/6pkrp8o1n6rjvawjyrstt/AGGNOGlVn4hAz_BZOngOj68?rlkey=nj9gyz1k0bcjz7sxr0jq5c59l&dl=0)

Both plugins follow the standard WordPress plugin installation process:

1. Download the plugin files
2. Go to your WordPress admin panel
3. Navigate to Plugins > Add New
4. Click "Upload Plugin"
5. Select the plugin file and click "Install Now"
6. Activate the plugin

### Next Steps

After installation, each plugin requires specific configuration:

- [Content Synchronization Setup](./sync-plugin) - Configure how your WordPress content syncs with Evie
- [Chat Integration Setup](./chat-plugin) - Set up the AI chat widget for your website

## Support and Customization

:::important
Aggressive caching in WordPress can cripple correct behaviour of the Chat Plugin
:::

When running into problems:
- Enable debugging in WordPress. We have quite extensive logging in both components.
- For the chatbot itself, you can check the browser console (at least, on Chrome). A lot of debugging information is available.

Both plugins are provided as open-source software, allowing for:
- Custom modifications to match your needs
- Integration with existing WordPress themes
- Extended functionality development

For technical support or questions about customization, please contact our support team.
</file>

<file path="docs/Integrations/_category_.json">
{
  "label": "Integrations",
  "position": 4,
  "link": {
    "type": "generated-index",
    "description": "Learn about the integration possibilities of Evie"
  }
}
</file>

<file path="docs/Library/_category_.json">
{
  "label": "Library",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Learn about the core components of Evie's Library system"
  }
}
</file>

<file path="docs/Library/library_basics.md">
---
id: library_basics
title: Evie's Library Basics
description: Understanding catalogs, documents, and document versions in Evie's Library
sidebar_label: Library Basics
sidebar_position: 1
---

# Evie's Library Basics: Catalogs, Documents & DocumentVersions

## Overview
Evie's Library is an intelligent information storage and retrieval system. It organizes your business information semantically, making it easily accessible and searchable. The library can handle various types of content including HTML pages, PDF documents, and other document formats, storing them in a way that preserves their meaning and context.

## Library Structure
The library is organized into sections called Catalogs, which help group related information together. Each catalog contains Documents, which can have multiple versions to track changes over time.

```mermaid
classDiagram
    class Catalog {
        +name
        +description
        +type (Standard/Dossier)
        +min_chunk_size
        +max_chunk_size
        +user_metadata
    }
    class Document {
        +name
        +valid_from
        +valid_to
    }
    class DocumentVersion {
        +url
        +file_type
        +language
        +user_context
        +processing_status
    }
    
    Catalog "1" -- "*" Document : contains
    Document "1" -- "*" DocumentVersion : has versions
    note for Catalog "Configurable based on type, e.g. Dossier has tagging fields"
    note for DocumentVersion "Processed asynchronously & Generates semantic chunks"
```

### Catalogs
A catalog is a container for related documents. You can create different catalogs to organize your information in ways that make sense for your business. Each catalog has the following key features:

- **Name and Description**: Helps identify the catalog's purpose
- **Type**: Determines how information is organized within the catalog
- **Chunk Size Settings**: Controls how documents are processed for optimal retrieval
- **Custom Metadata**: Allows adding business-specific information

Catalog Types

Standard Catalog

Basic catalog type for general document storage
All stored information is treated as a unified collection
Suitable for most general knowledge bases


Dossier Catalog

Advanced catalog type with tagging capabilities
Allows organizing documents with custom tags
Requires configuration of tagging fields during catalog creation
Example tagging field configuration:



```
{
  "tagging_fields": {
    "company": {
      "type": "string",
      "required": true,
      "description": "Company name"
    },
    "year": {
      "type": "integer",
      "required": false,
      "max_value": 2100,
      "min_value": 1900,
      "description": "Document year"
    },
    "document_type": {
      "type": "enum",
      "required": false,
      "description": "Type of document",
      "allowed_values": [
        "quarterly_report",
        "annual_report",
        "presentation",
        "press_release"
      ]
    },
    "confidentiality": {
      "type": "enum",
      "required": false,
      "description": "Document confidentiality level",
      "allowed_values": [
        "public",
        "internal",
        "confidential"
      ]
    }
  }
}
```

This configuration defines:

- A required company name field as text
- An optional year field (between 1900 and 2100)
- An optional document type selection from predefined options
- An optional confidentiality level selection

### Documents and Versioning
Documents in Evie's Library are managed with version control to ensure information stays current:

- **Basic Document Properties**:
  - Name
  - Validity period (optional)
  - Associated metadata

- **Document Versions**:
  - Track changes in document content
  - Store the actual content and its processing state
  - Support multiple file formats
  - Can be automatically updated for URL-based sources
  - Include language information

### Multilingual Support
Evie's Library has built-in multilingual capabilities:
- Documents in different languages can coexist in the same catalog
- Information can be retrieved regardless of the language it was stored in
- Questions can be asked in any supported language
- No need to store multiple translations of the same document

### Document Processing
When documents are added to the library:

1. They are automatically processed to understand their content
2. Processing happens in the background without interrupting your work
3. Documents are split into semantic chunks for optimal understanding
4. The latest version becomes available once processing is complete

### Using the Library
To make the most of Evie's Library:

1. **Organize Your Information**:
   - Create catalogs based on your business needs
   - Choose between Standard and Dossier catalogs based on whether you need tagging
   - Add relevant metadata to help organize information

2. **Add Documents**:
   - Provide URLs for documents whenever possible (recommended method)
     - URLs allow automatic document refreshing
     - Ensures your library stays up-to-date with source changes
     - Maintains version history automatically
   - File uploads are supported as an alternative
     - Use when URL access isn't available
     - Note: Updates will require manual re-upload

3. **Maintain Your Library**:
   - URL-based documents can be automatically refreshed to stay current
   - Monitor processing status for new additions
   - Manage document validity periods if needed
   - For uploaded files, consider periodically checking if updates are needed

## Best Practices
- Group related documents in the same catalog
- Use meaningful names and descriptions for catalogs and documents
- Add relevant metadata to make information more discoverable
- For Dossier catalogs, establish consistent tagging conventions
- Prefer URL-based documents over file uploads to enable automatic updates
</file>

<file path="docs/Library/processors.md">
---
id: processors
title: Understanding Processors
description: Learn how processors handle different types of files in Evie's Library
sidebar_label: Processors
sidebar_position: 2
---

# Understanding Processors

## Overview

Processors are essential components in Evie's Library that determine how different types of files (HTML, PDF, audio) are processed and stored. Each processor is specifically configured for a catalog and handles one or more file types, ensuring that content is properly extracted, chunked, and stored according to your business needs.

The relationship between Catalogs and Processors is shown in this diagram:

```mermaid
classDiagram
    class Catalog {
        +id: Integer
        +name: String
        +description: Text
        +type: String
        +min_chunk_size: Integer
        +max_chunk_size: Integer
        +user_metadata: JSON
        +system_metadata: JSON
        +configuration: JSON
    }
    class Processor {
        +id: Integer
        +name: String
        +description: Text
        +type: String
        +sub_file_type: String
        +tuning: Boolean
        +user_metadata: JSON
        +system_metadata: JSON
        +configuration: JSON
    }
    
    Catalog "1" -- "*" Processor : has
    note for Processor "Unique per catalog\nConfigured for specific file types"
```

## Key Concepts

### Processor Basics

- **Catalog-Specific**: Each processor is uniquely defined for a specific catalog and cannot be shared across catalogs
- **File Type Support**: Currently supports HTML, PDF, and audio files
- **Optional Usage**: If no processor is specified for a file type, files of that type will not be processed
- **File Size Limits**: Maximum file size of 50MB for all file types

### Sub-File Types

Sub-file types allow you to process different document types within the same catalog using different rules. For example:
- Quarterly reports might have a different structure than project definitions
- News articles might need different processing than product documentation
- Internal memos might require different handling than public announcements

## Types of Processors

### HTML Processor
The HTML processor provides detailed control over how HTML content is processed through various configuration options.
These options define the HTML processing, and they follow a strict process:

1. **Included Elements** (`html_included_elements`)
   - Defines the main sections of the document to process
   - Only content within these elements will be considered
   - Example: `article, main`

2. **Excluded Elements** (`html_excluded_elements`)
   - Elements to remove from included sections
   - Useful for navigation, headers, footers, etc.
   - Example: `header, footer, nav, script`

3. **HTML Tags** (`html_tags`)
   - Specific content tags to process
   - Determines what content is actually stored
   - Example: `p, h1, h2, h3, table`

4. **Excluded Classes** (`html_excluded_classes`)
   - Classes of elements to exclude
   - Useful for removing specific sections like sidebars
   - Example: `sidebar, advertisement`

This is graphically shown in this process flow:

```mermaid
flowchart TD
    A[HTML Document] --> B[Check Included Elements]
    B --> C[Remove Excluded Elements]
    C --> D[Process HTML Tags]
    D --> E[Remove Excluded Classes]
    
    style A fill:#9c2d66,stroke:#333,stroke-width:2px
    style B fill:#423372,stroke:#333,stroke-width:2px
    style C fill:#423372,stroke:#333,stroke-width:2px
    style D fill:#423372,stroke:#333,stroke-width:2px
    style E fill:#423372,stroke:#333,stroke-width:2px

    note1[Only process content within<br>included elements]
    note2[Remove specified elements<br>from included content]
    note3[Include only specified<br>HTML tags]
    note4[Remove content with<br>excluded classes]

    B --- note1
    C --- note2
    D --- note3
    E --- note4
```

Additional HTML processing settings:
- **End Tags** (`html_end_tags`): Defines where chunks can logically end
- **Chunk Sizing**: Respects catalog's min/max chunk sizes while maintaining content coherence

### PDF Processor
- Handles PDF document processing
- No additional configuration required
- Automatically extracts text and maintains document structure

### Audio Processor
- Supports mp3, mp4, and ogg formats
- Automatically transcribes audio content
- No additional configuration required

## Managing Processors

### Creating Processors

When creating a processor, consider:
1. Which catalog it will serve
2. What file type it needs to handle
3. Whether you need a sub-file type
4. Any specific configuration needed (especially for HTML)

### Modifying Processors

- Processors can be modified after creation
- Changes don't automatically apply to already processed documents
- Documents must be manually reprocessed to apply new processor settings

### Processor Tuning

The tuning feature is available for implementation teams to:
- Generate additional processing logs
- Gain insights into exact processing behavior
- Fine-tune processor behavior for specific contexts

Note: Tuning logs are only accessible to implementation teams, not end users.

## Best Practices

1. **Plan Your Structure**
   - Define clear sub-file types based on document characteristics
   - Consider document structure when configuring HTML processors

2. **HTML Processing**
   - Start with broader included elements and narrow down
   - Test configuration with representative documents
   - Use excluded classes for fine-grained control

3. **General Tips**
   - Keep file sizes under the 50MB limit
   - Document your processor configurations
   - Plan for periodic review of processor settings

## Future Extensions

The processor framework is designed for extensibility:
- Additional processor types planned
- Metadata fields ready for future features
- Configuration options may be expanded
</file>

<file path="docs/Library/retrievers.md">
---
id: retrievers
title: Understanding Retrievers
description: Learn how retrievers find and extract relevant information from your documents
sidebar_label: Retrievers
sidebar_position: 3
---

# Understanding Retrievers

## Overview

Retrievers are essential components in Evie's Library that help find and extract relevant information from your documents. 
Think of retrievers as intelligent search engines that understand the meaning behind your questions and find the most 
relevant content from your stored documents.

```mermaid
classDiagram
    class Catalog {
        +id: Integer
        +name: String
        +description: Text
        +type: String
        +min_chunk_size: Integer
        +max_chunk_size: Integer
        +user_metadata: JSON
    }
    
    class Retriever {
        +id: Integer
        +name: String
        +description: Text
        +catalog_id: Integer
        +type: String
        +tuning: Boolean
        +configuration: JSON
        +arguments: JSON
    }
    
    class StandardRAGRetriever {
        +configuration
        es_k: Integer
        es_similarity_threshold: Float
        +arguments
        query: String
    }
    
    class DossierRetriever {
        +configuration
        es_k: Integer
        es_similarity_threshold: Float
        tag_conditions: JSON
        +arguments
        query: String
    }
    
    Catalog "1" -- "*" Retriever : has
    Retriever <|-- StandardRAGRetriever
    Retriever <|-- DossierRetriever
    
    note for StandardRAGRetriever "Default similarity threshold: 0.3<br>Default es_k: 8"
    note for DossierRetriever "Coming soon<br>Specialized for Dossier catalogs"
```
## Key Concepts

### What is a Retriever?

A retriever is responsible for:
- Understanding the meaning of your questions
- Searching through document chunks in your catalog
- Finding the most relevant information based on semantic similarity
- Providing context for Evie's responses

```mermaid
flowchart LR
    A[User Question] --> B[Retriever]
    B --> C[Document Chunks]
    C --> D[Most Relevant Information]
    D --> E[Evie's Response]
    
    style A fill:#9c2d66,stroke:#333,stroke-width:2px
    style B fill:#423372,stroke:#333,stroke-width:2px
    style C fill:#423372,stroke:#333,stroke-width:2px
    style D fill:#423372,stroke:#333,stroke-width:2px
    style E fill:#9c2d66,stroke:#333,stroke-width:2px
```

### How Retrievers Work

When you ask Evie a question, the retriever:
1. Analyzes your question to understand its meaning
2. Compares it with stored document chunks
3. Assigns similarity scores to each chunk
4. Returns the most relevant chunks based on configuration settings

## Types of Retrievers

### Standard RAG Retriever

The Standard RAG (Retrieval-Augmented Generation) Retriever is the default option suitable for most use cases. It 
searches through all documents in a catalog to find relevant information.

Configuration options include:
- **Maximum Results (es_k)**: Controls how many document chunks to retrieve (default: 8)
- **Similarity Threshold**: Determines how closely chunks must match your question (default: 0.3)
  - Lower threshold = stricter matching
  - Higher threshold = more permissive matching

### Dossier Retriever (Coming Soon)

A specialized retriever for Dossier catalogs that will allow:
- Filtering by document tags
- Creating specific "viewpoints" based on tag combinations
- Combining semantic search with tag-based filtering

## Setting Up Retrievers

### Creating a New Retriever

To create a retriever:
1. Enter standard values such as name and description
2. Select the target catalog
3. Choose the retriever type
4. After saving, you will have the ability to set the specific configuration (based on the type)

### Configuration Best Practices

1. **Similarity Threshold Tuning**:
   - Start with the default 0.3 threshold
   - If receiving too much information: Lower the threshold
   - If receiving too little information: Raise the threshold

2. **Multiple Retrievers**:
   You can create multiple retrievers for the same catalog to serve different purposes. For example:
   - A broad retriever with higher threshold for general questions
   - A strict retriever with lower threshold for specific queries
   - Different retrievers for different document subsets (in Dossier catalogs)

## Practical Examples

### Standard RAG Retriever Example

```json
{
  "name": "General Knowledge Retriever",
  "type": "STANDARD_RAG",
  "configuration": {
    "es_k": 8,
    "es_similarity_threshold": 0.3
  }
}
```

### Future Dossier Retriever Example

```json
{
  "name": "Quarterly Reports 2024",
  "type": "DOSSIER_RAG",
  "configuration": {
    "es_k": 8,
    "es_similarity_threshold": 0.3,
    "tag_conditions": {
      "document_type": "quarterly_report",
      "year": 2024
    }
  }
}
```

## Tips for Optimal Retrieval

1. **Name Retrievers Clearly**:
   Use descriptive names that indicate their purpose and configuration

2. **Monitor Performance**:
   - If answers are missing important information, consider:
     - Increasing the similarity threshold
     - Increasing the maximum results (es_k)
   - If answers contain irrelevant information, consider:
     - Decreasing the similarity threshold
     - Decreasing the maximum results

3. **Use Multiple Retrievers**:
   Create specialized retrievers for different use cases within the same catalog
</file>

<file path="docs/Specialists/_category_.json">
{
  "label": "Specialists",
  "position": 3,
  "link": {
    "type": "generated-index",
    "description": "Learn about the Specialists enabling intelligent interactions and task execution"
  }
}
</file>

<file path="docs/Specialists/q_a_rag_specialist.md">
---
id: qa-rag-specialist
title: Q&A RAG Specialist
description: Understand how to configure and use the Q&A RAG Specialist for intelligent conversations
sidebar_label: Q&A RAG Specialist
sidebar_position: 2
---

# Q&A RAG Specialist

## Overview

The Q&A RAG Specialist enables intelligent question-answering interactions using your organization's specific information stored in Evie's Library. Whether supporting customers on your website or helping employees access internal knowledge, this specialist provides accurate, context-aware responses based on your documented information.

## Structure

The Q&A RAG Specialist extends the base Specialist with specific configuration, arguments, and results tailored for question-answering:

```mermaid
classDiagram
    class Specialist {
        +id: Integer
        +name: String
        +description: Text
        +type: String
        +configuration: JSON
        +arguments: JSON
        +results: JSON
    }

    class QARagSpecialist {
        +configuration
        specialist_context: String
        temperature: Float
        +arguments
        language: String
        query: String
        +results
        detailed_query: String
        answer: String
        citations: Array
        insufficient_info: Boolean
    }

    Specialist <|-- QARagSpecialist
```

## Configuration

### Specialist Context
The context defines the specialist's identity and behavior. A well-structured context typically includes:

1. **Identity**
   - The specialist's name
   - Role or position (e.g., company spokesperson)

2. **Reference Handling**
   - How your company/product names might appear
   - Common variations or abbreviations
   - How to handle self-references

3. **Domain Clarity**
   - Clear description of the business domain
   - Disambiguation from similar companies/products
   
Example context:
```json
{
  "specialist_context": "You are Evie, the main spokesperson for 'Ask Eve AI'. 
    'Ask Eve AI' can be spelled in different ways (e.g. askeveai), can be 
    shortened to Evie, and can be referred to as 'you' (as you share the 
    same name as the product, and actually are an impersonation of the 
    product Evie). Ask Eve AI sells an advanced SAAS platform, also called 
    Evie, that enables companies to easily implement business cases based 
    on generative AI, mainly LLMs."
}
```

### Temperature
Controls the balance between creativity and precision in responses:

- **Range**: 0 to 1
- **Default**: 0.3
- **Effect**:
  - Lower values (closer to 0): More conservative, strictly adhering to source content
  - Higher values (closer to 1): More creative, potentially introducing more variation
  - Adjust based on your needs:
    - Increase if responses feel too rigid
    - Decrease if responses take too many liberties with the source material
  - Note: Higher temperatures increase the risk of hallucinations

## Arguments

Arguments required for each interaction:

1. **language**
   - Specifies the desired response language
   - Evie intelligently handles multi-language content
   - Can find relevant information across language barriers
   - Note: While Evie translates answers, it is not a document translation service

2. **query**
   - The actual question from the end user
   - Will be processed considering session context

## Results

The specialist returns structured results for each interaction:

1. **detailed_query**
   - Enhanced version of the original query
   - Incorporates context from previous interactions
   - Helps maintain conversation coherence

2. **answer**
   - The specialist's response to the query
   - Based on retrieved information
   - Formulated according to configuration settings

3. **citations**
   - References to specific embeddings used
   - Traceable back to source document versions
   - Enables verification and source tracking

4. **insufficient_info**
   - Boolean flag indicating information adequacy
   - `true` when library content insufficient for proper response
   - Helps monitor answer quality and identify knowledge gaps

## Integration Notes

While the specialist provides structured arguments and results, these technical details are typically hidden from end users. Client interfaces (such as chat widgets) handle:

- Submitting properly formatted arguments
- Receiving and processing results
- Presenting information in a user-friendly format

This abstraction allows for:
- Clean user experiences
- Consistent interaction patterns
- Technical flexibility for integrators

## Multi-language Capabilities

The Q&A RAG Specialist features advanced language handling:

- Finds relevant content across languages
- Provides responses in requested language
- Maintains context across language switches
- Intelligently translates responses while preserving meaning

For example, English questions can receive relevant information from Dutch documents, with responses properly formulated in English.

---

The next sections cover best practices, common use cases, and integration examples.
</file>

<file path="docs/Specialists/specialists_introduction.md">
---
id: specialists
title: Understanding Specialists - Introduction
description: Learn how specialists use Evie's Library to execute specific tasks
sidebar_label: Specialists Intro
sidebar_position: 1
---

# Understanding Specialists - Introduction

## Overview

Specialists are powerful components in Evie's ecosystem that perform specific activities using information from Evie's Library. Think of specialists as expert assistants, each trained for particular tasks - from answering questions to filling templates or providing specialized support.

## How Specialists Work

Every specialist follows a structured approach:

1. **Information Gathering**: Using one or more retrievers, specialists search Evie's Library for relevant information
2. **Information Processing**: Retrieved information is processed according to the specialist's specific algorithm
3. **Task Execution**: The specialist performs its designated task using:
   - Retrieved information
   - Its configuration settings
   - Provided arguments

```mermaid
flowchart TD
    A[User Request] --> B[Specialist]
    B --> C{Process Arguments}
    C --> D[Evaluate Specialist Arguments]
    D --> E[Push Arguments to Retrievers]
    E --> F[Search Library using Retrievers]
    F --> G[Combine Retrieved Information]
    G --> H[Execute Specialist Algorithm]
    H --> I[Return Results]
    
    style A fill:#9c2d66,stroke:#333,stroke-width:2px
    style B fill:#423372,stroke:#333,stroke-width:2px
    style I fill:#9c2d66,stroke:#333,stroke-width:2px
```

### Key Components

The relationship between specialists and other components is shown in this diagram:

```mermaid
classDiagram
    class Specialist {
        +id: Integer
        +name: String
        +description: Text
        +type: String
        +configuration: JSON
        +arguments: JSON
        +results: JSON
    }
    
    class Retriever {
        +id: Integer
        +name: String
        +catalog_id: Integer
        +type: String
        +configuration: JSON
    }
    
    Specialist "*" -- "*" Retriever : uses
    note for Specialist "Each specialist can use multiple retrievers"
    note for Retriever "Each retriever can be used by multiple specialists"
```

### Sessions and Interactions

Each specialist operates within sessions, managing interactions as shown here:

```mermaid
classDiagram
    class ChatSession {
        +id: Integer
        +session_id: String
        +session_start: DateTime
        +session_end: DateTime
    }
    
    class Interaction {
        +id: Integer
        +chat_session_id: Integer
        +specialist_id: Integer
        +specialist_arguments: JSON
        +specialist_results: JSON
        +question_at: DateTime
        +answer_at: DateTime
    }
    
    class Specialist {
        +id: Integer
        +name: String
        +type: String
    }
    
    ChatSession "1" -- "*" Interaction
    Specialist "1" -- "*" Interaction
```

## Working with Specialists

### Configuration & Arguments

Specialists use three key data structures:

1. **Configuration**
   - Fixed parameters that remain constant during all interactions
   - Defines core behavior settings (e.g., inference parameters)
   - Set during specialist creation

2. **Arguments**
   - Variable parameters passed during each interaction
   - Can change between interactions within a session
   - Example: questions or specific task parameters

3. **Results**
   - Output structure returned after each interaction
   - Contains the specialist's response or task output
   - Format depends on specialist type

### Sessions

- Each session is dedicated to one specialist
- Sessions maintain context across multiple interactions
- Session boundaries are specialist-specific
  - For Q&A specialists: typically aligned with client communication sessions
  - For task-based specialists: may be bound by task completion

### Argument Inheritance

Specialists implement an intelligent argument inheritance mechanism:

1. Arguments can be defined at both specialist and retriever levels
2. When argument names match:
   - Specialist arguments take precedence
   - Retriever-specific values can override this if explicitly set
3. This allows for:
   - Consistent argument handling across retrievers
   - Flexibility when needed for specific retrievers

## Current Specialist Types

Currently, the main specialist type is the RAG (Retrieval-Augmented Generation) Specialist, focused on question-answering using library content. Additional specialist types are being developed for:

- Sales support
- Template filling
- Specialized customer support
- Document analysis
- And more...

Detailed documentation for each specialist type is available in their respective sections.
</file>

<file path="docs/introduction.md">
---
id: introduction
title: Introduction to Ask Eve AI
description: Learn about Evie, a cutting-edge AI solution for transforming how businesses interact with information
sidebar_label: Introduction
sidebar_position: 1
slug: /
keywords:
  - introduction
  - AI assistant
  - knowledge base
  - Evie
---

# Introduction to Ask Eve AI

Welcome to the world of Ask Eve AI, affectionately known as **Evie**—a cutting-edge AI solution 
designed to revolutionize how businesses interact with information. Whether enhancing customer 
experiences, boosting internal efficiency, or empowering specialized teams, Evie is here to unlock 
the full potential of your organization’s knowledge.

## What is Evie?

Evie is an AI assistant tailored to your unique business needs. By leveraging advanced AI 
techniques, she transforms complex information into natural, engaging dialogues. Unlike generic 
chatbots, Evie is deeply integrated into your specific knowledge base, offering precise, 
traceable, and contextual responses.

Here’s how Evie stands out:
- **Custom Knowledge Integration**: Evie learns from your documents, intranet, website, and other sources, providing responses grounded in your organization’s information.
- **Conversational AI**: Interact with Evie just like you would with a colleague. She understands context, remembers past interactions, and responds naturally.
- **Agentic Behaviour**: Evie goes beyond just conversations. She can perform smart actions based on your information, or based on the conversation.
- **Multilingual Capabilities**: Evie breaks language barriers, understanding and responding in multiple languages based on your business requirements.

## Key Features and Benefits

### Enhanced Customer Experience
Evie transforms customer interactions by providing 24/7 conversational support. She engages visitors on your website, guiding them to relevant information with ease and efficiency. This improves user satisfaction and helps establish your brand’s reputation as forward-thinking and customer-centric.

### Boosted Internal Productivity
Internally, Evie acts as a conversational hub for your organization. Employees can quickly find policies, data, and other resources using simple language, reducing time spent searching for information and improving productivity.

### Expertise On Demand
Evie serves as an always-on expert assistant, making specialized knowledge instantly accessible across your organization. This democratizes access to expertise and allows your human experts to focus on high-value tasks.

## Why Choose Evie?

Evie is more than a chatbot; she’s an intelligent information assistant designed to adapt to your needs:
- **Transparency**: Evie provides citations for her answers, enabling users to verify information at its source.
- **Customization**: From integration with specific platforms to tailoring conversational styles, Evie is built to align with your unique environment.
- **Continuous Improvement**: Evie evolves with your business, adapting to new information and changing requirements effortlessly.

## How Does Evie Work?

At the heart of Evie is a system based on Retrieval-Augmented Generation (RAG). Think of Evie as a hyper-intelligent librarian, and a very talented assistant.
As a librarian, Evie has two essential talents:

1. **Efficient Knowledge Storage**: Evie stores the information you offer her (html, pdfs, audio, ...) intelligently in the library. She stores the information semantically, i.e. Evie understands the content you offer her, and indexes your information as such.
2. **Efficient Knowledge Retrieval**: Once stored, Evie has the ability to semantically retrieve relevant information from the library for a given question, task, ...

Using this library, Evie assists you in various daily activity - to answer questions or execute tasks.

1. **Knowledge Retrieval**: When asked a question or given a task, Evie searches your knowledge base for the most relevant information.
2. **Contextual Responses**: Using advanced AI, she generates accurate, contextual answers while citing her sources.
3. **Real-Time Updates**: As you add new information, Evie incorporates it seamlessly into her responses.

## Ready to Transform Information Access?

Whether you aim to:
- Turn your website into an interactive knowledge hub,
- Optimize your intranet for streamlined internal processes,
- Empower your teams with instant access to expertise, or
- Have tasks you want to automate

Evie is the intelligent, adaptable solution you’ve been looking for.


---
</file>

<file path=".gitignore">
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
</file>

<file path=".repopackignore">
# Add patterns to ignore here, one per line
# Example:
# *.log
# tmp/
blog/
build/
node_modules/
src/
</file>

<file path="docusaurus.config.js">
// @ts-check
// `@type` JSDoc annotations allow editor autocompletion and type checking
// (when paired with `@ts-check`).
// There are various equivalent ways to declare your Docusaurus config.
// See: https://docusaurus.io/docs/api/docusaurus-config

import {themes as prismThemes} from 'prism-react-renderer';

// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Ask Eve AI Documentation',
  tagline: 'Evie is the best',
  favicon: 'img/favicon.ico',

  // Set the production url of your site here
  url: 'https://askeveai.com',
  // Set the /<baseUrl>/ pathname under which your site is served
  // For GitHub pages deployment, it is often '/<projectName>/'
  baseUrl: '/docs',

  // GitHub pages deployment config.
  // If you aren't using GitHub pages, you don't need these.
  // organizationName: 'facebook', // Usually your GitHub org/user name.
  // projectName: 'docusaurus', // Usually your repo name.
  //
  // onBrokenLinks: 'throw',
  // onBrokenMarkdownLinks: 'warn',

  // Even if you don't use internationalization, you can use this field to set
  // useful metadata like html lang. For example, if your site is Chinese, you
  // may want to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  markdown: {
    mermaid: true, // Enable Mermaid support in Markdown
  },

  themes: ['@docusaurus/theme-mermaid'], // Add the Mermaid theme (diagrams)

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: './sidebars.js',
          routeBasePath: '/',
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          // editUrl:
          //   'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        blog: false,
        pages: false,
        theme: {
          customCss: './src/css/custom.css',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // Replace with your project's social card
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'Ask Eve AI',
        logo: {
          alt: 'Ask Eve AI',
          src: 'img/logo.png',
        },
        items: [
          {
            type: 'doc',
            docId: 'introduction',
            position: 'left',
            label: 'Documentation',
          },
        ],
      },
      footer: {
        style: 'dark',
        // links: [
        //   {
        //     title: 'Docs',
        //     items: [
        //       {
        //         label: 'Tutorial',
        //         to: '/docs/intro',
        //       },
        //     ],
        //   },
        //   {
        //     title: 'Community',
        //     items: [
        //       {
        //         label: 'Stack Overflow',
        //         href: 'https://stackoverflow.com/questions/tagged/docusaurus',
        //       },
        //       {
        //         label: 'Discord',
        //         href: 'https://discordapp.com/invite/docusaurus',
        //       },
        //       {
        //         label: 'X',
        //         href: 'https://x.com/docusaurus',
        //       },
        //     ],
        //   },
        //   {
        //     title: 'More',
        //     items: [
        //       {
        //         label: 'Blog',
        //         to: '/blog',
        //       },
        //       {
        //         label: 'GitHub',
        //         href: 'https://github.com/facebook/docusaurus',
        //       },
        //     ],
        //   },
        // ],
        copyright: `Copyright © ${new Date().getFullYear()} Ask Eve AI. Built with Docusaurus.`,
      },
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
      },
      mermaid: {
        theme: {}, // Mermaid theme configuration, optional
      },
    }),
};

export default config;
</file>

<file path="package.json">
{
  "name": "eveai-docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
  "dependencies": {
    "@docusaurus/core": "^3.6.3",
    "@docusaurus/preset-classic": "^3.6.3",
    "@docusaurus/theme-mermaid": "^3.6.3",
    "@mdx-js/react": "^3.0.0",
    "clsx": "^2.0.0",
    "prism-react-renderer": "^2.3.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "3.6.2",
    "@docusaurus/types": "3.6.2"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 3 chrome version",
      "last 3 firefox version",
      "last 5 safari version"
    ]
  },
  "engines": {
    "node": ">=18.0"
  }
}
</file>

<file path="README.md">
# Website

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

Using SSH:

```
$ USE_SSH=true yarn deploy
```

Not using SSH:

```
$ GIT_USER=<Your GitHub username> yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
</file>

<file path="repopack.config.json">
{
  "output": {
    "filePath": "eveai_docs_repo.txt",
    "style": "xml",
    "removeComments": false,
    "removeEmptyLines": false,
    "topFilesLength": 5,
    "showLineNumbers": false
  },
  "include": [],
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    "customPatterns": []
  },
  "security": {
    "enableSecurityCheck": true
  }
}
</file>

<file path="sidebars.js">
// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  libraryDocs: [
    {
      type: 'autogenerated',
      dirName: '.', // Generate from the docs directory
    },
  ],
};

module.exports = sidebars;
</file>

</repository_files>
