Add ability to attach documents to a chat session in all UIs (#327)

Author: MikeAlhayek

.copilot/instructions.md

@@ -0,0 +1,46 @@
+# GLOBAL COPILOT CLI RULES (MANDATORY)
+
+## SOURCE CONTROL RULES
+- NEVER run git commit
+- NEVER run git push
+- NEVER amend commits
+- NEVER stage files unless explicitly instructed
+- ALL changes must remain local and uncommitted
+- Assume the user will manually review and commit
+
+## CODE CHANGE RULES
+- You MAY modify files locally
+- You MUST clearly describe all changes made
+- You MUST assume the user will review diffs before committing
+- If unsure, prefer minimal and incremental changes
+
+## DOCUMENTATION ENFORCEMENT (REQUIRED)
+Whenever code is modified:
+
+1. You MUST evaluate the documentation project located at:
+   src\CrestApps.OrchardCore.Documentations
+
+2. You MUST update documentation to reflect the changes:
+   - Update the relevant **feature documentation first**
+   - Ensure accuracy with the latest behavior
+   - Use concise, developer-facing language
+
+3. After feature docs are updated:
+   - Add an entry to the **changelog** in the same documentation project
+   - Clearly describe:
+     - What changed
+     - Why it changed
+     - Any breaking or behavioral impact
+
+4. Documentation changes are NOT optional
+   - Code changes without documentation updates are considered incomplete
+
+## QUALITY EXPECTATIONS
+- Prefer clarity over cleverness
+- Follow existing project conventions
+- Do not introduce undocumented behavior
+- Keep documentation and code in sync at all times
+
+## ASSUMPTIONS
+- The user evaluates all changes before committing
+- The user controls all source control actions

src/Abstractions/CrestApps.OrchardCore.AI.Abstractions/Models/AIChatSession.cs

@@ -41,6 +41,12 @@ public sealed class AIChatSession : Entity
     /// </summary>
     public string ClientId { get; set; }
 
+    /// <summary>
+    /// Gets or sets the collection of document references attached to this session.
+    /// Documents are uploaded by users and used for RAG (Retrieval-Augmented Generation).
+    /// </summary>
+    public IList<ChatInteractionDocumentInfo> Documents { get; set; } = [];
+
     /// <summary>
     /// Gets or sets the UTC date and time when the session was first created.
     /// This property helps track the start time of the session in a standardized format (UTC).

src/Core/CrestApps.OrchardCore.AI.Core/AIConstants.cs

@@ -12,6 +12,8 @@ public static class AIConstants
 
     public const string DefaultBlankMessage = "AI drew blank and no message was generated!";
 
+    public const string DefaultBlankSessionTitle = "Untitled";
+
     public const string CollectionName = "AI";
 
     public const string ConnectionProtectorName = "AIProviderConnection";
@@ -50,6 +52,8 @@ public static class Feature
         public const string ProfileDocuments = "CrestApps.OrchardCore.AI.Documents.Profiles";
 
         public const string ChatAdminWidget = "CrestApps.OrchardCore.AI.Chat.AdminWidget";
+
+        public const string ChatSessionDocuments = "CrestApps.OrchardCore.AI.Documents.ChatSessions";
     }
 
     public static readonly string AIDocumentsIndexingTaskType = "AIDocuments";
@@ -59,6 +63,8 @@ public static class DocumentReferenceTypes
         public const string Profile = "profile";
 
         public const string ChatInteraction = "chat-interaction";
+
+        public const string ChatSession = "chat-session";
     }
 
     public static class ColumnNames
@@ -95,5 +101,9 @@ public static class RouteNames
         public const string ChatInteractionUploadDocument = "ChatInteractionUploadDocument";
 
         public const string ChatInteractionRemoveDocument = "ChatInteractionRemoveDocument";
+
+        public const string ChatSessionUploadDocument = "ChatSessionUploadDocument";
+
+        public const string ChatSessionRemoveDocument = "ChatSessionRemoveDocument";
     }
 }

src/Core/CrestApps.OrchardCore.AI.Core/Handlers/DocumentOrchestrationHandler.cs

