Orchardcore AI Documents

Orchard Core AI Documents - Prompt Templates

Configure AI Documents

You are an Orchard Core expert. Generate code, configuration, and recipes for adding document processing, storage, indexing, and Retrieval-Augmented Generation (RAG) capabilities to an Orchard Core application using CrestApps AI Documents modules.

Guidelines

• The AI Documents modules provide document upload, text extraction, chunking, vector indexing, and RAG search for AI conversations.
• The base feature CrestApps.OrchardCore.AI.Documents is EnabledByDependencyOnly and is activated automatically when you enable one of the higher-level features.
• Embeddable documents follow the pipeline Upload → Extract Text → Chunk → Embed → Index → Vector Search.
• Tabular documents (.csv and .xlsx) use a tabular workspace and tabular tools instead of embedding and vector indexing.
• An embedding deployment (e.g., text-embedding-3-small) is required only for the embeddable document indexing path.
• Each indexing backend (Azure AI Search or Elasticsearch) registers a keyed IVectorSearchService implementation.
• Install all CrestApps NuGet packages in the web/startup project.
• Always secure connection strings and API keys using user secrets or environment variables.

Feature IDs

NuGet Packages

Enabling AI Documents for Chat Interactions with Azure AI Search

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat.Interactions",
        "CrestApps.OrchardCore.AI.Documents.ChatInteractions",
        "CrestApps.OrchardCore.AI.Documents.AzureAI",
        "CrestApps.OrchardCore.AI.Documents.Pdf",
        "CrestApps.OrchardCore.AI.Documents.OpenXml",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Enabling AI Documents for Chat Interactions with Elasticsearch

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat.Interactions",
        "CrestApps.OrchardCore.AI.Documents.ChatInteractions",
        "CrestApps.OrchardCore.AI.Documents.Elasticsearch",
        "CrestApps.OrchardCore.AI.Documents.Pdf",
        "CrestApps.OrchardCore.AI.Documents.OpenXml",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Enabling AI Documents for Profiles

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Documents.Profiles",
        "CrestApps.OrchardCore.AI.Documents.AzureAI",
        "CrestApps.OrchardCore.AI.Documents.Pdf",
        "CrestApps.OrchardCore.AI.Documents.OpenXml",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Enabling AI Documents for Chat Sessions

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Documents.ChatSessions",
        "CrestApps.OrchardCore.AI.Documents.AzureAI",
        "CrestApps.OrchardCore.AI.Documents.Pdf",
        "CrestApps.OrchardCore.AI.Documents.OpenXml",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Document Upload Flow

The document processing pipeline follows these steps:

1. Upload - User uploads a file via the chat interaction, profile, or chat session UI. The file is saved using IDocumentFileStore (file system by default, or Azure Blob if configured).
2. Extract Text - The document processor extracts plain text. PDF and OpenXml formats require their respective feature modules.
3. Chunk - Extracted text is split into smaller chunks stored via IAIDocumentChunkStore.
4. Embed and Index - For embeddable documents, chunks are sent to the configured embedding deployment and written to the configured search backend.
5. Search - For indexed documents, a vector similarity search retrieves relevant chunks to augment the AI response (RAG).

CSV and Excel are tabular, non-embeddable inputs. They are loaded into the per-conversation tabular workspace and handled with tabular tools rather than through RAG indexing.

Supported Document Formats

Legacy Office formats (.doc, .xls, .ppt) are not supported. Convert them to their modern equivalents first.

Storage Backends

File System (Default)

By default, uploaded documents are stored on the local file system under {WebRootPath}/{TenantName}/AIDocuments. No additional configuration is required.

Azure Blob Storage

Enable the CrestApps.OrchardCore.AI.Documents.Azure feature and configure appsettings.json:

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "AzureDocuments": {
          "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net",
          "ContainerName": "ai-documents",
          "CreateContainer": true
        }
      }
    }
  }
}

The Azure module replaces IDocumentFileStore with a BlobFileStore-backed implementation. The AIDocumentBlobContainerTenantEvents handler manages container lifecycle for multi-tenant setups.

