Aivie.Content 18.0.0

Aivie Content for Umbraco

Content generation, keyword management, content planning and a chat assistant inside the Umbraco backoffice.

Aivie runs on Umbraco.AI as its engine: that package talks to the models, Aivie supplies the contexts, the agents and the tools. Umbraco.AI is installed as a dependency of this package; you do not need to add it yourself. The background jobs run inside Aivie itself, so no scheduling package is needed either.

Works on SQL Server and SQLite. About forty tables with the prefix aivie_ are created automatically in the Umbraco database on first start; no separate connection string is needed.

Full documentation - configuration, settings, licence, Google Search Console - is at https://docs.aivie.nl. This page covers what you need to install the package.

Before you install

Which version? Aivie Content follows Umbraco: the first number of the package version is the Umbraco version it is built for. A 17 package does not install on Umbraco 18, and the other way round.

Does your site use HtmlSanitizer? Make sure it is on version 9.1.973 or newer.

dotnet add package HtmlSanitizer --version 9.1.973

Do this before you add Aivie. Otherwise the restore fails with an NU1107 error about AngleSharp, and the advice in that error message - to add AngleSharp directly - makes things worse.

The reason: HtmlSanitizer 9.0.x pins AngleSharp to exactly 0.17.1, while Umbraco.AI needs AngleSharp 1.4 or newer through SmartReader. The two cannot be reconciled. NuGet cannot raise a direct package reference in your own project by itself, so this is the one step you have to take by hand.

Installing

On an Umbraco 18 site:

dotnet add package Aivie.Content

On an Umbraco 17 site, name the version:

dotnet add package Aivie.Content --version "17.*"

Without --version, NuGet takes the newest version, and that is an 18.x. On an Umbraco 17 site the restore then fails with error NU1107, and the 18.x reference stays in your .csproj. If that happened, run dotnet remove package Aivie.Content and add the package again with --version "17.*".

Upgrading a site from Umbraco 17 to 18 moves Aivie to 18.x in the same step: update Umbraco.Cms and Aivie.Content together. The steps are at https://docs.aivie.nl.

Then one block in Program.cs: pin Data Protection. It is optional but strongly recommended. Nothing else in your site needs to change; all Aivie registrations happen through composers.

// At the top of the file; without this using the compiler does not know SetApplicationName and
// PersistKeysToFileSystem (CS1061).
using Microsoft.AspNetCore.DataProtection;

// Pin Data Protection.
//
// Without this, .NET stores the key ring in the profile of the account the site runs under, and
// derives the application discriminator from the content root path. Encrypted values become
// unreadable as soon as the app pool runs under a different account, the profile is not loaded, or
// the folder is moved.
//
// Umbraco.AI stores a connection's API key this way. If it can no longer be decrypted, the backoffice
// shows the raw value and encrypts it again on save - after which the connection is permanently
// broken. The same key ring protects login sessions and OpenIddict tokens.
//
// The folder belongs in your backups and must not be cleaned up. With multiple servers this must be a
// shared location.
builder.Services
    .AddDataProtection()
    .SetApplicationName("YourProject")
    .PersistKeysToFileSystem(
        new DirectoryInfo(Path.Combine(
            builder.Environment.ContentRootPath, "umbraco", "Data", "DataProtection-Keys")));

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .Build();

WebApplication app = builder.Build();

First start

Start the site and open the backoffice. The Aivie section contains a setup screen that configures the OpenAI connection, the agents, the contexts, the subscription and section access. You need an OpenAI API key; it is stored under Umbraco:AI:Secrets:OpenAiKey, where Umbraco.AI reads it itself.

External integrations - DataForSeo, Google Search Console - you set up afterwards; they may be left empty, and the corresponding feature then stays off.

How to connect them (Google Search Console needs a service account and a property), and what to check when you upgrade from an earlier version, is described at https://docs.aivie.nl.

Who can use Aivie. Only users who have the Aivie section can use the chat and the "Generate with AI" button. Aivie's chat tools do only what the user may do in Umbraco: they respect start nodes, permissions per page and read access. Give editors the Aivie group (or add the Aivie section to their own group) under Users.

Terms of use

The terms of use for Aivie are published at https://www.aivie.nl. Please read them before you use the package in production.

The full installation guide and the editor guide are at https://docs.aivie.nl.