inquiryaisession()

edit

Sends a question/message to an AI session and returns the response. The function maintains conversation context from previous interactions within the same session.

The response can either be returned as a complete string or streamed in chunks to a listener function for real-time processing.

Also known as: LuceeInquiryAISession, aiInquirySession

inquiryaisession( session=any, question=any, listener=function );

Returns: String

Argument Description
session
any, required 		edit

The AI session object returned by LuceeCreateAISession(). This session maintains the conversation history and configuration settings like temperature and system message.

Alias: aiSession
question
any, required 		edit

The question or message to send to the AI. This can be plain text or structured data (like JSON) depending on how the session was configured in its system message.

The question becomes part of the conversation history and provides context for future interactions within the same session.

Alias: message, parts
listener
function, optional 		edit

A user-defined function that receives the response in chunks as they arrive from the AI. This enables real-time processing or display of the response.

The listener function receives the response chunk as its first argument, followed by the chunk number, whether this is the last chunk, the type of the chunk (text or binary), its content type and the part number.

When a listener is provided, the function still returns the complete response, but also streams each chunk to the listener as it arrives.

The listener can cancel the inquiry by returning boolean false (since 9.0). Lucee then stops reading the response, closes the connection to the AI and returns what has been received so far, including the chunk the listener was called with when it returned false. The listener is not called again. A listener that returns nothing, true or any other value does not cancel, the response is streamed to the end.

Usage Notes

edit

Cancelling an inquiry

Return false from the listener to stop an inquiry that is still streaming, for example when the user closed the dialog or pressed a "stop" button. This works for all the built-in AI engines (OpenAI and compatible endpoints like Ollama, Claude and Gemini).

  • the connection to the AI is closed, no more of the response is read
  • the function returns the response received so far (the text of all chunks up to and including the one that returned false), it does not throw
  • the partial answer is kept in the history of the session, so the session can be used for follow-up questions
  • returning nothing, true or any value other than the boolean false continues the inquiry as before

Examples

edit 
// AI service name, e.g., "test_ai"
aiSession = LuceeCreateAISession("test_ai");
result = LuceeInquiryAISession(aiSession, "What is Lucee?");
writeDump(result);

Cancel an inquiry from the listener (since 9.0)

Returning false from the listener stops the inquiry. The function returns what was received up to that point.

aiSession = createAISession( name: "test_ai" );
// stop after the first 200 characters
received = "";
answer = inquiryAISession( aiSession, "Tell me a long story", function( chunk ) {
	received &= chunk;
	if ( len( received ) >= 200 ) return false; // cancels the inquiry
} );
// answer contains the text received so far
writeOutput( answer );

The listener can also be a function of a component, created with new:

// StopAfter.cfc
component {
	variables.max = 0;
	variables.count = 0;
	function init( required numeric max ) {
		variables.max = arguments.max;
		return this;
	}
	function listen( chunk ) {
		variables.count++;
		// false cancels the inquiry
		return variables.count < variables.max;
	}
}
<div class="highlight"><pre><span></span>
</pre></div>
<br>lucee
aiSession = createAISession( name: "test_ai" );
stopper = new StopAfter( 5 );
answer = inquiryAISession( aiSession, "Count from 1 to 100", stopper.listen );
writeOutput( answer ); // only what arrived in the first 5 chunks

Or a static function of a component, using import and :::

// Listeners.cfc
component {
	static function stopOnKeyword( chunk ) {
		return !findNoCase( "stop", chunk );
	}
}
<div class="highlight"><pre><span></span>
</pre></div>
<br>lucee
import Listeners;
aiSession = createAISession( name: "test_ai" );
answer = inquiryAISession( aiSession, "Count from 1 to 100", Listeners::stopOnKeyword );

See also