google-cloud-db-context-engineering 0.7.5__tar.gz → 0.8.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. {google_cloud_db_context_engineering-0.7.5/src/google_cloud_db_context_engineering.egg-info → google_cloud_db_context_engineering-0.8.1}/PKG-INFO +12 -3
  2. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/README.md +11 -0
  3. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/pyproject.toml +2 -4
  4. google_cloud_db_context_engineering-0.8.1/src/google/cloud/db_context_enrichment/common/context_mutator.py +205 -0
  5. google_cloud_db_context_engineering-0.8.1/src/google/cloud/db_context_enrichment/common/context_validator.py +562 -0
  6. google_cloud_db_context_engineering-0.8.1/src/google/cloud/db_context_enrichment/dataset/dataset_splitter.py +446 -0
  7. google_cloud_db_context_engineering-0.8.1/src/google/cloud/db_context_enrichment/evaluate/db_generators/bigquery.py +90 -0
  8. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/bigtable.py +7 -4
  9. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/firestore.py +5 -1
  10. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/evaluate_generator.py +82 -15
  11. google_cloud_db_context_engineering-0.8.1/src/google/cloud/db_context_enrichment/evaluate/generalizability.py +420 -0
  12. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/result_reader.py +20 -0
  13. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/main.py +120 -123
  14. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/model/context.py +1 -1
  15. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1/src/google_cloud_db_context_engineering.egg-info}/PKG-INFO +12 -3
  16. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google_cloud_db_context_engineering.egg-info/SOURCES.txt +3 -1
  17. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google_cloud_db_context_engineering.egg-info/requires.txt +0 -2
  18. google_cloud_db_context_engineering-0.7.5/src/google/cloud/db_context_enrichment/common/context_mutator.py +0 -132
  19. google_cloud_db_context_engineering-0.7.5/src/google/cloud/db_context_enrichment/common/context_store_client.py +0 -190
  20. google_cloud_db_context_engineering-0.7.5/src/google/cloud/db_context_enrichment/common/context_validator.py +0 -188
  21. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/LICENSE +0 -0
  22. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/setup.cfg +0 -0
  23. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/__init__.py +0 -0
  24. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/common/__init__.py +0 -0
  25. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/common/config.py +0 -0
  26. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/dataset/__init__.py +0 -0
  27. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/dataset/dataset_generator.py +0 -0
  28. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/__init__.py +0 -0
  29. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/__init__.py +0 -0
  30. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/alloydb.py +0 -0
  31. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/base.py +0 -0
  32. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/custom.py +0 -0
  33. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/mysql.py +0 -0
  34. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/postgres.py +0 -0
  35. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/evaluate/db_generators/spanner.py +0 -0
  36. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google/cloud/db_context_enrichment/model/__init__.py +0 -0
  37. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google_cloud_db_context_engineering.egg-info/dependency_links.txt +0 -0
  38. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google_cloud_db_context_engineering.egg-info/entry_points.txt +0 -0
  39. {google_cloud_db_context_engineering-0.7.5 → google_cloud_db_context_engineering-0.8.1}/src/google_cloud_db_context_engineering.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: google-cloud-db-context-engineering
3
- Version: 0.7.5
3
+ Version: 0.8.1
4
4
  Summary: A FastMCP server for generating natural language to SQL templates from database schemas.
5
5
  Requires-Python: >=3.12
6
6
  Description-Content-Type: text/markdown
@@ -9,8 +9,6 @@ Requires-Dist: fastmcp==3.3.1
9
9
  Requires-Dist: google-genai==1.46.0
10
10
  Requires-Dist: toolbox-core==0.5.2
11
11
  Requires-Dist: google-cloud-geminidataanalytics==0.11.0
12
- Requires-Dist: google-auth==2.41.1
13
- Requires-Dist: requests==2.33.0
14
12
  Provides-Extra: test
15
13
  Requires-Dist: pytest; extra == "test"
16
14
  Requires-Dist: pytest-asyncio; extra == "test"
