podojo-cli 1.5.2__tar.gz → 1.7.0__tar.gz

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to the Podojo CLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com),
 and this project adheres to [Semantic Versioning](https://semver.org).
 
+## [1.7.0] - 2026-07-04
+
+### Added
+- User tests support an optional participant screener: `screening_questions` (single-select, options flagged `qualifies: true`) and `rejection_message`, mirroring AI interviews. `validate`/`create` check the screener shape, and `example` shows the new fields.
+
+## [1.6.0] - 2026-07-03
+
+### Added
+- AI interviews support an optional participant screener: `screening_questions` (single-select, options flagged `qualifies: true`) and `rejection_message`. `validate`/`create` check the screener shape, and `example` shows the new fields.
+
 ## [1.5.2] - 2026-07-02
 
 ### Changed

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: podojo-cli
-Version: 1.5.2
+Version: 1.7.0
 Summary: CLI for the Podojo user research platform
 Project-URL: Homepage, https://github.com/podojo/cli-podojo
 Project-URL: Source, https://github.com/podojo/cli-podojo
@@ -123,6 +123,12 @@ podojo usertests delete checkout-usability-v1
 podojo usertests snippet                  # recorder script for self-hosted prototypes
 ```
 
+A user test can open with an optional participant screener: on-screen
+single-select `screening_questions` whose options carry `qualifies: true`
+flags. Participants must pick a qualifying option on every question; everyone
+else sees the test's `rejection_message` and never reaches the recorded test.
+See `podojo usertests example` for the exact shape.
+
 ### AI interviews
 
 An AI interview is a self-serve voice conversation: an AI interviewer asks
@@ -143,6 +149,12 @@ podojo aiinterviews delete checkout-experience-v1
 base URL can be overridden via `ai_interviews_url` in `~/.podojo.toml` or
 `PODOJO_AI_INTERVIEWS_URL`.
 
+A study can open with an optional participant screener: on-screen single-select
+`screening_questions` whose options carry `qualifies: true` flags. Participants
+must pick a qualifying option on every question; everyone else sees the study's
+`rejection_message` and never reaches the voice interview. See
+`podojo aiinterviews example` for the exact shape.
+
 ### Synthetic participants
 
 The `synth` group drives a Playwright browser through a user test preview so an

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/README.md

@@ -92,6 +92,12 @@ podojo usertests delete checkout-usability-v1
 podojo usertests snippet                  # recorder script for self-hosted prototypes
 ```
 
+A user test can open with an optional participant screener: on-screen
+single-select `screening_questions` whose options carry `qualifies: true`
+flags. Participants must pick a qualifying option on every question; everyone
+else sees the test's `rejection_message` and never reaches the recorded test.
+See `podojo usertests example` for the exact shape.
+
 ### AI interviews
 
 An AI interview is a self-serve voice conversation: an AI interviewer asks
@@ -112,6 +118,12 @@ podojo aiinterviews delete checkout-experience-v1
 base URL can be overridden via `ai_interviews_url` in `~/.podojo.toml` or
 `PODOJO_AI_INTERVIEWS_URL`.
 
+A study can open with an optional participant screener: on-screen single-select
+`screening_questions` whose options carry `qualifies: true` flags. Participants
+must pick a qualifying option on every question; everyone else sees the study's
+`rejection_message` and never reaches the voice interview. See
+`podojo aiinterviews example` for the exact shape.
+
 ### Synthetic participants
 
 The `synth` group drives a Playwright browser through a user test preview so an

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "podojo-cli"
-version = "1.5.2"
+version = "1.7.0"
 description = "CLI for the Podojo user research platform"
 readme = "README.md"
 license = "MIT"

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/src/podojo_cli/commands/aiinterviews.py

@@ -24,13 +24,21 @@ EXAMPLE_YAML = """\
 #
 # Required fields: interview_id, title, questions, closing_message
 # Optional fields: language (default en-US), project_name, overview,
-#                  decision, live
+#                  decision, screening_questions, rejection_message, live
 #
 # Each question:
 #   text            (required) the main question, asked verbatim-ish in order
 #   section         (optional) researcher-facing grouping label
 #   max_follow_ups  (optional, default 2) adaptive follow-up budget
 #   probe_for       (optional) what a concrete answer must cover — drives follow-ups
+#
+# Each screening question (optional participant screener, answered on screen
+# before the voice interview starts):
+#   text            (required) single-select multiple-choice question
+#   options         (required, at least 2) each with `text` and an optional
+#                   `qualifies: true` — participants must pick a qualifying
+#                   option on every question, otherwise they see the
+#                   rejection_message and the interview never starts
 
 interview_id: checkout-experience-v1
 title: Checkout Experience Research
@@ -57,6 +65,30 @@ decision: >
 # Optional: set interview live (default: false)
 # live: true
 
+# Optional: participant screener — shown on screen (no audio) before the
+# conversation. Answers are captured alongside the session's recording.
+screening_questions:
+  - text: How often do you shop online?
+    options:
+      - text: Rarely or never
+      - text: A few times a year
+      - text: At least once a month
+        qualifies: true
+      - text: Weekly or more
+        qualifies: true
+
+  - text: Have you abandoned an online purchase at checkout in the past 3 months?
+    options:
+      - text: "Yes"
+        qualifies: true
+      - text: "No"
+      - text: Not sure
+
+# Optional: shown to participants whose screener answers don't qualify
+rejection_message: >
+  Thank you for your time, you did not meet the research criteria for this
+  study!
+
 questions:
   - section: Shopping Habits
     text: >
@@ -118,6 +150,38 @@ def validate_ai_interview_data(data: dict) -> list[str]:
                     errors.append(
                         f"Question {i}: 'max_follow_ups' must be an integer >= 0, got '{max_follow_ups}'"
                     )
+
+    screening_questions = data.get("screening_questions")
+    if screening_questions is not None:
+        if not isinstance(screening_questions, list):
+            errors.append("'screening_questions' must be a list")
+        else:
+            for i, question in enumerate(screening_questions, 1):
+                if not isinstance(question, dict) or "text" not in question:
+                    errors.append(f"Screening question {i}: must be a mapping with 'text'")
+                    continue
+                options = question.get("options")
+                if not isinstance(options, list) or len(options) < 2:
+                    errors.append(f"Screening question {i}: 'options' must list at least 2 options")
+                    continue
+                qualifying = 0
+                for j, option in enumerate(options, 1):
+                    if not isinstance(option, dict) or "text" not in option:
+                        errors.append(
+                            f"Screening question {i}, option {j}: must be a mapping with 'text'"
+                        )
+                        continue
+                    qualifies = option.get("qualifies", False)
+                    if not isinstance(qualifies, bool):
+                        errors.append(
+                            f"Screening question {i}, option {j}: 'qualifies' must be true or false"
+                        )
+                    elif qualifies:
+                        qualifying += 1
+                if qualifying == 0:
+                    errors.append(
+                        f"Screening question {i}: needs at least one option with 'qualifies: true'"
+                    )
     return errors
 
 

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/src/podojo_cli/commands/usertests.py

@@ -37,7 +37,16 @@ EXAMPLE_YAML = """\
 #
 # Required fields: usertest_id, title, logo, prototype_url, steps
 # Optional fields: welcome_text, promo_code, promo_code_info,
+#                  screening_questions, rejection_message,
 #                  project_name, live, collect_contact
+#
+# Each screening question (optional participant screener, answered on screen
+# before consent — screening is never recorded):
+#   text            (required) single-select multiple-choice question
+#   options         (required, at least 2) each with `text` and an optional
+#                   `qualifies: true` — participants must pick a qualifying
+#                   option on every question, otherwise they see the
+#                   rejection_message and the test never starts
 
 usertest_id: checkout-usability-v1
 title: Checkout Flow Usability Test
@@ -66,6 +75,31 @@ project_name: checkout-redesign-q1
 # Optional: collect participant name/email on the final screen (default: false)
 # collect_contact: true
 
+# Optional: participant screener — shown on screen before consent and
+# recording. Only qualified participants reach the test; screen-out answers
+# are still captured for funnel metrics.
+screening_questions:
+  - text: How often do you shop online?
+    options:
+      - text: Rarely or never
+      - text: A few times a year
+      - text: At least once a month
+        qualifies: true
+      - text: Weekly or more
+        qualifies: true
+
+  - text: Have you abandoned an online purchase at checkout in the past 3 months?
+    options:
+      - text: "Yes"
+        qualifies: true
+      - text: "No"
+      - text: Not sure
+
+# Optional: shown to participants whose screener answers don't qualify
+rejection_message: >
+  Thank you for your time, you did not meet the research criteria for this
+  study!
+
 # Steps define what participants see and do
 # Each step requires: type ("screen" or "prototype") and title
 # Screen steps should have a variant: "question" (open-ended), "task" (action-based),
@@ -143,6 +177,38 @@ def validate_usertest_data(data: dict) -> list[str]:
                     errors.append(
                         f"Step {i}: 'variant' must be one of {sorted(VALID_STEP_VARIANTS)}, got '{variant}'"
                     )
+
+    screening_questions = data.get("screening_questions")
+    if screening_questions is not None:
+        if not isinstance(screening_questions, list):
+            errors.append("'screening_questions' must be a list")
+        else:
+            for i, question in enumerate(screening_questions, 1):
+                if not isinstance(question, dict) or "text" not in question:
+                    errors.append(f"Screening question {i}: must be a mapping with 'text'")
+                    continue
+                options = question.get("options")
+                if not isinstance(options, list) or len(options) < 2:
+                    errors.append(f"Screening question {i}: 'options' must list at least 2 options")
+                    continue
+                qualifying = 0
+                for j, option in enumerate(options, 1):
+                    if not isinstance(option, dict) or "text" not in option:
+                        errors.append(
+                            f"Screening question {i}, option {j}: must be a mapping with 'text'"
+                        )
+                        continue
+                    qualifies = option.get("qualifies", False)
+                    if not isinstance(qualifies, bool):
+                        errors.append(
+                            f"Screening question {i}, option {j}: 'qualifies' must be true or false"
+                        )
+                    elif qualifies:
+                        qualifying += 1
+                if qualifying == 0:
+                    errors.append(
+                        f"Screening question {i}: needs at least one option with 'qualifies: true'"
+                    )
     return errors
 
 

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/tests/test_aiinterviews.py

@@ -305,6 +305,87 @@ def test_validate_invalid(runner, tmp_path):
     assert "Missing required field" in result.output
 
 
+SCREENING_YAML = VALID_AI_INTERVIEW_YAML + """\
+screening_questions:
+  - text: Do you currently drive for a ridehailing platform?
+    options:
+      - text: "Yes"
+        qualifies: true
+      - text: "No"
+  - text: How many rides did you complete last month?
+    options:
+      - text: 0 rides
+      - text: 1-10 rides
+        qualifies: true
+      - text: More than 10 rides
+        qualifies: true
+rejection_message: You did not meet the research criteria for this study.
+"""
+
+
+def test_validate_with_screening(runner, tmp_path):
+    yaml_file = tmp_path / "interview.yaml"
+    yaml_file.write_text(SCREENING_YAML)
+
+    result = runner.invoke(app, ["aiinterviews", "validate", str(yaml_file)])
+
+    assert result.exit_code == 0
+    assert "Valid AI interview config" in result.output
+
+
+def test_validate_screening_question_needs_two_options(runner, tmp_path):
+    yaml_file = tmp_path / "interview.yaml"
+    yaml_file.write_text(
+        VALID_AI_INTERVIEW_YAML
+        + "screening_questions:\n"
+        + "  - text: Only one way to answer?\n"
+        + "    options:\n"
+        + "      - text: \"Yes\"\n"
+        + "        qualifies: true\n"
+    )
+
+    result = runner.invoke(app, ["aiinterviews", "validate", str(yaml_file)])
+
+    assert result.exit_code == 1
+    assert "'options' must list at least 2 options" in result.output
+
+
+def test_validate_screening_question_needs_a_qualifying_option(runner, tmp_path):
+    yaml_file = tmp_path / "interview.yaml"
+    yaml_file.write_text(
+        VALID_AI_INTERVIEW_YAML
+        + "screening_questions:\n"
+        + "  - text: Nobody can pass this one\n"
+        + "    options:\n"
+        + "      - text: A\n"
+        + "      - text: B\n"
+    )
+
+    result = runner.invoke(app, ["aiinterviews", "validate", str(yaml_file)])
+
+    assert result.exit_code == 1
+    assert "needs at least one option with 'qualifies: true'" in result.output
+
+
+def test_validate_screening_option_qualifies_must_be_bool(runner, tmp_path):
+    yaml_file = tmp_path / "interview.yaml"
+    yaml_file.write_text(
+        VALID_AI_INTERVIEW_YAML
+        + "screening_questions:\n"
+        + "  - text: Q\n"
+        + "    options:\n"
+        + "      - text: A\n"
+        + "        qualifies: yep\n"
+        + "      - text: B\n"
+        + "        qualifies: true\n"
+    )
+
+    result = runner.invoke(app, ["aiinterviews", "validate", str(yaml_file)])
+
+    assert result.exit_code == 1
+    assert "'qualifies' must be true or false" in result.output
+
+
 def test_example(runner):
     result = runner.invoke(app, ["aiinterviews", "example"])
 
@@ -313,6 +394,8 @@ def test_example(runner):
     assert "questions:" in result.output
     assert "closing_message:" in result.output
     assert "max_follow_ups:" in result.output
+    assert "screening_questions:" in result.output
+    assert "rejection_message:" in result.output
 
 
 def test_example_validates(runner, tmp_path):

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/tests/test_usertests.py

@@ -292,6 +292,87 @@ def test_validate_invalid(runner, tmp_path):
     assert "Missing required field" in result.output
 
 
+SCREENING_YAML = VALID_USERTEST_YAML + """\
+screening_questions:
+  - text: Do you shop online?
+    options:
+      - text: "Yes"
+        qualifies: true
+      - text: "No"
+  - text: How often do you shop online?
+    options:
+      - text: Never
+      - text: Monthly
+        qualifies: true
+      - text: Weekly
+        qualifies: true
+rejection_message: You did not meet the research criteria for this study.
+"""
+
+
+def test_validate_with_screening(runner, tmp_path):
+    yaml_file = tmp_path / "usertest.yaml"
+    yaml_file.write_text(SCREENING_YAML)
+
+    result = runner.invoke(app, ["usertests", "validate", str(yaml_file)])
+
+    assert result.exit_code == 0
+    assert "Valid user test config" in result.output
+
+
+def test_validate_screening_question_needs_two_options(runner, tmp_path):
+    yaml_file = tmp_path / "usertest.yaml"
+    yaml_file.write_text(
+        VALID_USERTEST_YAML
+        + "screening_questions:\n"
+        + "  - text: Only one way to answer?\n"
+        + "    options:\n"
+        + "      - text: \"Yes\"\n"
+        + "        qualifies: true\n"
+    )
+
+    result = runner.invoke(app, ["usertests", "validate", str(yaml_file)])
+
+    assert result.exit_code == 1
+    assert "'options' must list at least 2 options" in result.output
+
+
+def test_validate_screening_question_needs_a_qualifying_option(runner, tmp_path):
+    yaml_file = tmp_path / "usertest.yaml"
+    yaml_file.write_text(
+        VALID_USERTEST_YAML
+        + "screening_questions:\n"
+        + "  - text: Nobody can pass this one\n"
+        + "    options:\n"
+        + "      - text: A\n"
+        + "      - text: B\n"
+    )
+
+    result = runner.invoke(app, ["usertests", "validate", str(yaml_file)])
+
+    assert result.exit_code == 1
+    assert "needs at least one option with 'qualifies: true'" in result.output
+
+
+def test_validate_screening_option_qualifies_must_be_bool(runner, tmp_path):
+    yaml_file = tmp_path / "usertest.yaml"
+    yaml_file.write_text(
+        VALID_USERTEST_YAML
+        + "screening_questions:\n"
+        + "  - text: Q\n"
+        + "    options:\n"
+        + "      - text: A\n"
+        + "        qualifies: yep\n"
+        + "      - text: B\n"
+        + "        qualifies: true\n"
+    )
+
+    result = runner.invoke(app, ["usertests", "validate", str(yaml_file)])
+
+    assert result.exit_code == 1
+    assert "'qualifies' must be true or false" in result.output
+
+
 def test_example(runner):
     result = runner.invoke(app, ["usertests", "example"])
 
@@ -300,6 +381,20 @@ def test_example(runner):
     assert "steps:" in result.output
     assert "prototype" in result.output
     assert "screen" in result.output
+    assert "screening_questions:" in result.output
+    assert "rejection_message:" in result.output
+
+
+def test_example_validates(runner, tmp_path):
+    from podojo_cli.commands.usertests import EXAMPLE_YAML
+
+    yaml_file = tmp_path / "example.yaml"
+    yaml_file.write_text(EXAMPLE_YAML)
+
+    result = runner.invoke(app, ["usertests", "validate", str(yaml_file)])
+
+    assert result.exit_code == 0
+    assert "Valid user test config" in result.output
 
 
 def test_snippet(runner):

{podojo_cli-1.5.2 → podojo_cli-1.7.0}/uv.lock

@@ -369,7 +369,7 @@ wheels = [
 
 [[package]]
 name = "podojo-cli"
-version = "1.5.1"
+version = "1.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },