docs: clarify intent examples in docstrings and format code

wangauone · wangauone · commit 7ead11789f7b · 2026-01-23T16:08:26.000-08:00
- Update docstrings for `generate_templates` and `generate_facets` to show explicit examples for optional intent
- Format code with `ruff`
diff --git a/mcp/facet/facet_generator.py b/mcp/facet/facet_generator.py
@@ -31,12 +31,14 @@ async def generate_facets_from_items(
         facet_text = item.get("sql_snippet", item.get("facet"))
         if not facet_text:
             # Skip malformed items or raise error? For now, we might want to be robust
-            # But if both are missing, we might have an issue. 
+            # But if both are missing, we might have an issue.
             # Let's assume validation happened or we just let it fail later if None.
             # Actually, to be safe and avoid KeyError if strict logic elsewhere:
             raise KeyError("Each item must have a 'sql_snippet' or 'facet' key.")
 
-        intent = item.get("intent", question)  # Use provided intent or fallback to question
+        intent = item.get(
+            "intent", question
+        )  # Use provided intent or fallback to question
 
         # 1. Extract value phrases from the question
         phrases = await parameterizer.extract_value_phrases(nl_query=question)
diff --git a/mcp/main.py b/mcp/main.py
@@ -48,9 +48,10 @@ async def generate_templates(
     Generates final templates from a list of user-approved question, SQL statement, and optional intent.
 
     Args:
-        template_inputs_json: A JSON string representing a list of dictionaries,
+        template_inputs_json: A JSON string representing a list of dictionaries (template inputs),
                              where each dictionary has "question", "sql", and optional "intent" keys.
-                             Example: '[{"question": "...", "sql": "...", "intent": "..."}]'
+                             Example (with intent): '[{"question": "How many users?", "sql": "SELECT count(*) FROM users", "intent": "Count total users"}]'
+                             Example (default intent): '[{"question": "List all items", "sql": "SELECT * FROM items"}]'
         sql_dialect: The SQL dialect to use for parameterization. Accepted
                    values are 'postgresql', 'mysql', or 'googlesql'.
 
@@ -70,9 +71,10 @@ async def generate_facets(
     Generates final facets from a list of user-approved question, SQL snippet, and optional intent.
 
     Args:
-        facet_inputs_json: A JSON string representing a list of dictionaries,
+        facet_inputs_json: A JSON string representing a list of dictionaries (facet inputs),
                              where each dictionary has "question", "sql_snippet", and optional "intent".
-                             Example: '[{"question": "...", "sql_snippet": "...", "intent": "..."}]'
+                             Example (with intent): '[{"question": "expensive items", "sql_snippet": "price > 1000", "intent": "Filter by high price"}]'
+                             Example (default intent): '[{"question": "active users", "sql_snippet": "status = 'active'"}]'
         sql_dialect: The SQL dialect to use for parameterization. Accepted
                    values are 'postgresql', 'mysql', or 'googlesql'.
 
diff --git a/mcp/model/context.py b/mcp/model/context.py
@@ -68,4 +68,3 @@ class ContextSet(BaseModel):
         description="A list of SQL facets.",
         validation_alias=AliasChoices("facets", "fragments"),
     )
-
diff --git a/mcp/template/template_generator.py b/mcp/template/template_generator.py
@@ -28,7 +28,9 @@ async def generate_templates_from_items(
     for item in item_list:
         question = item["question"]
         sql = item["sql"]
-        intent = item.get("intent", question)  # Use provided intent or fallback to question
+        intent = item.get(
+            "intent", question
+        )  # Use provided intent or fallback to question
 
         # 1. Extract value phrases from the question
         phrases = await parameterizer.extract_value_phrases(nl_query=question)
diff --git a/mcp/tests/facet/facet_generator_test.py b/mcp/tests/facet/facet_generator_test.py
@@ -18,7 +18,6 @@ async def test_generate_facets_from_items_simple():
         with patch(
             "common.parameterizer.parameterize_sql_and_intent"
         ) as mock_parameterize_sql_and_intent:
-
             mock_extract_value_phrases.return_value = mock_phrases
             mock_parameterize_sql_and_intent.return_value = {
                 "sql": "city = $1",
@@ -61,7 +60,6 @@ async def test_generate_facets_from_items_multiple_phrases():
         with patch(
             "common.parameterizer.parameterize_sql_and_intent"
         ) as mock_parameterize_sql_and_intent:
-
             mock_extract_value_phrases.return_value = mock_phrases
             mock_parameterize_sql_and_intent.return_value = {
                 "sql": "name = $1 AND city = $2",
@@ -76,16 +74,13 @@ async def test_generate_facets_from_items_multiple_phrases():
             facet = result_context_set.facets[0]
             assert facet.sql_snippet == "name = 'John Doe' AND city = 'New York'"
             assert facet.intent == "Find users named John Doe in New York"
-            assert (
-                facet.manifest == "Find users named a given person in a given city"
-            )
+            assert facet.manifest == "Find users named a given person in a given city"
             assert (
                 facet.parameterized.parameterized_sql_snippet
                 == "name = $1 AND city = $2"
             )
             assert (
-                facet.parameterized.parameterized_intent
-                == "Find users named $1 in $2"
+                facet.parameterized.parameterized_intent == "Find users named $1 in $2"
             )
 
             mock_extract_value_phrases.assert_called_once_with(
@@ -96,9 +91,7 @@ async def test_generate_facets_from_items_multiple_phrases():
 
 @pytest.mark.asyncio
 async def test_generate_facets_from_items_empty_phrases():
-    facet_inputs_json = json.dumps(
-        [{"question": "List all users", "facet": "TRUE"}]
-    )
+    facet_inputs_json = json.dumps([{"question": "List all users", "facet": "TRUE"}])
     mock_phrases = {}
 
     with patch(
@@ -107,7 +100,6 @@ async def test_generate_facets_from_items_empty_phrases():
         with patch(
             "common.parameterizer.parameterize_sql_and_intent"
         ) as mock_parameterize_sql_and_intent:
-
             mock_extract_value_phrases.return_value = mock_phrases
             mock_parameterize_sql_and_intent.return_value = {
                 "sql": "TRUE",
@@ -157,7 +149,7 @@ async def test_generate_facets_from_items_with_explicit_intent():
             {
                 "question": "luxury items",
                 "facet": "description LIKE '%luxury%'",
-                "intent": "Filter by luxury description"
+                "intent": "Filter by luxury description",
             }
         ]
     )
@@ -169,7 +161,6 @@ async def test_generate_facets_from_items_with_explicit_intent():
         with patch(
             "common.parameterizer.parameterize_sql_and_intent"
         ) as mock_parameterize_sql_and_intent:
-
             mock_extract_value_phrases.return_value = mock_phrases
             mock_parameterize_sql_and_intent.return_value = {
                 "sql": "description LIKE '%luxury%'",
@@ -183,7 +174,7 @@ async def test_generate_facets_from_items_with_explicit_intent():
             assert len(result_context_set.facets) == 1
             facet = result_context_set.facets[0]
             assert facet.intent == "Filter by luxury description"
-            
+
             # Verify parameterizer was called with explicit intent
             # args match: phrases, facet_text, intent, db_dialect
             args, _ = mock_parameterize_sql_and_intent.call_args
@@ -198,7 +189,7 @@ async def test_generate_facets_from_items_with_sql_snippet_key():
             {
                 "question": "expensive items",
                 "sql_snippet": "price > 1000",
-                "intent": "Filter by expensive items"
+                "intent": "Filter by expensive items",
             }
         ]
     )
@@ -210,7 +201,6 @@ async def test_generate_facets_from_items_with_sql_snippet_key():
         with patch(
             "common.parameterizer.parameterize_sql_and_intent"
         ) as mock_parameterize_sql_and_intent:
-
             mock_extract_value_phrases.return_value = mock_phrases
             mock_parameterize_sql_and_intent.return_value = {
                 "sql": "price > 1000",
diff --git a/mcp/tests/main_test.py b/mcp/tests/main_test.py
@@ -5,21 +5,25 @@
 from main import attach_context_set
 from model.context import ContextSet
 
+
 @pytest.fixture
 def clean_context_set_json():
-    return json.dumps({
-        "facets": [
-            {
-                "sql_snippet": "new_snippet",
-                "intent": "new_intent",
-                "manifest": "new_manifest",
-                "parameterized": {
-                    "parameterized_sql_snippet": "p_new_snippet",
-                    "parameterized_intent": "p_new_intent"
+    return json.dumps(
+        {
+            "facets": [
+                {
+                    "sql_snippet": "new_snippet",
+                    "intent": "new_intent",
+                    "manifest": "new_manifest",
+                    "parameterized": {
+                        "parameterized_sql_snippet": "p_new_snippet",
+                        "parameterized_intent": "p_new_intent",
+                    },
                 }
-            }
-        ]
-    })
+            ]
+        }
+    )
+
 
 def test_attach_context_set_legacy_compatibility(tmp_path, clean_context_set_json):
     """Test attaching new context to a file with legacy 'fragment' and 'fragments' keys."""
@@ -32,32 +36,35 @@ def test_attach_context_set_legacy_compatibility(tmp_path, clean_context_set_jso
                 "manifest": "old_manifest",
                 "parameterized": {
                     "parameterized_fragment": "p_old_snippet",
-                    "parameterized_intent": "p_old_intent"
-                }
+                    "parameterized_intent": "p_old_intent",
+                },
             }
         ]
     }
     legacy_file.write_text(json.dumps(legacy_content))
 
     # Call the tool
-    attach_context_set.fn(context_set_json=clean_context_set_json, file_path=str(legacy_file))
+    attach_context_set.fn(
+        context_set_json=clean_context_set_json, file_path=str(legacy_file)
+    )
 
     # Verify the file was updated and migrated
     updated_content = json.loads(legacy_file.read_text())
-    
+
     # Check that legacy content was correctly parsed and migrated to 'facets' and 'sql_snippet'
     assert "facets" in updated_content
     assert "fragments" not in updated_content
     assert len(updated_content["facets"]) == 2
-    
+
     # Check old item (migrated)
     old_item = updated_content["facets"][0]
     assert old_item["sql_snippet"] == "old_snippet"
-    
+
     # Check new item
     new_item = updated_content["facets"][1]
     assert new_item["sql_snippet"] == "new_snippet"
 
+
 def test_attach_context_set_standard(tmp_path, clean_context_set_json):
     """Test attaching new context to a file with standard 'facets' key."""
     standard_file = tmp_path / "standard_context.json"
@@ -69,27 +76,29 @@ def test_attach_context_set_standard(tmp_path, clean_context_set_json):
                 "manifest": "existing_manifest",
                 "parameterized": {
                     "parameterized_sql_snippet": "p_existing_snippet",
-                    "parameterized_intent": "p_existing_intent"
-                }
+                    "parameterized_intent": "p_existing_intent",
+                },
             }
         ]
     }
     standard_file.write_text(json.dumps(standard_content))
 
     # Call the tool
