google-cloud-db-context-engineering 0.7.4__tar.gz → 0.8.0__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.
- {google_cloud_db_context_engineering-0.7.4/src/google_cloud_db_context_engineering.egg-info → google_cloud_db_context_engineering-0.8.0}/PKG-INFO +12 -3
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/README.md +11 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/pyproject.toml +3 -5
- google_cloud_db_context_engineering-0.8.0/src/google/cloud/db_context_enrichment/common/context_mutator.py +205 -0
- google_cloud_db_context_engineering-0.8.0/src/google/cloud/db_context_enrichment/common/context_validator.py +562 -0
- google_cloud_db_context_engineering-0.8.0/src/google/cloud/db_context_enrichment/dataset/dataset_splitter.py +446 -0
- google_cloud_db_context_engineering-0.8.0/src/google/cloud/db_context_enrichment/evaluate/db_generators/bigquery.py +90 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/bigtable.py +7 -4
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/firestore.py +5 -1
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/evaluate_generator.py +82 -15
- google_cloud_db_context_engineering-0.8.0/src/google/cloud/db_context_enrichment/evaluate/generalizability.py +420 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/result_reader.py +20 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/main.py +120 -123
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/model/context.py +1 -1
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0/src/google_cloud_db_context_engineering.egg-info}/PKG-INFO +12 -3
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google_cloud_db_context_engineering.egg-info/SOURCES.txt +3 -1
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google_cloud_db_context_engineering.egg-info/requires.txt +0 -2
- google_cloud_db_context_engineering-0.7.4/src/google/cloud/db_context_enrichment/common/context_mutator.py +0 -132
- google_cloud_db_context_engineering-0.7.4/src/google/cloud/db_context_enrichment/common/context_store_client.py +0 -190
- google_cloud_db_context_engineering-0.7.4/src/google/cloud/db_context_enrichment/common/context_validator.py +0 -188
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/LICENSE +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/setup.cfg +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/__init__.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/common/__init__.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/common/config.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/dataset/__init__.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/dataset/dataset_generator.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/__init__.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/__init__.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/alloydb.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/base.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/custom.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/mysql.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/postgres.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/evaluate/db_generators/spanner.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google/cloud/db_context_enrichment/model/__init__.py +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google_cloud_db_context_engineering.egg-info/dependency_links.txt +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/src/google_cloud_db_context_engineering.egg-info/entry_points.txt +0 -0
- {google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/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.
|
|
3
|
+
Version: 0.8.0
|
|
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
|
{google_cloud_db_context_engineering-0.7.4 → google_cloud_db_context_engineering-0.8.0}/README.md
RENAMED
|
@@ -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.
|
|
3
|
+
version = "0.8.0"
|
|
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]
|
|
@@ -45,8 +43,8 @@ dev = [
|
|
|
45
43
|
]
|
|
46
44
|
|
|
47
45
|
[tool.db-context-engineering]
|
|
48
|
-
toolbox_version = "1.
|
|
49
|
-
evalbench_version = "1.
|
|
46
|
+
toolbox_version = "1.14.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
|