Merge pull request #14 from GoogleCloudPlatform/refactor/rename-fragment-to-facet

Refactor: Rename ContextSet "fragment" to "facet"

Author: wangauone

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-db-context-enrichment",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "contextFileName": "./mcp/GEMINI.md",
   "mcpServers": {
     "mcp_db_context_enrichment": {
@@ -9,7 +9,7 @@
         "tool",
         "run",
         "--from",
-        "${extensionPath}${/}mcp${/}dist${/}db_context_enrichment-0.1.6-py3-none-any.whl",
+        "${extensionPath}${/}mcp${/}dist${/}db_context_enrichment-0.2.0-py3-none-any.whl",
         "db-context-enrichment"
       ]
     }

mcp/GEMINI.md

@@ -1,6 +1,6 @@
 # Project Overview
 
-This project is a FastMCP server for "DB Context Enrichment." It provides a guided workflow to generate structured, natural language-to-SQL templates and SQL fragments from a user's database schema.
+This project is a FastMCP server for "DB Context Enrichment." It provides a guided workflow to generate structured, natural language-to-SQL templates and SQL facets from a user's database schema.
 
 **Crucially, this server depends on a running MCP Toolbox server to provide the underlying tools for database connection and schema fetching.**
 
@@ -44,7 +44,7 @@ When using the `attach_context_set` tool, the Gemini CLI should **not** read the
 
 ## ContextSet Structure
 
-The `ContextSet` object is a JSON structure that can contain both `templates` and `fragments`. It is the standardized output format for `generate_templates` and `generate_fragments` tools, and the expected input for `save_context_set` and `attach_context_set`.
+The `ContextSet` object is a JSON structure that can contain both `templates` and `facets`. It is the standardized output format for `generate_templates` and `generate_facets` tools, and the expected input for `save_context_set` and `attach_context_set`.
 
 **Example ContextSet JSON:**
 
@@ -62,13 +62,13 @@ The `ContextSet` object is a JSON structure that can contain both `templates` an
       }
     }
   ],
