Verify dataset requirements

knowledge_base/agent.md

@@ -357,6 +357,15 @@ These datasets follow CDISC standards and include standard variables like:
 - Suitable for questionnaire scores, lab values, etc.
 - AVAL should contain numeric continuous values
 - Good alternative to GEE when data is continuous
+- **Works with**: ADLB (lab values), ADVS (vitals), ADQS (questionnaires), or any BDS dataset with continuous AVAL
+
+### tm_t_ancova (ANCOVA)
+
+**Data requirements**:
+- Requires continuous outcome variable (AVAL)
+- Needs covariates for adjustment
+- Visit variable (AVISIT) for repeated measures
+- **Works with**: ADLB (lab efficacy endpoints like glucose, HbA1c), ADVS (vital signs), ADQS (questionnaire scores), or any BDS dataset with continuous AVAL
 
 ### tm_g_forest_tte
 
@@ -549,6 +558,19 @@ When providing R code or guidance to users:
 9. Agent: Verify configuration variables (AVAL, USUBJID, AVISIT) exist in ADQS
 10. Agent: Provide code with appropriate variable configuration
 
+### Example 6: Using Statistical Modules with Lab Data (ADLB)
+
+1. User: "I want to analyze glucose levels over time with ANCOVA"
+2. Agent: Use `tealflow_discover_datasets` to find available datasets
+3. Agent: User has ADSL and ADLB datasets
+4. Agent: Use `tealflow_get_dataset_info` on ADLB
+5. Agent: Verify ADLB has required variables: PARAMCD (includes glucose), AVAL (continuous lab values), AVISIT
+6. Agent: Use `tealflow_check_dataset_requirements` for tm_t_ancova
+7. Agent: Explain: "tm_t_ancova requires BDS_CONTINUOUS dataset. Your ADLB matches - it has continuous AVAL for lab values."
+8. Agent: Generate tm_t_ancova code configured for ADLB
+9. Agent: Include parameter filter for glucose: `paramcd = choices_selected(value_choices(ADLB, "PARAMCD"), "GLUC")`
+10. Agent: User successfully analyzes glucose efficacy with ANCOVA
+
 ### Example 5: Working with SAP
 
 1. User: "I have a Statistical Analysis Plan (SAP), help me implement it"

knowledge_base/teal_modules_clinical_modules_requirements.json