-    attach_context_set.fn(context_set_json=clean_context_set_json, file_path=str(standard_file))
+    attach_context_set.fn(
+        context_set_json=clean_context_set_json, file_path=str(standard_file)
+    )
 
     # Verify the file was updated
     updated_content = json.loads(standard_file.read_text())
-    
+
     assert "facets" in updated_content
     assert "fragments" not in updated_content
     assert len(updated_content["facets"]) == 2
-    
+
     # Check existing item
     existing_item = updated_content["facets"][0]
     assert existing_item["sql_snippet"] == "existing_snippet"
-    
+
     # Check new item
     new_item = updated_content["facets"][1]
     assert new_item["sql_snippet"] == "new_snippet"
diff --git a/mcp/tests/template/template_generator_test.py b/mcp/tests/template/template_generator_test.py
@@ -17,12 +17,14 @@ async def test_generate_templates_from_items_simple():
     )
     mock_phrases = {"New York": ["city"]}
 
-    with patch(
-        "common.parameterizer.extract_value_phrases", new_callable=AsyncMock
-    ) as mock_extract_value_phrases, patch(
-        "common.parameterizer.parameterize_sql_and_intent"
-    ) as mock_parameterize_sql_and_intent:
-
+    with (
+        patch(
+            "common.parameterizer.extract_value_phrases", new_callable=AsyncMock
+        ) as mock_extract_value_phrases,
+        patch(
+            "common.parameterizer.parameterize_sql_and_intent"
+        ) as mock_parameterize_sql_and_intent,
+    ):
         mock_extract_value_phrases.return_value = mock_phrases
         mock_parameterize_sql_and_intent.return_value = {
             "sql": "SELECT count(*) FROM users WHERE city = $1",
@@ -70,25 +72,29 @@ async def test_generate_templates_from_items_invalid_dialect():
     )
     assert "error" in result_json
     assert "Invalid database dialect specified" in result_json