-  "fragments": [
+  "facets": [
     {
-      "fragment": "description LIKE '%luxury%' OR description LIKE '%premium%'",
+      "sql_snippet": "description LIKE '%luxury%' OR description LIKE '%premium%'",
       "intent": "luxury product",
       "manifest": "luxury product",
       "parameterized": {
-        "parameterized_fragment": "description LIKE '%luxury%' OR description LIKE '%premium%'",
+        "parameterized_sql_snippet": "description LIKE '%luxury%' OR description LIKE '%premium%'",
         "parameterized_intent": "luxury product"
       }
     }

mcp/dist/db_context_enrichment-0.1.6-py3-none-any.whl

@@ -3,11 +3,11 @@
 from model import context
 
 
-async def generate_fragments_from_pairs(
+async def generate_facets_from_pairs(
     approved_pairs_json: str, db_dialect_str: str = "postgresql"
 ) -> str:
     """
-    Generates the final, detailed fragments based on user-approved question/SQL fragment pairs.
+    Generates the final, detailed facets based on user-approved question/SQL facet pairs.
     """
     try:
         # Convert the string to the Enum member
@@ -23,11 +23,11 @@ async def generate_fragments_from_pairs(
     except json.JSONDecodeError:
         return '{"error": "Invalid JSON format for approved pairs. Expected a JSON array."}'
 
-    final_fragments = []
+    final_facets = []
 
     for pair in pair_list:
         question = pair["question"]
-        fragment_text = pair["fragment"]
+        facet_text = pair["facet"]
         intent = question  # The intent starts as the original question
 
         # 1. Extract value phrases from the question
@@ -44,20 +44,20 @@ async def generate_fragments_from_pairs(
 
         # 3. Parameterize the SQL and Intent
         parameterized_result = parameterizer.parameterize_sql_and_intent(
-            phrases, fragment_text, intent, db_dialect=db_dialect
+            phrases, facet_text, intent, db_dialect=db_dialect
         )
 
-        # 4. Assemble the final fragment object
-        fragment = context.Fragment(
-            fragment=fragment_text,
+        # 4. Assemble the final facet object
+        facet = context.Facet(
+            sql_snippet=facet_text,
             intent=intent,
             manifest=manifest,
-            parameterized=context.ParameterizedFragment(
-                parameterized_fragment=parameterized_result["sql"],
+            parameterized=context.ParameterizedFacet(
+                parameterized_sql_snippet=parameterized_result["sql"],
                 parameterized_intent=parameterized_result["intent"],
             ),
         )
-        final_fragments.append(fragment)
+        final_facets.append(facet)
 
-    context_set = context.ContextSet(templates=None, fragments=final_fragments)
+    context_set = context.ContextSet(templates=None, facets=final_facets)
     return context_set.model_dump_json(indent=2, exclude_none=True)

mcp/dist/db_context_enrichment-0.1.6.tar.gz

@@ -2,7 +2,7 @@
 from typing import Optional, List
 import textwrap
 from template import question_generator, template_generator
-from fragment import fragment_generator
+from facet import facet_generator
 from model import context
 import datetime
 import os
@@ -64,16 +64,16 @@ async def generate_templates(
 
 
 @mcp.tool
-async def generate_fragments(
+async def generate_facets(
     approved_pairs_json: str, db_engine: Optional[str] = "postgresql"
 ) -> str:
     """
-    Generates final fragments from a list of user-approved question/SQL fragment pairs.
+    Generates final facets from a list of user-approved question/SQL facet pairs.
 
     Args:
         approved_pairs_json: A JSON string representing a list of dictionaries,
-                             where each dictionary has a "question" and a "fragment" key.
-                             Example: '[{"question": "...", "fragment": "..."}]'
+                             where each dictionary has a "question" and a "facet" key.
+                             Example: '[{"question": "...", "facet": "..."}]'
         db_engine: The SQL dialect to use for parameterization. Accepted
                    values are 'postgresql', 'mysql', or 'googlesql'.
 
@@ -82,7 +82,7 @@ async def generate_fragments(
     """
     # Ensure we pass a string, defaulting to 'postgresql' if None is provided.
     dialect = db_engine if db_engine is not None else "postgresql"
-    return await fragment_generator.generate_fragments_from_pairs(
+    return await facet_generator.generate_facets_from_pairs(
         approved_pairs_json, dialect
     )
 
@@ -129,18 +129,18 @@ def attach_context_set(
     Attaches a ContextSet to an existing JSON file.
 
     This tool reads an existing JSON file containing a ContextSet,
-    appends new templates/fragments to it, and writes the updated ContextSet
+    appends new templates/facets to it, and writes the updated ContextSet
     back to the file. Exceptions are propagated to the caller.
 
     Args:
-        context_set_json: The JSON string output from the `generate_templates` or `generate_fragments` tool.
+        context_set_json: The JSON string output from the `generate_templates` or `generate_facets` tool.
         file_path: The **absolute path** to the existing template file.
 
     Returns:
         A confirmation message with the path to the updated file.
     """
 
-    existing_content_dict = {"templates": [], "fragments": []}
+    existing_content_dict = {"templates": [], "facets": []}
     if os.path.getsize(file_path) > 0:
         with open(file_path, "r") as f:
             existing_content_dict = json.load(f)
@@ -154,10 +154,10 @@ def attach_context_set(
     if new_context.templates:
         existing_context.templates.extend(new_context.templates)
 
-    if existing_context.fragments is None:
-        existing_context.fragments = []
-    if new_context.fragments:
-        existing_context.fragments.extend(new_context.fragments)
+    if existing_context.facets is None:
+        existing_context.facets = []
+    if new_context.facets:
+        existing_context.facets.extend(new_context.facets)
 
     with open(file_path, "w") as f:
         json.dump(existing_context.model_dump(), f, indent=2)
@@ -353,37 +353,37 @@ def generate_targeted_templates() -> str:
 
 
 @mcp.prompt
-def generate_targeted_fragments() -> str:
-    """Initiates a guided workflow to generate specific Phrase/SQL fragment pair templates."""
+def generate_targeted_facets() -> str:
+    """Initiates a guided workflow to generate specific Phrase/SQL facet pair templates."""
     return textwrap.dedent(
         """
-        **Workflow for Generating Targeted Phrase/SQL Fragment Pair Templates**
+        **Workflow for Generating Targeted Phrase/SQL Facet Pair Templates**
 
         1.  **User Input Loop:**
-            - Ask the user to provide a natural language phrase and its corresponding SQL fragment.
+            - Ask the user to provide a natural language phrase and its corresponding SQL facet.
             - After capturing the pair, ask the user if they would like to add another one.
             - Continue this loop until the user indicates they have no more pairs to add.
 
         2.  **Review and Confirmation:**
-            - Present the complete list of user-provided Phrase/SQL fragment pairs for confirmation.
+            - Present the complete list of user-provided Phrase/SQL facet pairs for confirmation.
               - **Use the following format for each pair:**
                 **Pair [Number]**
                 **Phrase:** [The natural language phrase]
-                **Fragment:**
+                **Facet:**
                 ```sql
-                [The SQL fragment, properly formatted]
+                [The SQL facet, properly formatted]
                 ```
             - Ask if any modifications are needed. If so, work with the user to refine the pairs.
 
-        3.  **Final Fragment Generation:**
-            - Once approved, call the `generate_fragments` tool with the approved pairs.
-            - **Note:** If the number of approved pairs is very large (e.g., over 50), break the list into smaller chunks and call the `generate_fragments` tool for each chunk.
+        3.  **Final Facet Generation:**
+            - Once approved, call the `generate_facets` tool with the approved pairs.
+            - **Note:** If the number of approved pairs is very large (e.g., over 50), break the list into smaller chunks and call the `generate_facets` tool for each chunk.
             - The tool will return the final JSON content as a string.
 
-        4.  **Save Fragments:**
+        4.  **Save Facets:**
             - Ask the user to choose one of the following options:
               1. Create a new context set file.
-              2. Append fragments to an existing context set file.
+              2. Append facets to an existing context set file.
 
             - **If creating a new file:**
               - You will need to ask the user for the database instance and database name to create the filename.

mcp/dist/db_context_enrichment-0.2.0-py3-none-any.whl

@@ -1,4 +1,4 @@
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, Field
 from typing import List, Optional
 
 
@@ -27,31 +27,45 @@ class Template(BaseModel):
     parameterized: ParameterizedTemplate
 
 
-class ParameterizedFragment(BaseModel):
-    """Defines the parameterized version of a SQL fragment and intent."""
+class ParameterizedFacet(BaseModel):
+    """Defines the parameterized version of a SQL facet and intent."""
 
-    parameterized_fragment: str = Field(
-        ..., description="The SQL fragment with placeholders (eg., )."
+    parameterized_sql_snippet: str = Field(
+        ...,
+        description="The SQL facet with placeholders (eg., ).",
+        validation_alias=AliasChoices(
+            "parameterized_sql_snippet", "parameterized_fragment"
+        ),
     )
     parameterized_intent: str = Field(
         ..., description="The natural language intent with placeholders."
     )
 
 
-class Fragment(BaseModel):
-    """Represents a single, complete fragment."""
+class Facet(BaseModel):
+    """Represents a single, complete facet."""
 
-    fragment: str = Field(..., description="The corresponding, complete SQL fragment.")
+    sql_snippet: str = Field(
+        ...,
+        description="The corresponding, complete SQL facet.",
+        validation_alias=AliasChoices("sql_snippet", "fragment"),
+    )
     intent: str = Field(..., description="The user's specific intent.")
     manifest: str = Field(
-        ..., description="A general description of what the fragment does."
+        ..., description="A general description of what the facet does."
     )
-    parameterized: ParameterizedFragment
+    parameterized: ParameterizedFacet
 
 
 class ContextSet(BaseModel):
-    """A set of templates and fragments."""
+    """A set of templates and facets."""
 
-    templates: Optional[List[Template]] = Field(None, description="A list of complete templates.")
-    fragments: Optional[List[Fragment]] = Field(None, description="A list of SQL fragments.")
+    templates: Optional[List[Template]] = Field(
+        None, description="A list of complete templates."
+    )
+    facets: Optional[List[Facet]] = Field(
+        None,
+        description="A list of SQL facets.",
+        validation_alias=AliasChoices("facets", "fragments"),
+    )