SteadyGo.Umbraco.AI.Toolkit
1.0.2
See the version list below for details.
dotnet add package SteadyGo.Umbraco.AI.Toolkit --version 1.0.2
NuGet\Install-Package SteadyGo.Umbraco.AI.Toolkit -Version 1.0.2
<PackageReference Include="SteadyGo.Umbraco.AI.Toolkit" Version="1.0.2" />
<PackageVersion Include="SteadyGo.Umbraco.AI.Toolkit" Version="1.0.2" />
<PackageReference Include="SteadyGo.Umbraco.AI.Toolkit" />
paket add SteadyGo.Umbraco.AI.Toolkit --version 1.0.2
#r "nuget: SteadyGo.Umbraco.AI.Toolkit, 1.0.2"
#:package SteadyGo.Umbraco.AI.Toolkit@1.0.2
#addin nuget:?package=SteadyGo.Umbraco.AI.Toolkit&version=1.0.2
#tool nuget:?package=SteadyGo.Umbraco.AI.Toolkit&version=1.0.2
Umbraco AI Search, Chat & Enquiries
SteadyGo.Umbraco.AI.Toolkit is an installable package for Umbraco 17.6.2 and later 17.x releases, providing AI-powered search, chat, enquiry capture and external content indexing. Indexing, grounded answers, chat orchestration, enquiry routing, conversation storage and SMTP delivery run inside the Umbraco application. A separate AI API App Service is not required. The package installs SteadyGo.Umbraco.AI.Toolkit.Engine automatically as a dependency.
Each installation needs configured Azure AI Search, an Azure OpenAI deployment and storage. SMTP is needed for real email delivery. The Toolkit contains no customer branding, default contacts, recipient addresses or credentials.
Licence
The Toolkit is offered as a single Search and Chat tier. It includes AI Search, suggested questions, paged results, publishing/indexing, unpublish removal, AI Chat, guidance rules, enquiry submission and transcript delivery.
Licences are enforced on server endpoints and indexing. When no paid or local development licence is active, enabling the Toolkit for the first time starts a full-featured 14-day trial. Its start time and generated trial ID are stored in the Umbraco database; disabling the Toolkit does not pause or reset the period. The trial is local evaluation state, not a signed token, and clearing the Toolkit database settings during uninstall clears it too. After the trial, a paid licence is required. Commercial licences are signed offline tokens, so normal installations do not need a licence server or a localhost callback. The public IAiLicenceService interface remains available for providers that need a different validation policy.
Install
Once published to NuGet, install the package in an Umbraco 17.6.2 or later 17.x site:
dotnet add .\YourSite.csproj package SteadyGo.Umbraco.AI.Toolkit --version 1.0.2
For a local build, pack both projects into the same feed and install from that feed:
dotnet pack .\src\Umbraco.AI.Toolkit.Engine\Umbraco.AI.Toolkit.Engine.csproj -c Release -o .\artifacts
dotnet pack .\src\Umbraco.AI.Toolkit\Umbraco.AI.Toolkit.csproj -c Release -o .\artifacts
dotnet add .\YourSite.csproj package SteadyGo.Umbraco.AI.Toolkit --version 1.0.2 --source .\artifacts
Run the Umbraco 17 site. Complete Umbraco installation if necessary, then restart once. Configure the infrastructure through hosting configuration. A paid licence key is optional during the 14-day trial; enable the Toolkit in AI on Site to start it.
Settings
The Toolkit stores its feature switches, search settings, widget wording, guidance rules and document-type selections in its own Umbraco database record. It does not install Toolkit document types or content nodes. Website pages and their document types remain under the site's control.
The AI Toolkit section contains App Settings (read-only server configuration and licence status), AI on Site (feature switches and default culture), AI Search Test, AI Chat Test, DocType Config, Guidance Rules, UI Labelling, Email Queue, Use on Website and Uninstall. Save editable settings before testing them. AI Search Test includes editable search settings; AI Chat Test and App Settings do not have a Save button.
Use DocType Config to select which published document types are indexed. The selected aliases live in Toolkit database settings. Publication visibility and the Toolkit's page-level exclusion rules still apply.
Configure the included engine
- For a paid installation, set the signed Toolkit licence key in hosting configuration (
UmbracoAi:Licence:Key). For evaluation, leave it blank and enable the Toolkit to start the 14-day trial. - Set Azure OpenAI endpoint, deployment name and key in hosting configuration.
- Set Azure AI Search endpoint, admin key and a dedicated index name (default:
umbraco-ai) in hosting configuration. - Set Azure Storage connection string and LLM container (default:
umbraco-ai-llm) in hosting configuration. - In AI on Site, enable the Toolkit, AI Search and publish indexing. Enable Chat where licensed.
- For email delivery, configure SMTP in hosting configuration and permitted enquiry destinations in the Toolkit settings.
A dedicated index is created if missing. An existing index may receive the Toolkit scoring profile, but required fields are not added automatically; an incompatible schema will reject uploads. Use a new Toolkit index with its block metadata fields.
Indexing needs Search credentials. Answers also need the model deployment. Chat needs Azure Table storage. Search uses full-text retrieval followed by model-generated answers; this version does not generate vector embeddings. Search pagination operates on the best 1,000 retrieved chunks.
The shared storage connection supplies LLM blobs and chat tables. Without it, LLM files are saved locally, while embedded Chat remains unavailable until conversation storage is configured. Table names default to UmbracoAiConversations and UmbracoAiEnquiries.
Guidance rules and enquiry routing
Open AI Toolkit → Guidance Rules and create a rule for each subject or routing policy:
| Tab | Purpose |
|---|---|
| Matching | Subject description, matching and excluded keywords/phrases, and priority; higher priority wins among matching keyword rules |
| Guidance | Instructions for answering that subject |
| Enquiries | Recipient addresses, prohibit-enquiry switch, required telephone/summary and confirmation wording |
Add approved guidance page links beneath a rule in the Guidance Rules tab when specific pages should be offered for that subject. The links are validated and are only selected for relevant page/link requests; ordinary answers remain grounded in the normal website search flow.
Add Required Information entries beneath a rule for extra questions, validation and required/optional fields.
Use Default enquiry email on the Email Queue panel for permitted general enquiries without a subject-specific destination. Rule restrictions and the master Allow enquiries switch still apply. Browser requests cannot choose recipients, replace guidance or manufacture stored conversation history. Submission rechecks current saved routing and requires the completed confirmation flow. Email and transcript delivery use durable claims to prevent duplicate sends on retries.
Test from the backoffice
Open AI Search Test or AI Chat Test and select Refresh tester after saving the relevant editable settings. The testers use saved settings, licence checks and the same local endpoints as the frontend. Missing engine settings are shown before starting. Configured resources must be reachable, and search needs indexed content.
Chat stays open inside its tab. Each test uses separate in-memory browser state; refreshing starts a new test without changing the website session. Conversations still use server storage and the configured retention policy. Culture can be overridden for a test.
Backoffice enquiry/transcript tests are always stored as labelled preview emails in the Toolkit queue and are never sent to a real recipient. Genuine website submissions are sent through the Toolkit SMTP settings when configured; otherwise they remain in the durable queue and are sent automatically when SMTP becomes available. Search/chat requests themselves use the configured AI services. No page templates or frontend markup are needed for these testers.
Block rendering and LLM page files
The Toolkit creates one LLM text document per eligible published page and culture. It reads published content, respects licensing/indexing switches and exclusions, and omits configuration nodes.
For each Block List item in editor order:
- Render
xyz.llm.cshtmlif present. - Otherwise render
xyz.cshtmlif available. - If neither exists, extract readable content fields directly from the database.
- Clean HTML, script/style/template bodies, comments and attributes.
- Surround the readable text with block-name and element-key comments.
## About our service
Readable text from the mirror, regular component or content fields.
Headings, paragraphs, lists and inline linked words are preserved. Images, image alt text, buttons, navigation and link destinations are omitted. An intentionally empty mirror stays empty; a broken mirror logs a rendering error rather than silently falling back. Pages are not truncated mid-block.
Mirrors use the regular BlockListItem model and require no isLLM branch. The Toolkit recursively discovers .llm.cshtml and regular .cshtml block views anywhere under /Views, preferring the .llm.cshtml mirror. Compiled Razor views are supported. Replace IAiLlmBlockRenderer for custom models or components.
Excluded properties are honoured in nested field/JSON extraction. A block with an excluded property uses field extraction instead of rendering Razor. Nested lists receive their own boundaries unless a parent view renders them. Fallback extraction keeps authored prose and numeric facts while omitting editor flags, styling and picker metadata. Text is stored without CMS property labels; the page URL remains separate search metadata. Content generated only by site code needs a mirror view or custom renderer.
Starting with only a database
A running Umbraco host connected to the restored database can generate LLM files and populate the configured index without the original page/block views. Missing-view fallback extracts published fields and nested Block Lists. Rich-text source is read without invoking site Razor converters, including embedded RTE block data, so a missing rich-text component view does not prevent the page export.
Configure the engine and licence, enable the Toolkit, Search and indexing in AI on Site, save settings and publish the content tree. Alternatively, run the rebuild service for already published content. Saving settings alone clears caches; it does not trigger a full rebuild.
Text supplied only by Razor code, custom converters or external services cannot be reconstructed from the database alone. Search links may point to pages that cannot render until their frontend exists.
External source webhooks
External systems can add, update and remove records from the same AI Search index. Post a source-agnostic
ExternalIndexDocument to /api/umbraco-ai/index/external-document. It accepts human-readable Content plus arbitrary
structured Fields; the Source and ExternalId form the stable identity. Posting the same record again replaces its
existing chunks, making webhook retries and updates idempotent.
To remove records, post one or more ExternalIndexDocumentReference objects in an ExternalRemoveDocumentsRequest to
/api/umbraco-ai/index/external-remove. The original Umbraco-style endpoints /api/umbraco-ai/index/document and
/api/umbraco-ai/index/remove remain available for compatibility.
Enable the webhook surface only in server configuration and keep its key out of Umbraco content:
{
"UmbracoAi": {
"ExternalIndexing": {
"Enabled": true,
"ApiKey": "<server secret>",
"MaximumDocumentsPerRequest": 100
}
}
}
Send the key in the X-Umbraco-AI-Index-Key header. Serve the endpoint over HTTPS in production; it uses the normal
Search licence and Azure AI Search configuration. The posted content should be the complete human-readable record;
the webhook caller should not pre-chunk it.
When the host exposes Umbraco's development Swagger UI, these operations are available at
/umbraco/swagger/index.html under Default API. The API-key header is described on both operations so Swagger's
Try it out can be used for a manual test. Swagger UI is host-provided; the Toolkit package supplies the endpoints
and their OpenAPI metadata but does not add Swagger to a production host.
Storage, chunking and indexing
The exact assembled page text is saved as UTF-8 before indexing. An indexing failure leaves the file available for inspection. Empty eligible pages also receive a file.
Files use {content-type-alias}/{node-name}.{culture}.llm.txt, for example homePage/Home.en.llm.txt, with invariant for nonvariant content. The published node name is separate from any marketing/search title. Unsafe filename characters are normalised. Duplicate names gain the page key as a suffix, so pages cannot overwrite each other. An internal .umbraco-ai folder maps page keys/cultures to filenames for renames and removals; Azure files also carry ownership metadata.
Rebuild replaces the file and removes its old name after a successful save. Old {page-key}/{culture}.llm.txt files are migrated per page/culture after the new file is stored. Unpublish/recycle removes corresponding files and index chunks; hidden/excluded content is removed rather than exported.
Azure containers are created with private access if missing. Without blob credentials, files are stored beneath umbraco/Data/UmbracoAi/llm. Configure LlmStorage:LocalDirectory or replace IAiLlmFileStorage for other storage. Local writes are atomic.
The included chunker consumes BEGIN/END comments and removes them from submitted search content. Oversized blocks are split within their boundaries, default 2,400 characters. Metadata retains block name/key/part, page/culture and tags. Nested extracted content is not duplicated in parents. Stable IDs distinguish repeated block names and cultures.
Page replacement uploads new chunks before deleting stale ones. Failed upload does not trigger stale-chunk deletion; Azure batches are not atomic transactions. Removal is scoped to the affected pages/cultures.
Startup rebuilding is disabled by default. Set RebuildLlmFilesOnStartup to true to traverse published pages in batches of 100 when indexing and licensing permit, or call IAiLlmRebuildService.RebuildAsync from an administrative job. Publish notifications continue to update individual pages.
Publication lifecycle
- A normal single-page publish refreshes that page in the published language(s), using published values rather than draft edits.
- Publish with descendants captures the exact branch and selected languages, waits for Umbraco's publish task to finish, then rebuilds every eligible published descendant, including unchanged pages. The Toolkit preserves Umbraco's include-unpublished selection; it never publishes content itself.
- Each page and every ancestor must be published in the relevant language. A descendant retaining its own published flag beneath an unpublished ancestor is removed from the files and index.
- Unpublishing a page removes its entire unreachable branch. Unpublishing one language removes that language throughout the branch and preserves other live languages.
- Republishing a parent through the backoffice restores descendants that become reachable again, while their own unpublished languages remain excluded.
- Recycling removes all affected descendant files and cultures. Hiding a page from search or excluding its content type removes that page without automatically hiding its children.
- Branch synchronization re-reads publication state before each page operation. Indexing and removal are serialized per page so an unpublish can take effect during a large rebuild.
The backoffice branch hook wraps IContentPublishingService; custom integrations that call lower-level IContentService.PublishBranch and receive empty notifications should explicitly run IAiLlmRebuildService.RebuildAsync.
Branch rebuilds are recorded as Umbraco long-running operations of type UmbracoAiIndexBranch. Logs include the selected root, publish/index task IDs and visited/indexed/removed/failed counts. The operation result contains Succeeded and detailed counts: completion alone does not imply every upload succeeded. A failed page does not stop later pages. Restarting during a rebuild interrupts it; repeat Publish with descendants (or run a rebuild) to retry.
Frontend components
<script type="module" src="/App_Plugins/UmbracoAiToolkit/ai-toolkit.js"></script>
<ai-search culture="en"></ai-search>
<ai-chat-widget culture="en"></ai-chat-widget>
Use <ai-chat-widget inline> for a panel within a page; the default retains a popup launcher. CSS variables include --uai-accent, --uai-surface and --uai-radius.
Public settings contain presentation/configuration readiness only. They do not expose keys, connection strings, recipients or guidance. Output is inserted as text, with HTTP/HTTPS source links.
Embedded endpoints
The Umbraco host provides:
GET /api/umbraco-ai/settingsPOST /api/umbraco-ai/search/askPOST /api/umbraco-ai/search/queryPOST /api/umbraco-ai/search/suggested-questionsPOST /api/umbraco-ai/chat/messagePOST /api/umbraco-ai/chat/submit-enquiryPOST /api/umbraco-ai/chat/send-transcript
Server input limits, conversation-ID validation, per-IP rate limits, feature switches and licence entitlements apply before execution. Indexing runs internally from Umbraco lifecycle services.
This release contains the reusable engine library and Umbraco endpoints, not a standalone API-host application. Azure Search and model endpoints require HTTPS. Commercial licence validation is performed locally from the signed offline token.
Development licence on the local installation
The package includes an optional local validator at POST /api/umbraco-ai/licence/validate. It is disabled by default, requires the ASP.NET Core Development environment and accepts only loopback requests. It is useful for local development when no signed licence is available; production installations should use a signed offline licence.
Configure UmbracoAi:DevelopmentLicence in the development host's server configuration:
{
"UmbracoAi": {
"DevelopmentLicence": {
"Enabled": true,
"ValidationEndpoint": "https://localhost:5000/api/umbraco-ai/licence/validate",
"KeySha256": "<64 hexadecimal characters: SHA-256 of your generated key>",
"Tier": "SearchAndChat",
"Customer": "Local development",
"ExpiresUtc": "<required future UTC expiry>"
}
}
}
For localhost Development operation, the CMS licence key is optional: the configured development tier and future expiry are sufficient. If a key is supplied, its SHA-256 hash must match the server configuration. No development key or hash is shipped in the package. Tier and expiry are controlled by server configuration; requests cannot select them. Wrong keys, missing/expired expiry, invalid tiers, and invalid hashes fail validation. This development-only route is separate from production licence issuance.
The endpoint returns the development licence-validation response. When the CMS endpoint exactly matches the configured loopback URL, the Toolkit uses the same validator in process, including during startup before HTTP is listening. Expiry is checked on every local validation. A restart is required after first enabling this server configuration.
Signed offline licences
The private issuer tool is kept separately from this public package repository. It creates an UAT1.<payload>.<signature> token using an RSA-PSS SHA-256 signature. The package contains only the matching public key and verifies the product, tier, term, issue time and expiry locally on every licence check. Monthly and annual terms are recorded in the token; the expiry date is enforced at the installation, including after a restart.
Configure the token through hosting configuration:
{
"UmbracoAi": {
"Licence": {
"Key": "UAT1.<signed-token>"
}
}
}
The corresponding environment variable is UmbracoAi__Licence__Key. Do not commit the token to source control where the customer site configuration is public. Commercial issuance is handled by the separate private License Issuer tool.
Server configuration
Deployment settings are server-authoritative. Azure endpoints/keys, storage, chat table names, SMTP and licence values are read from UmbracoAi hosting configuration. Content/editor settings such as feature switches, widget wording, guidance rules and indexing selections remain in the Toolkit database record. Engine:Conversations:ConnectionString can supply a separate chat account; when it is blank, it inherits LlmStorage:ConnectionString.
{
"UmbracoAi": {
"Licence": { "Key": "UAT1.<signed-token>" },
"Engine": {
"Search": { "Endpoint": "https://your-search.search.windows.net", "IndexName": "umbraco-ai", "Key": "<secret>" },
"Model": { "Endpoint": "https://your-resource.openai.azure.com", "Deployment": "<deployment-name>", "Key": "<secret>" },
"Conversations": { "ConversationTableName": "UmbracoAiConversations", "EnquiriesTableName": "UmbracoAiEnquiries" },
"MaximumChunkCharacters": 2400,
"CreateIndexIfMissing": true,
"Email": { "Enabled": true, "Host": "<smtp-host>", "Port": 587, "EnableSsl": true, "FromAddress": "<sender-address>", "Username": "<secret>", "Password": "<secret>" }
},
"LlmStorage": { "ConnectionString": "<secret>", "ContainerName": "umbraco-ai-llm" }
}
}
Supply secrets through hosting configuration. Environment examples: UmbracoAi__Licence__Key, UmbracoAi__Engine__Search__Key, UmbracoAi__Engine__Model__Key, UmbracoAi__LlmStorage__ConnectionString and UmbracoAi__Engine__Email__Password.
Optional Engine:Chat fields include MainContactPostalAddress, MainContactTelephoneDisplay, MainContactTelephoneLink and SiteSearchUrlTemplate (containing {query}). These default empty; no customer contacts or search routes are assumed. General options include MaximumRequestCharacters, LicenceCacheMinutes and FailedLicenceCacheMinutes.
Validation
dotnet test .\Umbraco.AI.Toolkit.slnx
cd .\tests\browser
npm install
npx playwright install chromium
npm test
Server tests cover Razor fallback, cleaning, storage lifecycle, named chunks, Azure SDK requests with mocked transport, enquiry/transcript confirmation and retries, and trusted server routing/history. Browser tests mock the AI endpoints and substitute Umbraco's lifecycle mixin. They cover tester registration, inline/mobile layout, settings refresh, configuration gaps, preview delivery and website popup behaviour. Screenshots are saved under tests/browser/test-output.
These checks do not verify real Azure credentials, deployed model responses, SMTP delivery or commercial licence issuance. Those require deployment-specific testing.
Page content cleanup
Database fallback groups unique page-level prose inside a named pageContent block, using the page key as its stable boundary key. Current component blocks keep their own names and keys. Page fields that repeat text already present in those blocks are omitted, and repeated page fields are included once. Comparison ignores case, whitespace and Markdown punctuation so a legacy HTML article does not duplicate its current rich-text block. Unique legacy text is retained; separate authored component blocks are not deduplicated.
Technical identifier fields, identifier lists, machine counters/ticks and administrative creation/update dates are omitted. Meaningful quantities, years and event dates remain. Rich-text list paragraphs render as readable bullets. The stored LLM file is the exact content submitted for chunking; boundary comments identify sections but are removed from the indexed chunk text. Large sections still split at the configured character limit.
Republish a page or rebuild the published branch to replace existing exports and their index chunks with the cleaned content. This cleanup does not publish draft content.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Azure.Storage.Blobs (>= 12.29.1)
- HtmlAgilityPack (>= 1.12.4)
- SteadyGo.Umbraco.AI.Toolkit.Engine (>= 1.0.2)
- Umbraco.Cms.Web.Common (>= 17.6.2 && < 18.0.0)
- Umbraco.Cms.Web.Website (>= 17.6.2 && < 18.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.