Indexing Backends

Azure AI Search

Enable CrestApps.OrchardCore.AI.Documents.AzureAI. This registers:

• AIDocumentAzureAISearchDocumentIndexHandler as an IDocumentIndexHandler
• AzureAISearchVectorSearchService as a keyed IVectorSearchService
• An indexing source named AI Documents (Azure AI Search) under Search → Indexing

Elasticsearch

Enable CrestApps.OrchardCore.AI.Documents.Elasticsearch. This registers:

• AIDocumentElasticsearchDocumentIndexHandler as an IDocumentIndexHandler
• ElasticsearchVectorSearchService as a keyed IVectorSearchService
• An indexing source named AI Documents (Elasticsearch) under Search → Indexing

Setting Up Document Indexing

1. Enable one of the indexing backend features (CrestApps.OrchardCore.AI.Documents.AzureAI or CrestApps.OrchardCore.AI.Documents.Elasticsearch).
2. Navigate to Search → Indexing in the admin and create a new index selecting the "AI Documents" source.
3. Configure an embedding deployment (see below).
4. Enable the desired document context feature (ChatInteractions, Profiles, or ChatSessions).

Configuring the Embedding Model

Document indexing requires an embedding deployment. Create one via admin UI or define it in appsettings.json:

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "Deployments": [
          {
            "Name": "text-embedding-3-small",
            "ClientName": "OpenAI",
            "ConnectionName": "default",
            "Purpose": "Embedding"
          }
        ]
      }
    }
  }
}

Integration with Chat Sessions, Profiles, and Interactions

Chat Interactions

The CrestApps.OrchardCore.AI.Documents.ChatInteractions feature adds document upload endpoints and display drivers to the Chat Interactions UI. Users can upload documents directly in an ad-hoc chat session, and the system indexes them for RAG queries.

• Upload endpoint registered via AddUploadChatInteractionDocumentEndpoint
• Remove endpoint registered via AddRemoveChatInteractionDocumentEndpoint
• Display driver ChatInteractionDocumentsDisplayDriver renders the upload UI

Profiles

The CrestApps.OrchardCore.AI.Documents.Profiles feature lets administrators attach documents to AI Profiles and Profile Templates. Documents uploaded at the profile level are available to all chat sessions that use that profile.

• AIProfileDocumentsDisplayDriver adds a documents tab to the profile editor
• AIProfileTemplateDocumentsDisplayDriver adds a documents tab to profile templates

Chat Sessions

The CrestApps.OrchardCore.AI.Documents.ChatSessions feature adds per-session document upload for AI Chat Sessions and Widgets. When a chat session is deleted, the AIChatSessionDocumentCleanupHandler automatically removes associated documents.

• Upload endpoint registered via AddUploadChatSessionDocumentEndpoint
• Remove endpoint registered via AddRemoveChatSessionDocumentEndpoint
• AIProfileSessionDocumentsDisplayDriver adds documents to session configuration

Key Services

Custom Document Event Handler

Implement IAIChatDocumentEventHandler to react to document lifecycle events:

public sealed class MyDocumentEventHandler : IAIChatDocumentEventHandler
{
    public Task UploadedAsync(
        AIChatDocumentUploadContext context,
        CancellationToken cancellationToken = default)
    {
        // Runs after a document is uploaded and processed.
        return Task.CompletedTask;
    }

    public Task RemovedAsync(
        AIChatDocumentRemoveContext context,
        CancellationToken cancellationToken = default)
    {
        // Runs after a document is removed.
        return Task.CompletedTask;
    }
}

Register the handler in your module startup:

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<IAIChatDocumentEventHandler, MyDocumentEventHandler>();
    }
}

Security

Document upload and removal endpoints are protected by authorization handlers:

• OrchardChatInteractionDocumentAuthorizationHandler controls access for chat interaction documents.
• OrchardAIChatSessionDocumentAuthorizationHandler controls access for chat session documents.

These handlers are registered automatically when the base AI Documents feature is enabled.