@@ -48,6 +48,19 @@ public Task BuildingAsync(OrchestrationContextBuildingContext context)
 
     public Task BuiltAsync(OrchestrationContextBuiltContext context)
     {
+        // Check for session documents after configure has run,
+        // since the session is set via the configure callback
+        // which executes between BuildingAsync and BuiltAsync.
+        if (context.Context.Documents is not { Count: > 0 } &&
+            context.Resource is AIProfile &&
+            context.Context.CompletionContext?.AdditionalProperties is not null &&
+            context.Context.CompletionContext.AdditionalProperties.TryGetValue("Session", out var sessionObj) &&
+            sessionObj is AIChatSession session &&
+            session.Documents is { Count: > 0 })
+        {
+            context.Context.Documents = session.Documents;
+        }
+
         if (context.Context.Documents is not { Count: > 0 } ||
             context.Context.CompletionContext is null)
         {

src/Core/CrestApps.OrchardCore.AI.Core/Models/AIProfileSessionDocumentsMetadata.cs

@@ -0,0 +1,14 @@
+namespace CrestApps.OrchardCore.AI.Models;
+
+/// <summary>
+/// Metadata stored on <see cref="AIProfile.Properties"/> to control
+/// whether users can upload documents within AI Chat Sessions.
+/// </summary>
+public sealed class AIProfileSessionDocumentsMetadata
+{
+    /// <summary>
+    /// Gets or sets whether users are allowed to upload and attach documents
+    /// to chat sessions that use this profile.
+    /// </summary>
+    public bool AllowSessionDocuments { get; set; }
+}

src/CrestApps.OrchardCore.Documentations/docs/ai/documents/index.md

@@ -2,7 +2,7 @@
 sidebar_label: Overview
 sidebar_position: 1
 title: AI Documents
-description: Document upload, text extraction, embedding, and RAG capabilities for AI Chat Interactions and AI Profiles.
+description: Document upload, text extraction, embedding, and RAG capabilities for AI Chat Interactions, AI Profiles, and AI Chat Sessions.
 ---
 
 | | |
@@ -34,6 +34,7 @@ The base feature (`CrestApps.OrchardCore.AI.Documents`) provides the shared infr
 |---------|-----|-------------|
 | **AI Documents for Chat Interactions** | `CrestApps.OrchardCore.AI.Documents.ChatInteractions` | Provides document upload and Retrieval-Augmented Generation (RAG) support for AI Chat Interactions. |
 | **AI Documents for Profiles** | `CrestApps.OrchardCore.AI.Documents.Profiles` | Provides document upload and Retrieval-Augmented Generation (RAG) support for AI Profiles. |
+| **AI Documents for Chat Sessions** | `CrestApps.OrchardCore.AI.Documents.ChatSessions` | Provides document upload and RAG support for AI Chat Sessions and AI Chat Widgets. |
 
 ## AI Documents for Chat Interactions
 
@@ -70,13 +71,6 @@ The orchestrator supports various document-related operations:
 - **Content Transformation** — Provides content for reformatting or conversion
 - **General Reference** — Provides context when asking general questions that reference documents
 
-### API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/ai/chat-interactions/upload-document` | POST | Upload one or more documents to a chat interaction |
-| `/ai/chat-interactions/remove-document` | POST | Remove a document from a chat interaction |
-
 ### Getting Started
 
 1. **Set up an indexing provider**: Enable Elasticsearch or Azure AI Search in the Orchard Core admin.
@@ -142,6 +136,56 @@ There are no separate API endpoints for profile document management — everythi
 3. Use the **Documents** tab to upload text-based documents.
 4. Configure the **Top N Results** setting to control how many matching chunks are included as context.
 
+## AI Documents for Chat Sessions
+
+| | |
+| --- | --- |
+| **Feature Name** | AI Documents for Chat Sessions |
+| **Feature ID** | `CrestApps.OrchardCore.AI.Documents.ChatSessions` |
+
+Provides document upload and Retrieval-Augmented Generation (RAG) support directly within AI Chat Sessions and AI Chat Widgets (both admin and frontend).
+
+When enabled, users can attach documents to any chat session via drag-and-drop or file browser. Documents are indexed using the same shared infrastructure (text extraction, chunking, embedding, and vector search) used by Chat Interactions and Profiles.
+
+Unlike profile documents (which persist across all sessions), chat session documents are **scoped to the individual session** — similar to chat interaction documents.
+
+### Key Capabilities
+
+- **Document Upload**: Drag-and-drop or browse to attach files directly in the chat input area
+- **Visual Attach Button**: A persistent "Attach files" button appears above the chat input when enabled
+- **Document Pills**: Attached documents are shown as compact pill badges with remove (X) buttons
+- **Drag-and-Drop Highlight**: The input area highlights when files are dragged over it
+- **Text Extraction & Embedding**: Uploaded documents are automatically extracted, chunked, and embedded for vector search
+- **RAG Integration**: Relevant chunks are retrieved and used as context for AI responses
+- **Per-Profile Opt-In**: Each AI Profile has an **Allow Documents & Attachments** checkbox (unchecked by default) to control whether document upload is available
+
+### Per-Profile Opt-In
+
+Because document processing is resource-intensive, document upload is **not enabled by default** even when the feature is active. Administrators must explicitly opt in for each AI Profile:
+
+1. Navigate to **Artificial Intelligence > AI Profiles** and edit a profile.
+2. In the **Documents** section, check **Allow Documents & Attachments**.
+3. Save the profile.
+
+For **AI Chat Widget** content items, the same checkbox appears on the widget editor under the AI profile part settings.
+
+### Supported UIs
+
+| UI | Where | Notes |
+|----|-------|-------|
+| **AI Chat Session** | Admin > Artificial Intelligence > AI Chat | Full session page |
+| **AI Chat Admin Widget** | Floating admin widget | Compact chat widget on admin pages |
+| **AI Chat Widget** | Frontend content widget | Public-facing chat widget |
+
+### Getting Started
+
+1. **Set up an indexing provider**: Enable Elasticsearch or Azure AI Search in the Orchard Core admin.
+2. **Create an index**: Navigate to **Search > Indexing** and create a new index (e.g., "ChatDocuments").
+3. **Configure settings**: Navigate to **Settings > Chat Interaction** and select your new index.
+4. **Enable the feature**: Enable `AI Documents for Chat Sessions` in the admin dashboard.
+5. **Opt in per profile**: Edit the desired AI Profile and check **Allow Documents & Attachments**.
+6. Open a chat session — the attach button and drag-and-drop zone are now available.
+
 ## Supported Document Formats
 
 | Format | Extension | Notes |

src/Modules/CrestApps.OrchardCore.AI.Chat/Assets/css/ai-chat-widget.css

@@ -390,3 +390,16 @@
         max-height: calc(100vh - 5rem);
     }
 }
+
+/* Document attachment bar */
+.ai-admin-widget .ai-chat-doc-bar {
+    border-bottom: 1px solid var(--bs-border-color, #dee2e6);
+    font-size: 0.8rem;
+}
+
+/* Drag-over highlight for the widget input area */
+.ai-admin-widget-input.ai-chat-drag-over {
+    outline: 2px dashed var(--ai-widget-primary, #41b670) !important;
+    outline-offset: -2px;
+    background-color: rgba(65, 182, 112, 0.05) !important;
+}

src/Modules/CrestApps.OrchardCore.AI.Chat/Assets/css/ai-chat.css

@@ -92,3 +92,15 @@
 .ai-chat-messages pre code.hljs {
     border-radius: 0.375rem;
 }
+
+/* Document attachment bar */
+.ai-chat-doc-bar {
+    border-bottom: 1px solid var(--bs-border-color, #dee2e6);
+}
+
+/* Drag-over highlight for the input area */
+.ai-chat-drag-over {
+    outline: 2px dashed var(--bs-primary, #0d6efd) !important;
+    outline-offset: -2px;
+    background-color: rgba(13, 110, 253, 0.05) !important;
+}