+
+
 @pytest.mark.asyncio
 async def test_generate_templates_from_items_with_explicit_intent():
     template_inputs_json = json.dumps(
         [
             {
                 "question": "How many users?",
                 "sql": "SELECT count(*) FROM users",
-                "intent": "Count all users"
+                "intent": "Count all users",
             }
         ]
     )
     mock_phrases = {}
 
-    with patch(
-        "common.parameterizer.extract_value_phrases", new_callable=AsyncMock
-    ) as mock_extract_value_phrases, patch(
-        "common.parameterizer.parameterize_sql_and_intent"
-    ) as mock_parameterize_sql_and_intent:
-
+    with (
+        patch(
+            "common.parameterizer.extract_value_phrases", new_callable=AsyncMock
+        ) as mock_extract_value_phrases,
+        patch(
+            "common.parameterizer.parameterize_sql_and_intent"
+        ) as mock_parameterize_sql_and_intent,
+    ):
         mock_extract_value_phrases.return_value = mock_phrases
         mock_parameterize_sql_and_intent.return_value = {
             "sql": "SELECT count(*) FROM users",
@@ -102,7 +108,7 @@ async def test_generate_templates_from_items_with_explicit_intent():
         assert len(result_context_set.templates) == 1
         template = result_context_set.templates[0]
         assert template.intent == "Count all users"
-        
+
         # Verify parameterizer was called with explicit intent
         # args match: phrases, sql, intent, db_dialect
         args, _ = mock_parameterize_sql_and_intent.call_args

Original file line number	Diff line number	Diff line change
`@@ -68,4 +68,3 @@ class ContextSet(BaseModel):`
`68`	`68`	`description="A list of SQL facets.",`
`69`	`69`	`validation_alias=AliasChoices("facets", "fragments"),`
`70`	`70`	`)`
`71`		`-`