@@ -49,6 +47,17 @@ Before getting started, prepare your GCP environment, required APIs (Data Analyt
49
47
  Follow the step-by-step setup guide in the official documentation:
50
48
  👉 **Prepare Your Environment**: ([AlloyDB](https://docs.cloud.google.com/gemini/data-agents/querydata/alloydb/build-context-gemini-cli#prepare-your-environment) | Cloud SQL: [PostgreSQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-postgres/build-context-gemini-cli#prepare-your-environment) / [MySQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-mysql/build-context-gemini-cli#prepare-your-environment) | [Spanner](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/build-context-gemini-cli#prepare-your-environment))
51
49
 
50
+ ### Context Set server access
51
+
52
+ The plugin talks to the **Context Set server** (upload / read / delete context sets) through a remote Google-hosted MCP server, authenticated with your Application Default Credentials. Before launching your agent, run:
53
+
54
+ ```bash
55
+ gcloud auth application-default login
56
+ gcloud auth application-default set-quota-project <your-project>
57
+ ```
58
+
59
+ Antigravity and Gemini CLI attach the credentials automatically; Claude Code does so through a small helper script bundled with the plugin (needs `gcloud` on your `PATH`). Details in [docs/development.md](docs/development.md#context-set-server-ctxset).
60
+
52
61
  ---
53
62
 
54
63
  ## Primary Workflow Phases
@@ -31,6 +31,17 @@ Before getting started, prepare your GCP environment, required APIs (Data Analyt
31
31
  Follow the step-by-step setup guide in the official documentation:
32
32
  👉 **Prepare Your Environment**: ([AlloyDB](https://docs.cloud.google.com/gemini/data-agents/querydata/alloydb/build-context-gemini-cli#prepare-your-environment) | Cloud SQL: [PostgreSQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-postgres/build-context-gemini-cli#prepare-your-environment) / [MySQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-mysql/build-context-gemini-cli#prepare-your-environment) | [Spanner](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/build-context-gemini-cli#prepare-your-environment))
33
33
 
34
+ ### Context Set server access
35
+
36
+ The plugin talks to the **Context Set server** (upload / read / delete context sets) through a remote Google-hosted MCP server, authenticated with your Application Default Credentials. Before launching your agent, run:
37
+
38
+ ```bash
39
+ gcloud auth application-default login
40
+ gcloud auth application-default set-quota-project <your-project>
41
+ ```
42
+
43
+ Antigravity and Gemini CLI attach the credentials automatically; Claude Code does so through a small helper script bundled with the plugin (needs `gcloud` on your `PATH`). Details in [docs/development.md](docs/development.md#context-set-server-ctxset).
44
+
34
45
  ---
35
46
 
36
47
  ## Primary Workflow Phases
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "google-cloud-db-context-engineering"
3
- version = "0.7.5"
3
+ version = "0.8.1"
4
4
  description = "A FastMCP server for generating natural language to SQL templates from database schemas."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -10,8 +10,6 @@ dependencies = [
10
10
  "google-genai==1.46.0",
11
11
  "toolbox-core==0.5.2",
12
12
  "google-cloud-geminidataanalytics==0.11.0",
13
- "google-auth==2.41.1",
14
- "requests==2.33.0",
15
13
  ]
16
14
 
17
15
  [project.scripts]
@@ -46,7 +44,7 @@ dev = [
46
44
 
47
45
  [tool.db-context-engineering]
48
46
  toolbox_version = "1.14.0"
49
- evalbench_version = "1.18.0"
47
+ evalbench_version = "1.19.0"
50
48
 
51
49
  [tool.ruff]
52
50
  line-length = 88
@@ -0,0 +1,205 @@
1
+ import json
2
+ import os
3
+ from typing import Any, Literal
4
+
5
+ from pydantic import AliasChoices, BaseModel, ValidationError
6
+ from pydantic.alias_generators import to_snake
7
+
8
+ from google.cloud.db_context_enrichment.common import context_validator
9
+ from google.cloud.db_context_enrichment.model import context
10
+
11
+
12
+ def _build_model_alias_map() -> dict[str, str]:
13
+ """Derives all field aliases dynamically from _BaseContextModel subclasses."""
14
+ aliases: dict[str, str] = {}
15
+ for model_cls in context._BaseContextModel.__subclasses__():
16
+ for field_name, field_info in model_cls.model_fields.items():
17
+ va = field_info.validation_alias
18
+ choices = (
19
+ va.choices if isinstance(va, AliasChoices) else ([va] if va else [])
20
+ )
21
+ for alias in choices:
22
+ if isinstance(alias, str):
23
+ aliases[alias] = field_name
24
+ return aliases
25
+
26
+
27
+ _MODEL_ALIASES = _build_model_alias_map()
28
+
29
+
30
+ def _to_snake_key(key: str) -> str:
31
+ """Normalizes any model alias or camelCase key to canonical snake_case."""
32
+ return _MODEL_ALIASES.get(key, to_snake(key))
33
+
34
+
35
+ def _normalize_item_keys(data: dict[str, Any]) -> dict[str, Any]:
36
+ """Recursively normalizes item dictionary keys to canonical snake_case."""
37
+ normalized: dict[str, Any] = {}
38
+ for k, v in data.items():
39
+ norm_k = _to_snake_key(k)
40
+ if isinstance(v, dict):
41
+ normalized[norm_k] = _normalize_item_keys(v)
42
+ else:
43
+ normalized[norm_k] = v
44
+ return normalized
45
+
46
+
47
+ class Mutation(BaseModel):
48
+ """Defines a strict schema for context modifications."""
49
+
50
+ operation: Literal["add", "delete", "update"]
51
+ type: Literal["template", "facet", "value_search"]
52
+ identifier: dict[str, Any] = {}
53
+ value: dict[str, Any] | None = None
54
+
55
+
56
+ def mutate_context_set(file_path: str, mutations: list[Mutation]) -> None:
57
+ """
58
+ Internal function to mutate (add, delete, update) elements in an existing ContextSet JSON file.
59
+
60
+ The mutations is expected to be a list of Mutation objects.
61
+ Each object specifies an 'operation', 'type', 'identifier' (to route to the correct item for deletes/updates), and 'value' (for adding/updating), for instance:
62
+
63
+ [
64
+ {
65
+ "operation": "add",
66
+ "type": "template",
67
+ "value": {"nl_query": "...", "sql": "...", "intent": "...", "manifest": "...", "parameterized": {...}}
68
+ },
69
+ {
70
+ "operation": "delete",
71
+ "type": "template",
72
+ "identifier": {"nl_query": "What are all users?"}
73
+ },
74
+ {
75
+ "operation": "update",
76
+ "type": "facet",
77
+ "identifier": {"intent": "high price"},
78
+ "value": {"sql_snippet": "price > 2000", "intent": "very high price"}
79
+ }
80
+ ]
81
+ """
82
+
83
+ # 1. Load existing raw JSON (or initialize empty dict) before full Pydantic validation
84
+ # so that broken items in an existing file can be repaired or deleted by mutations.
85
+ if not os.path.exists(file_path) or os.path.getsize(file_path) == 0:
86
+ raw_data: dict[str, Any] = {}
87
+ else:
88
+ try:
89
+ with open(file_path, encoding="utf-8") as f:
90
+ loaded = json.load(f)
91
+ if not isinstance(loaded, dict):
92
+ raise ValueError(
93
+ f"Top-level JSON in {file_path} must be an object, got {type(loaded).__name__}."
94
+ )
95
+ raw_data = {_to_snake_key(k): v for k, v in loaded.items()}
96
+ except (json.JSONDecodeError, OSError) as e:
97
+ raise RuntimeError(f"Error reading JSON from {file_path}: {e}") from e
98
+
99
+ # 2. Model mapping for tracking and validation
100
+ type_to_model = {
101
+ "template": context.Template,
102
+ "facet": context.Facet,
103
+ "value_search": context.ValueSearch,
104
+ }
105
+
106
+ type_to_attr = {
107
+ "template": "templates",
108
+ "facet": "facets",
109
+ "value_search": "value_searches",
110
+ }
111
+
112
+ # 3. Apply mutations
113
+ for i, mut in enumerate(mutations):
114
+ op = mut.operation
115
+ item_type = mut.type
116
+ identifier = _normalize_item_keys(mut.identifier or {})
117
+ value_data = (
118
+ _normalize_item_keys(mut.value)
119
+ if isinstance(mut.value, dict)
120
+ else mut.value
121
+ )
122
+
123
+ if item_type not in type_to_attr:
124
+ continue
125
+
126
+ if op in ("delete", "update") and not identifier:
127
+ raise ValueError(
128
+ f"Validation Error on mutation {i} during '{op}': 'identifier' is required and cannot be empty."
129
+ )
130
+
131
+ attr_name = type_to_attr[item_type]
132
+ model_class = type_to_model[item_type]
133
+
134
+ target_list = raw_data.get(attr_name)
135
+ if not isinstance(target_list, list):
136
+ target_list = []
137
+ raw_data[attr_name] = target_list
138
+
139
+ if op == "add":
140
+ if value_data:
141
+ try:
142
+ new_item = model_class.model_validate(value_data)
143
+ target_list.append(new_item.model_dump(exclude_none=True))
144
+ except ValidationError as e:
145
+ raise ValueError(
146
+ f"Validation Error on mutation {i} during 'add': {e}"
147
+ ) from e
148
+
149
+ elif op == "delete":
150
+ new_list = []
151
+ for raw_item in target_list:
152
+ norm_item = (
153
+ _normalize_item_keys(raw_item) if isinstance(raw_item, dict) else {}
154
+ )
155
+ match = all(norm_item.get(k) == v for k, v in identifier.items())
156
+ if not match:
157
+ new_list.append(raw_item)
158
+ raw_data[attr_name] = new_list
159
+
160
+ elif op == "update":
161
+ for idx, raw_item in enumerate(target_list):
162
+ norm_item = (
163
+ _normalize_item_keys(raw_item) if isinstance(raw_item, dict) else {}
164
+ )
165
+ match = all(norm_item.get(k) == v for k, v in identifier.items())
166
+ if match and value_data:
167
+ updated_dict = {**norm_item, **value_data}
168
+ if isinstance(norm_item.get("parameterized"), dict) and isinstance(
169
+ value_data.get("parameterized"), dict
170
+ ):
171
+ updated_dict["parameterized"] = {
172
+ **norm_item["parameterized"],
173
+ **value_data["parameterized"],
174
+ }
175
+ try:
176
+ updated_item = model_class.model_validate(updated_dict)
177
+ target_list[idx] = updated_item.model_dump(exclude_none=True)
178
+ break # Only update first match
179
+ except ValidationError as e:
180
+ raise ValueError(
181
+ f"Validation Error on mutation {i} during 'update': {e}"
182
+ ) from e
183
+
184
+ # 4. Validate resulting ContextSet (schema + duplicate check) and save
185
+ try:
186
+ context_set = context.ContextSet.model_validate(raw_data)
187
+ except ValidationError as e:
188
+ raise ValueError(
189
+ f"Validation Error loading ContextSet from {file_path}: {e}"
190
+ ) from e
191
+
192
+ normalized_dump = context_set.model_dump(exclude_none=True)
193
+ dup_issues = context_validator._check_duplicates(normalized_dump)
194
+ if dup_issues:
195
+ dup_msgs = "; ".join(issue["message"] for issue in dup_issues)
196
+ raise ValueError(
197
+ f"Duplicate items detected in ContextSet for {file_path}: {dup_msgs}"
198
+ )
199
+
200
+ try:
201
+ os.makedirs(os.path.dirname(os.path.abspath(file_path)), exist_ok=True)
202
+ with open(file_path, "w", encoding="utf-8") as f:
203
+ f.write(context_set.model_dump_json(indent=2, exclude_none=True))
204
+ except OSError as e:
205
+ raise RuntimeError(f"Error saving ContextSet to {file_path}: {e}") from e