Merge pull request #304 from SuffolkLITLab/nicer-questionnaire

Reduce latency, add tests for questionnaire feature

Author: nonprofittechy

.gitignore

@@ -10,4 +10,5 @@ docassemble.ALToolbox.egg-info/**
 
 # Python testing stuff
 .coverage
-coverage_html
+coverage_html
+.env

docassemble/ALToolbox/data/questions/goal_oriented_question_structured_demo.yml

@@ -3,21 +3,40 @@ include:
   - goal_oriented_question_structured.yml
 ---
 metadata:
-  title: Legal Aid Intake - Structured Initial Question Demo
-  short title: Structured Intake Demo
+  title: Legal Aid Intake - Goal-Oriented Questions Demo (Structured or Unstructured)
+  short title: Flexible Intake Demo
   description: |
-    This interview demonstrates using GoalOrientedQuestionList with a
-    structured initial question (using radio buttons, checkboxes, etc.)
-    instead of an open-ended narrative response.
+    This interview demonstrates using GoalOrientedQuestionList with either
+    a structured initial question (using radio buttons, checkboxes, etc.)
+    or an open-ended narrative response. You can choose the format that works
+    best for your use case.
 ---
 objects:
-  - housing_intake: GoalOrientedQuestionList.using(rubric="The response provides complete information about the tenant's housing situation, including the type of issue, timeline, communication with landlord, and any immediate safety or habitability concerns.", initial_question="We need to understand your housing situation to determine how we can help. Please provide information about your housing issue.", llm_assumed_role="housing intake specialist", user_assumed_role="tenant seeking help")
+  - housing_intake: GoalOrientedQuestionList.using(
+                    rubric="The response provides complete information about the tenant's housing situation, including the type of issue, timeline, communication with landlord, and any immediate safety or habitability concerns.",
+                    initial_question="We need to understand your housing situation to determine how we can help. Please provide information about your housing issue.",
+                    llm_assumed_role="housing intake specialist", 
+                    user_assumed_role="tenant seeking help",
+                    model=model,
+                    reasoning_effort=reasoning_effort,
+                    skip_moderation=skip_moderation,
+                  )
 ---
 mandatory: True
 code: |
   intro_screen
-  # Trigger the initial structured question
-  housing_intake._initial_structured_complete
+  question_format_choice
+  
+  # Set the use_structured_initial_question based on user choice
+  if question_format == "structured":
+    housing_intake.use_structured_initial_question = True
+    # Trigger the initial structured question
+    housing_intake._initial_structured_complete
+  else:
+    housing_intake.use_structured_initial_question = False
+    # Trigger the initial open-ended question
+    housing_intake.initial_draft
+  
   housing_intake.gather()
   final_response
   intake_summary
@@ -28,27 +47,80 @@ code: |
   else:
     final_response_default = housing_intake.initial_response_as_text()
 ---
+code: |
+  # This code block is needed to define the question_format_choice step
+  question_format_choice = True
+---
 continue button field: intro_screen
 question: |
-  Welcome to Housing Legal Aid Intake (Structured)
+  Welcome to Housing Legal Aid Intake
 subquestion: |
   This demo shows how the **GoalOrientedQuestionList** can use structured
-  fields (radio buttons, checkboxes, etc.) for the initial question instead
-  of requiring an open-ended narrative.
+  fields (radio buttons, checkboxes, etc.) or an open-ended narrative for 
+  the initial question.
   
   #### Scenario
   
   You are seeking help with a housing issue. An intake worker needs to understand
-  your situation using a structured form.
+  your situation to determine if you qualify for services and to prepare for
+  your initial consultation.
   
   #### How it works:
   
-  1. The AI will generate structured fields for the initial question based on the rubric
-  2. You'll answer using radio buttons, checkboxes, dates, etc. (not just a text area)
-  3. The AI will then ask follow-up questions if more information is needed
-  4. Your responses will be synthesized into a complete intake summary
+  1. You'll choose between a structured form or an open-ended question
+  2. You'll provide information about your housing situation
+  3. The AI will evaluate your response to see if it provides enough detail
+  4. If more information is needed, you'll get follow-up questions
+  5. Your responses will be synthesized into a complete intake summary
+  
+  This approach allows you to choose the most appropriate format for data collection.
+---
+question: |
+  Choose your initial question format
+subquestion: |
+  How would you like to provide information about your housing situation?
+fields: 
+  - Question format: question_format
+    datatype: radio
+    choices:
+      - Structured form with specific fields (AI-generated): structured
+      - Open-ended narrative response: unstructured
+  - Reasoning effort: reasoning_effort
+    datatype: radio
+    choices:
+      - Minimal: minimal
+      - Low effort (faster responses, less depth): low
+      - Medium effort (balanced speed and depth): medium
+      - High effort (more thoughtful responses, slower): high
+  - Skip moderation: skip_moderation
+    datatype: yesnoradio
+    default: True
+  - Model: model
+    datatype: radio
+    choices:
+      - gpt-4.1-nano
+      - gpt-5-nano
+      - gpt-5-mini
+---
+question: |
+  Tell us about your housing situation
+subquestion: |
+  To help us prepare for your consultation, please tell us about your housing issue.
+  
+  You can describe:
+  
+  * What type of problem you're having (repairs, eviction, etc.)
+  * When the issue started
+  * What you've tried to do about it
+  * Any communication with your landlord
+  * Whether there are safety or health concerns
   
-  This approach is useful when you want more structured data collection from the start.
+  Don't worry if you're not sure what's important—just tell us about your 
+  situation in your own words.
+fields:
+  - Your response: housing_intake.initial_draft
+    datatype: area
+    rows: 8
 ---
 question: |
   Review your intake information
@@ -97,17 +169,17 @@ subquestion: |
   
   #### About this demo
   
-  This demo used a **GoalOrientedQuestionList** with structured initial question:
+  This demo used a **GoalOrientedQuestionList** with:
   
-  * **Initial question format**: Structured fields (generated by AI)
+  * **Initial question format**: ${ "Structured fields (generated by AI)" if question_format == "structured" else "Open-ended narrative" }
   * **Question limit**: ${ housing_intake.question_limit } follow-up questions maximum
   * **Follow-ups asked**: ${ len(housing_intake) }
   * **Sufficient information gathered**: ${ "Yes" if housing_intake.satisfied() else "Partially" }
   * **Model**: ${ housing_intake.model }
   * **LLM role**: ${ housing_intake.llm_assumed_role }
   * **User role**: ${ housing_intake.user_assumed_role }
   
-  The AI generated structured fields for the initial question and then asked follow-ups until the response met this rubric:
+  The AI ${ "generated structured fields for the initial question and then" if question_format == "structured" else "" } asked follow-ups until the response met this rubric:
   
   > ${ housing_intake.rubric }
 buttons:

docassemble/ALToolbox/llms.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union, Literal
 import keyword
 import os
 import json
@@ -126,6 +126,7 @@ def chat_completion(
     openai_base_url: Optional[str] = None,  # "https://api.openai.com/v1/",
     max_output_tokens: Optional[int] = None,
     max_input_tokens: Optional[int] = None,
+    reasoning_effort: Optional[Literal["minimal", "low", "medium", "high"]] = None,
 ) -> Union[List[Any], Dict[str, Any], str]:
     """A light wrapper on the OpenAI chat endpoint.
 
@@ -144,10 +145,14 @@ def chat_completion(
         openai_base_url (Optional[str]): The base URL for the OpenAI API. Defaults to value provided in the configuration or "https://api.openai.com/v1/".
         max_output_tokens (Optional[int]): The maximum number of tokens to return from the API. Defaults to 16380.
         max_input_tokens (Optional[int]): The maximum number of tokens to send to the API. Defaults to 128000.
+        reasoning_effort (Optional[Literal["minimal", "low", "medium", "high"]]) = None: The reasoning effort to use for thinking models. Defaults to value provided in the configuration or "low".
 
     Returns:
         A string with the response from the API endpoint or JSON data if json_mode is True
     """
+    if not reasoning_effort:
+        reasoning_effort = get_config("open ai", {}).get("reasoning effort") or "low"
+
     if not openai_base_url:
         openai_base_url = (
             get_config("open ai", {}).get("base url") or "https://api.openai.com/v1/"
@@ -242,22 +247,24 @@ def chat_completion(
 
     # Build completion parameters based on model type
     if is_thinking_model:
-        # Thinking models don't support temperature
+        # Thinking models don't support temperature but do support reasoning_effort
         if json_mode:
             response = openai_client.chat.completions.create(  # type: ignore[call-overload]
                 model=model,
                 messages=messages,  # type: ignore[arg-type]
                 response_format={"type": "json_object"},
                 max_completion_tokens=max_output_tokens,
+                reasoning_effort=reasoning_effort,
             )
         else:
             response = openai_client.chat.completions.create(  # type: ignore[call-overload]
                 model=model,
                 messages=messages,  # type: ignore[arg-type]
                 max_completion_tokens=max_output_tokens,
+                reasoning_effort=reasoning_effort,
             )
     else:
-        # Regular models support temperature
+        # Regular models support temperature but not reasoning_effort
         if json_mode:
             response = openai_client.chat.completions.create(  # type: ignore[call-overload]
                 model=model,
@@ -1050,6 +1057,8 @@ class GoalOrientedQuestionList(DAList):
         model (str): The model to use for the OpenAI API. Defaults to "gpt-5-nano".
         llm_assumed_role (str): The role for the LLM to assume. Defaults to "legal aid intake worker".
         user_assumed_role (str): The role for the user to assume. Defaults to "applicant for legal help".
+        skip_moderation (bool): If True, skips moderation checks when generating structured fields. Defaults to True.
+        reasoning_effort (Optional[Literal["minimal", "low", "medium", "high"]]): The level of reasoning effort to use when generating responses. Defaults to "low"; use "minimal" for increased speed.
     """
 
     def init(self, *pargs, **kwargs):
@@ -1072,6 +1081,12 @@ def init(self, *pargs, **kwargs):
         if not hasattr(self, "use_structured_initial_question"):
             self.use_structured_initial_question = False
 
+        if not hasattr(self, "skip_moderation"):
+            self.skip_moderation = True
+
+        if not hasattr(self, "reasoning_effort"):
+            self.reasoning_effort = "low"
+
     def generate_initial_question_fields(self) -> Dict[str, Any]:
         """Generate structured fields for the initial question using the LLM.
 
@@ -1083,14 +1098,16 @@ def generate_initial_question_fields(self) -> Dict[str, Any]:
         """
         system_message = f"""You are a {self.llm_assumed_role} creating an intake form.
         
-        Based on this question, generate 1-5 structured fields to gather the initial information:
+        Based on this question, generate between 1 and 3 structured fields to gather the initial information:
         
         Question: {self.initial_question}
         
         Goal: {self.rubric}
         
-        Create structured fields that will help gather relevant information. Use structured question types
-        (yesnoradio, radio, checkboxes, date, currency, email) whenever possible.
+        Create structured fields that will help gather relevant information.
+
+        Whenever possible, use structured field types (yes/no, multiple choice, checkboxes, date, currency, etc.).
+        Only use open-ended text/area fields when a limited response format is insufficient.
         
         Respond with a JSON object in this format:
         {{
@@ -1107,13 +1124,18 @@ def generate_initial_question_fields(self) -> Dict[str, Any]:
         }}
         
         Guidelines:
-        - Generate 1-5 fields that capture the key information needed
+        - Generate 1-3 specific fields that help gather information relevant to the rubric
         - Use yesnoradio for yes/no questions
         - Use radio for single-choice questions (2-5 options)
         - Use checkboxes for multiple-choice questions
         - Use text for short text responses
-        - Use area for longer narrative responses
+        - Use area when longer narrative is needed
+        - Use date only when a precise date is likely to be known, or text when the date is likely to be approximate
+        - Use currency for dollar amounts
+        - Use email for email addresses
         - All fields must have required: false
+        - Write questions and field labels at about a 6th-grade reading level
+        - Ask one question per field, avoiding compound questions
         """
 
         results = chat_completion(
@@ -1122,6 +1144,8 @@ def generate_initial_question_fields(self) -> Dict[str, Any]:
             ],
             model=self.model,
             json_mode=True,
+            skip_moderation=self.skip_moderation,
+            reasoning_effort=self.reasoning_effort,
         )
         assert isinstance(results, dict)
         return results
@@ -1270,7 +1294,7 @@ def _check_satisfaction(self) -> Union[str, Dict[str, Any]]:
         If the goal or rubric is satisfied, respond with a JSON object containing only:
         {{"status": "satisfied"}}
 
-        If the goal or rubric is NOT satisfied, generate a follow-up question with 1-3 specific fields to gather missing information.
+        If the goal or rubric is NOT satisfied, generate a follow-up question with no more than 3 specific fields to gather missing information.
         The user will always have an opportunity to provide additional open-ended context in a text area field that you do not need to
         generate.
 
@@ -1283,8 +1307,6 @@ def _check_satisfaction(self) -> Union[str, Dict[str, Any]]:
         - If the user provides information that partially answers a question, DO NOT ask for the exact same information again
         - Only ask clarifying questions if critical details are genuinely missing AND the user hasn't already declined to provide them
         - If a question has been asked 2+ times without a satisfactory answer, STOP asking and move to different missing information
-
-        Use structured question types (yesnoradio, radio, checkboxes, date, currency, email) whenever possible instead of open-ended text.
         
         Respond with a JSON object in this format:
         {{
@@ -1313,6 +1335,11 @@ def _check_satisfaction(self) -> Union[str, Dict[str, Any]]:
         - Use email for email addresses
         - All fields must have required: false
         - Write questions and field labels at about a 6th-grade reading level
+
+        Use structured question types (yesnoradio, radio, checkboxes, date, currency, email)
+        as much as possible and whenever presenting multiple options. Only use an open-ended question when absolutely necessary.
+        You can direct the user to provide additional context in the open-ended text area that will always be present if an "other"
+        option is likely to be needed.
         """
 
         # Build message thread
@@ -1340,6 +1367,8 @@ def _check_satisfaction(self) -> Union[str, Dict[str, Any]]:
             messages=messages,
             model=self.model,
             json_mode=True,
+            skip_moderation=self.skip_moderation,
+            reasoning_effort=self.reasoning_effort,
         )
         assert isinstance(results, dict)
 
@@ -1470,6 +1499,8 @@ def provide_feedback(
         return chat_completion(
             messages=messages,
             model=self.model,
+            skip_moderation=self.skip_moderation,
+            reasoning_effort=self.reasoning_effort,
         )
 
 
@@ -1563,6 +1594,12 @@ def init(self, *pargs, **kwargs):
                 "tax": "problems with tax law, such as getting help with tax debt, dealing with the IRS, or getting help with tax preparation",
             }
 
+        if not hasattr(self, "reasoning_effort"):
+            self.reasoning_effort = "low"
+
+        if not hasattr(self, "skip_moderation"):
+            self.skip_moderation = True
+
     def _classify_problem_type(self):
         """Classifies the problem type based on the user's initial description."""
         return classify_text(
@@ -1654,6 +1691,8 @@ def _current_qualification_status(self):
             model=self.model,
             max_output_tokens=self.max_output_tokens,
             json_mode=True,
+            skip_moderation=self.skip_moderation,
+            reasoning_effort=self.reasoning_effort,
         )
 
         if isinstance(results, dict):