DEV: Use structured responses for summaries (#1252)

* DEV: Use structured responses for summaries

* Fix system specs

* Make response_format a first class citizen and update endpoints to support it

* Response format can be specified in the persona

* lint

* switch to jsonb and make column nullable

* Reify structured output chunks. Move JSON parsing to the depths of Completion

* Switch to JsonStreamingTracker for partial JSON parsing

Author: romanrizzi

app/controllers/discourse_ai/admin/ai_personas_controller.rb

@@ -221,6 +221,10 @@ def ai_persona_params
           permitted[:tools] = permit_tools(tools)
         end
 
+        if response_format = params.dig(:ai_persona, :response_format)
+          permitted[:response_format] = permit_response_format(response_format)
+        end
+
         permitted
       end
 
@@ -235,6 +239,18 @@ def permit_tools(tools)
           [tool, options, !!force_tool]
         end
       end
+
+      def permit_response_format(response_format)
+        return [] if !response_format.is_a?(Array)
+
+        response_format.map do |element|
+          if element && element.is_a?(ActionController::Parameters)
+            element.permit!
+          else
+            false
+          end
+        end
+      end
     end
   end
 end

app/models/ai_persona.rb

@@ -325,19 +325,24 @@ def chat_preconditions
   end
 
   def system_persona_unchangeable
+    error_msg = I18n.t("discourse_ai.ai_bot.personas.cannot_edit_system_persona")
+
     if top_p_changed? || temperature_changed? || system_prompt_changed? || name_changed? ||
          description_changed?
-      errors.add(:base, I18n.t("discourse_ai.ai_bot.personas.cannot_edit_system_persona"))
+      errors.add(:base, error_msg)
     elsif tools_changed?
       old_tools = tools_change[0]
       new_tools = tools_change[1]
 
       old_tool_names = old_tools.map { |t| t.is_a?(Array) ? t[0] : t }.to_set
       new_tool_names = new_tools.map { |t| t.is_a?(Array) ? t[0] : t }.to_set
 
-      if old_tool_names != new_tool_names
-        errors.add(:base, I18n.t("discourse_ai.ai_bot.personas.cannot_edit_system_persona"))
-      end
+      errors.add(:base, error_msg) if old_tool_names != new_tool_names
+    elsif response_format_changed?
+      old_format = response_format_change[0].map { |f| f["key"] }.to_set
+      new_format = response_format_change[1].map { |f| f["key"] }.to_set
+
+      errors.add(:base, error_msg) if old_format != new_format
     end
   end
 
@@ -395,6 +400,7 @@ def allowed_seeded_model
 #  rag_llm_model_id             :bigint
 #  default_llm_id               :bigint
 #  question_consolidator_llm_id :bigint
+#  response_format              :jsonb
 #
 # Indexes
 #

app/serializers/localized_ai_persona_serializer.rb

@@ -30,7 +30,8 @@ class LocalizedAiPersonaSerializer < ApplicationSerializer
              :allow_chat_direct_messages,
              :allow_topic_mentions,
              :allow_personal_messages,
-             :force_default_llm
+             :force_default_llm,
+             :response_format
 
   has_one :user, serializer: BasicUserSerializer, embed: :object
   has_many :rag_uploads, serializer: UploadSerializer, embed: :object

assets/javascripts/discourse/admin/models/ai-persona.js

@@ -33,6 +33,7 @@ const CREATE_ATTRIBUTES = [
   "allow_topic_mentions",
   "allow_chat_channel_mentions",
   "allow_chat_direct_messages",
+  "response_format",
 ];
 
 const SYSTEM_ATTRIBUTES = [
@@ -60,6 +61,7 @@ const SYSTEM_ATTRIBUTES = [
   "allow_topic_mentions",
   "allow_chat_channel_mentions",
   "allow_chat_direct_messages",
+  "response_format",
 ];
 
 export default class AiPersona extends RestModel {
@@ -151,6 +153,7 @@ export default class AiPersona extends RestModel {
     const attrs = this.getProperties(CREATE_ATTRIBUTES);
     this.populateTools(attrs);
     attrs.forced_tool_count = this.forced_tool_count || -1;
+    attrs.response_format = attrs.response_format || [];
 
     return attrs;
   }

assets/javascripts/discourse/components/ai-persona-editor.gjs

@@ -15,6 +15,7 @@ import Group from "discourse/models/group";
 import { i18n } from "discourse-i18n";
 import AdminUser from "admin/models/admin-user";
 import GroupChooser from "select-kit/components/group-chooser";
+import AiPersonaResponseFormatEditor from "../components/modal/ai-persona-response-format-editor";
 import AiLlmSelector from "./ai-llm-selector";
 import AiPersonaToolOptions from "./ai-persona-tool-options";
 import AiToolSelector from "./ai-tool-selector";
@@ -325,6 +326,8 @@ export default class PersonaEditor extends Component {
           <field.Textarea />
         </form.Field>
 
+        <AiPersonaResponseFormatEditor @form={{form}} @data={{data}} />
+
         <form.Field
           @name="default_llm_id"
           @title={{i18n "discourse_ai.ai_persona.default_llm"}}

assets/javascripts/discourse/components/modal/ai-persona-response-format-editor.gjs

@@ -0,0 +1,99 @@
+import Component from "@glimmer/component";
+import { tracked } from "@glimmer/tracking";
+import { fn, hash } from "@ember/helper";
+import { action } from "@ember/object";
+import { gt } from "truth-helpers";
+import ModalJsonSchemaEditor from "discourse/components/modal/json-schema-editor";
+import { prettyJSON } from "discourse/lib/formatter";
+import { i18n } from "discourse-i18n";
+
+export default class AiPersonaResponseFormatEditor extends Component {
+  @tracked showJsonEditorModal = false;
+
+  jsonSchema = {
+    type: "array",
+    uniqueItems: true,
+    title: i18n("discourse_ai.ai_persona.response_format.modal.root_title"),
+    items: {
+      type: "object",
+      title: i18n("discourse_ai.ai_persona.response_format.modal.key_title"),
+      properties: {
+        key: {
+          type: "string",
+        },
+        type: {
+          type: "string",
+          enum: ["string", "integer", "boolean"],
+        },
+      },
+    },
+  };
+
+  get editorTitle() {
+    return i18n("discourse_ai.ai_persona.response_format.title");
+  }
+
+  get responseFormatAsJSON() {
+    return JSON.stringify(this.args.data.response_format);
+  }
+
+  get displayJSON() {
+    const toDisplay = {};
+
+    this.args.data.response_format.forEach((keyDesc) => {
+      toDisplay[keyDesc.key] = keyDesc.type;
+    });
+
+    return prettyJSON(toDisplay);
+  }
+
+  @action
+  openModal() {
+    this.showJsonEditorModal = true;
+  }
+
+  @action
+  closeModal() {
+    this.showJsonEditorModal = false;
+  }
+
+  @action
+  updateResponseFormat(form, value) {
+    form.set("response_format", JSON.parse(value));
+  }
+
+  <template>
+    <@form.Container @title={{this.editorTitle}} @format="large">
+      <div class="ai-persona-editor__response-format">
+        {{#if (gt @data.response_format.length 0)}}
+          <pre class="ai-persona-editor__response-format-pre">
+            <code
+            >{{this.displayJSON}}</code>
+          </pre>
+        {{else}}
+          <div class="ai-persona-editor__response-format-none">
+            {{i18n "discourse_ai.ai_persona.response_format.no_format"}}
+          </div>
+        {{/if}}
+
+        <@form.Button
+          @action={{this.openModal}}
+          @label="discourse_ai.ai_persona.response_format.open_modal"
+          @disabled={{@data.system}}
+        />
+      </div>
+    </@form.Container>
+
+    {{#if this.showJsonEditorModal}}
+      <ModalJsonSchemaEditor
+        @model={{hash
+          value=this.responseFormatAsJSON
+          updateValue=(fn this.updateResponseFormat @form)
+          settingName=this.editorTitle
+          jsonSchema=this.jsonSchema
+        }}
+        @closeModal={{this.closeModal}}
+      />
+    {{/if}}
+  </template>
+}

assets/stylesheets/modules/ai-bot/common/ai-persona.scss

@@ -52,6 +52,21 @@
     margin-bottom: 10px;
     font-size: var(--font-down-1);
   }
+
+  &__response-format {
+    width: 100%;
+    display: block;
+  }
+
+  &__response-format-pre {
+    margin-bottom: 0;
+    white-space: pre-line;
+  }
+
+  &__response-format-none {
+    margin-bottom: 1em;
+    margin-top: 0.5em;
+  }
 }
 
 .rag-options {

config/locales/client.en.yml

@@ -323,6 +323,13 @@ en:
         rag_conversation_chunks: "Search conversation chunks"
         rag_conversation_chunks_help: "The number of chunks to use for the RAG model searches. Increase to increase the amount of context the AI can use."
         persona_description: "Personas are a powerful feature that allows you to customize the behavior of the AI engine in your Discourse forum. They act as a 'system message' that guides the AI's responses and interactions, helping to create a more personalized and engaging user experience."
+        response_format:
+          title: "JSON response format"
+          no_format: "No JSON format specified"
+          open_modal: "Edit"
+          modal:
+            root_title: "Response structure"
+            key_title: "Key"
 
         list:
           enabled: "AI Bot?"

db/fixtures/personas/603_ai_personas.rb

@@ -72,6 +72,8 @@ def from_setting(setting_name)
 
   persona.tools = tools.map { |name, value| [name, value] }
 
+  persona.response_format = instance.response_format
+
   persona.system_prompt = instance.system_prompt
   persona.top_p = instance.top_p
   persona.temperature = instance.temperature

db/migrate/20250411121705_add_response_format_json_to_personass.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+class AddResponseFormatJsonToPersonass < ActiveRecord::Migration[7.2]
+  def change
+    add_column :ai_personas, :response_format, :jsonb
+  end
+end