@@ -17,7 +17,8 @@
     "modules": {
       "tm_g_ci": {
         "description": "Confidence Interval Plot",
-        "required_datasets": ["ADSL", "ADLB"],
+        "required_datasets": ["ADSL", "BDS_DATASET"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {
@@ -156,7 +157,8 @@
       },
       "tm_g_ipp": {
         "description": "Individual Patient Plot",
-        "required_datasets": ["ADSL", "ADLB"],
+        "required_datasets": ["ADSL", "BDS_DATASET"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {
@@ -240,7 +242,8 @@
       },
       "tm_g_lineplot": {
         "description": "Line Plot",
-        "required_datasets": ["ADSL", "ADLB"],
+        "required_datasets": ["ADSL", "BDS_DATASET"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {
@@ -456,7 +459,8 @@
       },
       "tm_t_ancova": {
         "description": "ANCOVA Table",
-        "required_datasets": ["ADSL", "ADQS"],
+        "required_datasets": ["ADSL", "BDS_CONTINUOUS"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {
@@ -1100,7 +1104,8 @@
       },
       "tm_t_summary": {
         "description": "Summary Table",
-        "required_datasets": ["ADSL", "ADLB"],
+        "required_datasets": ["ADSL", "BDS_DATASET"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {
@@ -1134,7 +1139,8 @@
       },
       "tm_t_summary_by": {
         "description": "Summary Table by Group",
-        "required_datasets": ["ADSL", "ADLB"],
+        "required_datasets": ["ADSL", "BDS_DATASET"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {
@@ -1218,7 +1224,9 @@
       },
       "tm_a_gee": {
         "description": "Generalized Estimating Equations",
-        "required_datasets": ["ADSL", "ADQS"],
+        "required_datasets": ["ADSL", "BDS_DATASET"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
+        "notes": "Default regression type is logistic (requires binary AVAL). Can use linear regression for continuous AVAL.",
         "function_parameters": {
           "required_params": {
             "label": {
@@ -1268,7 +1276,8 @@
       },
       "tm_a_mmrm": {
         "description": "Mixed Model for Repeated Measures",
-        "required_datasets": ["ADSL", "ADQS"],
+        "required_datasets": ["ADSL", "BDS_CONTINUOUS"],
+        "typical_datasets": ["ADLB", "ADVS", "ADQS"],
         "function_parameters": {
           "required_params": {
             "label": {

tealflow_mcp.py

@@ -168,20 +168,26 @@ async def list_modules_tool(
     Returns:
         str: List of modules with names, descriptions, and required datasets
 
+        Dataset requirements may include flexible types:
+        - BDS_DATASET: Works with any BDS-structured dataset
+        - BDS_CONTINUOUS: Works with BDS datasets containing continuous data
+        - BDS_BINARY: Works with BDS datasets containing binary outcomes
+        - Specific names (ADSL, ADTTE, ADAE): Require exact dataset match
+
         Markdown format:
             # Teal Modules (Package Name)
 
             ## module_name
             **Description**: Module description
-            **Required Datasets**: ADSL, ADTTE (or "None")
+            **Required Datasets**: ADSL, BDS_CONTINUOUS (or "None")
 
         JSON format:
             {
                 "modules": [
                     {
-                        "name": "tm_g_km",
-                        "description": "Kaplan-Meier Plot",
-                        "required_datasets": ["ADSL", "ADTTE"]
+                        "name": "tm_t_ancova",
+                        "description": "ANCOVA Table",
+                        "required_datasets": ["ADSL", "BDS_CONTINUOUS"]
                     }
                 ],
                 "count": 10
@@ -191,6 +197,10 @@ async def list_modules_tool(
         - List all clinical modules: package="clinical"
         - List graphics modules: category="graphics"
         - Get machine-readable list: response_format="json"
+
+    Note:
+        Use tealflow_get_module_details to see typical datasets and detailed requirements
+        for modules with flexible dataset types.
     """
     params = ListModulesInput(
         package=PackageFilter(package),
@@ -230,13 +240,22 @@ async def get_module_details_tool(
 
         Includes:
         - Module description
-        - Required datasets
+        - Required datasets (may include flexible types: BDS_DATASET, BDS_CONTINUOUS, BDS_BINARY)
+        - Typical datasets (examples of datasets that satisfy flexible requirements)
+        - Dataset requirements (detailed descriptions of what each dataset needs)
+        - Notes (special considerations like regression type for tm_a_gee)
         - Required parameters (no defaults)
         - Optional parameters (with defaults)
         - Parameter types and constraints
         - R help documentation (complete help text from R's help system)
         - Usage examples from R documentation
 
+    Flexible Dataset Types:
+        - BDS_DATASET: Any BDS-structured dataset (ADLB, ADVS, ADQS, ADEG, ADEX)
+        - BDS_CONTINUOUS: BDS dataset with continuous AVAL (typically ADLB, ADVS, ADQS)
+        - BDS_BINARY: BDS dataset with binary AVAL 0/1 (typically ADRS)
+        - Specific names (ADSL, ADTTE, ADAE): Require exact dataset match
+
     Error Handling:
         - Returns error if module not found
         - Suggests similar module names for typos
@@ -246,6 +265,7 @@ async def get_module_details_tool(
     Examples:
         - Get details for KM plot: module_name="tm_g_km"
         - Get Cox regression info: module_name="tm_t_coxreg"
+        - Get ANCOVA details (shows BDS_CONTINUOUS): module_name="tm_t_ancova"
         - Get JSON format: response_format="json"
     """
     params = GetModuleDetailsInput(
@@ -286,9 +306,12 @@ async def search_modules_tool(
         Includes:
         - Analysis category matches (structured)
         - Module names and descriptions
-        - Required datasets
+        - Required datasets (may include flexible types: BDS_DATASET, BDS_CONTINUOUS, BDS_BINARY)
         - Category descriptions
 
+        Note: Dataset requirements may use flexible types. Use tealflow_get_module_details
+        to see typical datasets and tealflow_check_dataset_requirements to verify compatibility.
+
     Predefined Analysis Categories:
         Clinical: survival_analysis, safety_analysis, efficacy_analysis,
                  descriptive_analysis, laboratory_analysis, patient_profiles
@@ -299,6 +322,7 @@ async def search_modules_tool(
         - Find survival analysis modules: analysis_type="survival"
         - Find safety modules: analysis_type="safety"
         - Find visualization modules: analysis_type="visualization"
+        - Find efficacy modules: analysis_type="efficacy"
     """
     params = SearchModulesInput(
         analysis_type=analysis_type,
@@ -319,33 +343,57 @@ async def search_modules_tool(
 )
 async def check_dataset_requirements_tool(
     module_name: str,
-    available_datasets: list[str] | None = None,
+    available_datasets: list[str],
     response_format: str = "markdown"
 ) -> str:
     """
     Check if required datasets are available for a specific module.
 
     This tool validates whether you have all necessary datasets before attempting
     to use a module. It compares the module's dataset requirements against your
-    available datasets and provides clear feedback.
+    available datasets and provides clear feedback. Supports flexible dataset types
+    that match multiple dataset names.
+
+    **IMPORTANT**: Before checking compatibility, use tealflow_get_dataset_info to verify
+    that your datasets have the correct structure and data types for the module:
+    - For BDS_CONTINUOUS modules (ANCOVA, MMRM): Verify AVAL is continuous numeric
+    - For BDS_BINARY modules (logistic GEE): Verify AVAL is binary 0/1
+    - For all BDS modules: Verify required columns exist (PARAMCD, AVISIT, USUBJID, etc.)
 
     Args:
         module_name (str, required): Name of the module to check dataset requirements for.
-        available_datasets (list[str], optional): List of available dataset names. Defaults to Flow's standard datasets: ['ADSL', 'ADTTE', 'ADRS', 'ADQS', 'ADAE'].
+        available_datasets (list[str], required): List of available dataset names (e.g., ['ADSL', 'ADLB', 'ADVS']).
         response_format (str, optional): Output format - 'markdown' for human-readable or 'json' for machine-readable. Defaults to 'markdown'.
 
     Returns:
-        str: Compatibility report with status and missing datasets
+        str: Compatibility report with status and missing/matched datasets
 
         Includes:
         - Compatibility status (compatible/incompatible)
-        - List of required datasets
+        - List of required datasets (with flexible types if applicable)
+        - Matched datasets (which available datasets satisfy flexible requirements)
+        - Typical datasets (examples for flexible types)
+        - Dataset requirements (detailed descriptions)
+        - Notes (special considerations)
         - List of missing datasets (if any)
-        - Suggestions for alternatives
+        - Suggestions for alternatives and guidance
+
+    Flexible Dataset Type Matching:
+        - BDS_DATASET: Matches ADLB, ADVS, ADQS, ADEG, ADEX (any BDS structure)
+        - BDS_CONTINUOUS: Matches ADLB, ADVS, ADQS (BDS with continuous data)
+        - BDS_BINARY: Matches ADRS (BDS with binary outcomes)
+        - Specific names: Must match exactly (ADSL matches ADSL, ADTTE matches ADTTE)
 
     Examples:
-        - Check with defaults: module_name="tm_g_km"
+        - Check KM plot (specific dataset): module_name="tm_g_km", available_datasets=["ADSL", "ADTTE"]
+        - Check ANCOVA (flexible BDS_CONTINUOUS): module_name="tm_t_ancova", available_datasets=["ADSL", "ADLB"]
         - Check with custom datasets: module_name="tm_g_km", available_datasets=["ADSL", "ADTTE", "ADLB"]
+
+    Recommended Workflow:
+        1. Call tealflow_discover_datasets to find available datasets
+        2. Call tealflow_get_dataset_info to verify structure and data types
+        3. Call this tool to check compatibility
+        4. If compatible and data types verified, proceed with module generation
     """
     params = CheckDatasetRequirementsInput(
         module_name=module_name,

tealflow_mcp/models/input_models.py

@@ -84,9 +84,10 @@ class CheckDatasetRequirementsInput(BaseModel):
     module_name: str = Field(
         ..., description="Name of the module to check", min_length=3, max_length=100
     )
-    available_datasets: list[str] | None = Field(
-        default=None,
-        description="List of available datasets (defaults to Flow's standard: ADSL, ADTTE, ADRS, ADQS, ADAE)",
+    available_datasets: list[str] = Field(
+        ...,
+        description="List of available datasets",
+        min_length=1,
     )
     response_format: ResponseFormat = Field(
         default=ResponseFormat.MARKDOWN,

tealflow_mcp/tools/module_details.py

@@ -66,6 +66,24 @@ async def tealflow_get_module_details(params: GetModuleDetailsInput) -> str:
                 lines.append(f"**Required Datasets**: {', '.join(datasets)}")
             else:
                 lines.append("**Required Datasets**: None (works with any data.frame)")
+
+            # Typical datasets (for flexible modules)
+            typical = basic_info.get("typical_datasets", [])
+            if typical:
+                lines.append(f"**Typical Datasets**: {', '.join(typical)}")
+
+            # Dataset requirements details
+            ds_reqs = basic_info.get("dataset_requirements", {})
+            if ds_reqs:
+                lines.append("**Dataset Requirements**:")
+                for ds_name, req_desc in ds_reqs.items():
+                    lines.append(f"  - {ds_name}: {req_desc}")
+
+            # Notes (for special requirements)
+            notes = basic_info.get("notes", "")
+            if notes:
+                lines.append(f"**Note**: {notes}")
+
             lines.append("")
 
             # Function parameters
@@ -117,6 +135,9 @@ async def tealflow_get_module_details(params: GetModuleDetailsInput) -> str:
                     "package": f"teal.modules.{package}",
                     "description": basic_info.get("description", ""),
                     "required_datasets": basic_info.get("required_datasets", []),
+                    "typical_datasets": basic_info.get("typical_datasets", []),
+                    "dataset_requirements": basic_info.get("dataset_requirements", {}),
+                    "notes": basic_info.get("notes", ""),
                     "parameters": module_info.get("function_parameters", {}),
                     "r_help": r_help,
                 },