clinical-quality-agent

name	clinical-quality-agent
description	Install or teardown the Clinical Quality and Patient Safety Agent solution. Usage: $sf-hcls-solutions:clinical-quality-agent | $sf-hcls-solutions:clinical-quality-agent teardown Triggers: clinical, quality, patient safety, healthcare, HAI, mortality, cortex agent.
tools	["snowflake_sql_execute","snowflake_object_search","Bash","Read","Glob","Grep","WebFetch"]

Clinical Quality and Patient Safety Agent

Parse the action from $ARGUMENTS:

• If $ARGUMENTS is "install" or empty → run Install flow
• If $ARGUMENTS is "teardown" → run Teardown flow
• Otherwise → show usage help

Overview

• Industry: Healthcare & Life Sciences
• Database: SF_SOLUTIONS
• Schema: CLINICAL_QUALITY_SAFETY
• Features: Cortex Agent, Cortex Analyst, Semantic Model, Snowflake CoWork
• Role Required: ACCOUNTADMIN
• Optional Marketplace Dataset: PubMed Biomedical Research Corpus — can be added after install (see NEXT_ACTIONS.md)

Install

1. Locate the sf-hcls-solutions repository:

   • Check ~/project/sf-hcls-solutions/
   • Check current working directory
   • If not found: git clone https://github.com/Snowflake-Labs/sf-hcls-solutions.git /tmp/sf-hcls-solutions

2. Read solutions/clinical-quality-agent/manifest.json.

3. Present the installation plan:

   Solution: Clinical Quality and Patient Safety Agent v1.0.0
   Industry: Healthcare & Life Sciences
   Database: SF_SOLUTIONS
   Schema:   CLINICAL_QUALITY_SAFETY
   Role:     ACCOUNTADMIN
   
   What will be created:
     - 8 clinical quality tables (75K patients with realistic data)
     - Semantic model for Cortex Analyst (text-to-SQL)
     - Cortex Agent with Analyst + Email tools
     - PubMed Search tool can be added after install (see NEXT_ACTIONS.md)
     - Accessible via Snowflake Intelligence UI
   
   Optional prerequisite:
     - PubMed Biomedical Research Corpus (free Marketplace dataset)
     - Enables medical literature search (38M+ articles)
     - Without it, the Agent still works for analytics but cannot search research literature
   
   Proceed with installation?
   

4. Wait for user confirmation.

5. Read solutions/clinical-quality-agent/scripts/setup.sql and execute it.

   CRITICAL SESSION CONSTRAINT: This script uses SET session variables (e.g., $num_patients, $mortality_multiplier) that the data generation INSERT statements depend on. These variables MUST persist within the same session.

   Execution strategy:

   • Lines 1-208 (schema/table creation): Execute statement by statement — these are independent DDL.
   • Lines 209-1963 (SET variables + data generation): Execute as a SINGLE call using snowflake_sql_execute with all statements concatenated. The SET variables, TRUNCATE, and INSERT...GENERATOR statements MUST run in one session, otherwise the variables are lost and tables will be empty.
     • Use timeout_seconds: 1200 (data generation takes ~2-5 min on LARGE warehouse)
   • Lines 1964+ (stage creation only): Execute statement by statement. This creates the SEMANTIC_MODEL_STAGE.

   Log progress after each major section.

6. Upload semantic model YAML (CRITICAL — agent won't work without this):

   Step 6a — Locate the YAML file:

   • solutions/clinical-quality-agent/scripts/semantic_model.yaml

   Step 6b — Upload to stage via PUT:

   PUT file://<repo_path>/solutions/clinical-quality-agent/scripts/semantic_model.yaml
       @SF_SOLUTIONS.CLINICAL_QUALITY_SAFETY.SEMANTIC_MODEL_STAGE
       AUTO_COMPRESS=FALSE OVERWRITE=TRUE;
   

   Replace <repo_path> with the actual absolute path to the repository on disk.

   If PUT fails, write the file contents to /tmp/semantic_model.yaml first, then PUT that:

   PUT file:///tmp/semantic_model.yaml @SF_SOLUTIONS.CLINICAL_QUALITY_SAFETY.SEMANTIC_MODEL_STAGE AUTO_COMPRESS=FALSE OVERWRITE=TRUE;
   

   Step 6c — Verify the file is on stage:

   LIST @SF_SOLUTIONS.CLINICAL_QUALITY_SAFETY.SEMANTIC_MODEL_STAGE;
   

   You MUST see semantic_model.yaml. If not, retry PUT before proceeding.

   Step 6d — Execute solutions/clinical-quality-agent/scripts/deploy_agent.sql: This creates the Cortex Agent. Execute it as a SINGLE call (the agent spec is one statement):

   -- Execute full deploy_agent.sql contents as one statement
   

   Step 6e — Verify agent was created:

   SHOW AGENTS  SCHEMA SF_SOLUTIONS.CLINICAL_QUALITY_SAFETY;
   

7. Verify table data:

   SELECT TABLE_SCHEMA, TABLE_NAME, ROW_COUNT
   FROM SF_SOLUTIONS.INFORMATION_SCHEMA.TABLES
   WHERE TABLE_SCHEMA = 'CLINICAL_QUALITY_SAFETY'
   ORDER BY TABLE_NAME;
   

8. [MANDATORY — DO NOT SKIP] Show the Snowflake Intelligence Agent URL. Execute this query:

   SELECT 'https://app.snowflake.com/'
       || LOWER(CURRENT_ORGANIZATION_NAME()) || '/' || LOWER(CURRENT_ACCOUNT_NAME())
       || '/#/agents/database/SF_SOLUTIONS/schema/CLINICAL_QUALITY_SAFETY/agent/CLINICAL_QUALITY_SAFETY_AGENT/details' AS AGENT_URL;
   

   Display it to the user:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Cortex Agent:
   <paste the full URL here>
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   

   This step is NON-OPTIONAL. The user must always see the Agent URL after install.

9. Show final summary:

   Installation complete: Clinical Quality and Patient Safety Agent v1.0.0
   
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Cortex Agent:
   <the URL from step 9>
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
   Next Actions:
   1. Open the Cortex Agent URL above in Snowflake CoWork
   2. Try: "How many patients died in the last year?"
   3. Try: "Show me catheter infections that resulted in death"
   4. Add PubMed medical literature search (see NEXT_ACTIONS.md)
   
   Teardown: $sf-hcls-solutions:clinical-quality-agent teardown
   

Teardown

If $ARGUMENTS is "teardown":

1. Confirm with user: "This will drop the CLINICAL_QUALITY_SAFETY schema and the Cortex Agent. Proceed?"
2. Read and execute solutions/clinical-quality-agent/scripts/teardown.sql statement by statement.
3. Confirm: "Clinical Quality and Patient Safety Agent removed."

Next Actions

If the user asks "what next?", "what can I do?", or "how to customize":

Read and present the content from NEXT_ACTIONS.md in solutions/clinical-quality-agent/. Present the relevant section based on user intent:

• Just exploring → Quick Exploration section
• Wants to use own data → Customize with Your Data section
• Wants to add tools → Extend the Agent section
• Ready for production → Production Deployment section

Usage Help

Usage:
  $sf-hcls-solutions:clinical-quality-agent           — Install the solution
  $sf-hcls-solutions:clinical-quality-agent teardown   — Remove the solution