Skip to content

Add recipe: creating an extension that provides an AI engine - #1569

Merged
michaeloffner merged 2 commits into
lucee:masterfrom
GianTschingt:recipe-ai-engine-extension
Oct 2, 2026
Merged

michaeloffner merged 2 commits into
lucee:masterfrom
GianTschingt:recipe-ai-engine-extension

Conversation

@GianTschingt

Copy link
Copy Markdown
Contributor

New recipe docs/recipes/ai-engine-extension.md, explaining how an extension can provide its own AI engine, the same way the S3 extension provides a VFS resource provider.

  • The lucee.runtime.ai.* interfaces in the loader (since 7.0.0.114, LDEV-5368), with their signatures, and what Lucee expects from an implementation
  • A minimal engine and session for OpenAI compatible chat/completions endpoints, using only the JDK (java.net.http) and the loader API
  • Packaging as a .lex, both as an OSGi bundle and as a Maven artifact (start-bundles: false)
  • Registering the engine with an ai entry (class + bundleName/bundleVersion or maven, custom). There is no manifest key for AI engines.
  • Using it from CFML, with links to the related recipes

The example code compiles (javac --release 11 -Xlint:all -Werror) against the 7.0.5.41, 7.1.1.15-RC and 8.0.0.189-SNAPSHOT loaders. It was tested as an installed extension (OSGi and Maven) on 7.1.1.15-RC and 8.0.0.189-SNAPSHOT against a local mock endpoint.

Index, README and lucee.skill regenerated with .github/scripts/generate-index-recipes.js.

Possible follow-ups (not changed here):

  • loader-api-changes-7.md names AICreateSession and AIChat as functions. aiCreateSession exists as an alias, but there's no AIChat. The functions are createAISession()/inquiryAISession() (aliases aiCreateSession/aiInquirySession).
  • extension-utilities.md lists the AI util as "Since: 6.2", but CFMLEngine.getAIUtil() only exists from 7.0. The example also doesn't match the interface: it is List<String> getModelNames(AIEngine) and getMetaData(AIEngine, boolean, boolean), not getModelNames(null) returning String[] or getAIMetadata(pc, name, false).
  • ai.md mentions getAIMetadata()/LuceeGetAIMetadata(); the functions are AIGetMetaData()/LuceeAIGetMetaData().
  • On 8.0.0.189-SNAPSHOT, createAISession(name:, systemMessage:) without limit/temperature passes limit=1 and temperature=1 to the engine (also with the core OpenAIEngine), so only the last exchange is kept in the history. 7.1 passes the FLD defaults 50/0.7. This looks related to the defaults being removed from the 8.0 FLD.

Explain the admin drivers (built-in drivers, what a driver contains, where it goes in the .lex, how the Administrator writes the ai entry) with a minimal driver for the example engine. The example engine now treats empty custom values as not set, as the Administrator stores empty fields as empty strings.
@michaeloffner
michaeloffner merged commit 4341799 into lucee:master Oct 2, 2026
2 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants