vaultkit 0.2.0__tar.gz → 0.3.0__tar.gz

{vaultkit-0.2.0 → vaultkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: VaultKit Python SDK for policy-driven, runtime governed data access
 Author-email: VaultKit <founders@vaultkit.io>
 License: MIT
@@ -74,6 +74,37 @@ print(result.rows)
 
 ---
 
+## Analytical Queries
+
+Aggregate, group, filter on aggregates and sort within a single dataset:
+
+```python
+result = client.execute(
+    dataset="orders",
+    fields=["region"],
+    aggregates=[{"func": "sum", "field": "amount", "alias": "total"}],
+    having=[{"field": "SUM(amount)", "operator": "gt", "value": 1000}],
+    order_by={"column": "total", "direction": "desc"},
+    limit=10,
+    purpose="Quarterly revenue by region",
+)
+# [{"region": "US", "total": 18250}, {"region": "CA", "total": 4100}, ...]
+```
+
+- `aggregates`: `func` is one of `count`, `sum`, `avg`, `min`, `max`; use `field="*"` with `count`.
+- `group_by`: optional. Defaults to `fields`; if given, it must include every entry in `fields`.
+- `having`: needs an aggregate expression such as `SUM(amount)`, not an alias.
+- `order_by`: a field, an aggregate alias or an aggregate expression, `asc` (default) or `desc`.
+- `fields` can be omitted for a single total, e.g. `aggregates=[{"func": "count", "field": "*"}]`.
+
+Policies apply to every field these clauses use. `min`/`max`/`sum`/`avg` over a masked
+field are denied; `count` is allowed. Joins are not supported.
+
+> Requires a VaultKit control plane with intent analytics support. Older control
+> planes ignore these parameters and return ungrouped rows.
+
+---
+
 ## AI Agent Usage
 
 VaultKit provides built-in tools for LLM agents.

{vaultkit-0.2.0 → vaultkit-0.3.0}/README.md

@@ -48,6 +48,37 @@ print(result.rows)
 
 ---
 
+## Analytical Queries
+
+Aggregate, group, filter on aggregates and sort within a single dataset:
+
+```python
+result = client.execute(
+    dataset="orders",
+    fields=["region"],
+    aggregates=[{"func": "sum", "field": "amount", "alias": "total"}],
+    having=[{"field": "SUM(amount)", "operator": "gt", "value": 1000}],
+    order_by={"column": "total", "direction": "desc"},
+    limit=10,
+    purpose="Quarterly revenue by region",
+)
+# [{"region": "US", "total": 18250}, {"region": "CA", "total": 4100}, ...]
+```
+
+- `aggregates`: `func` is one of `count`, `sum`, `avg`, `min`, `max`; use `field="*"` with `count`.
+- `group_by`: optional. Defaults to `fields`; if given, it must include every entry in `fields`.
+- `having`: needs an aggregate expression such as `SUM(amount)`, not an alias.
+- `order_by`: a field, an aggregate alias or an aggregate expression, `asc` (default) or `desc`.
+- `fields` can be omitted for a single total, e.g. `aggregates=[{"func": "count", "field": "*"}]`.
+
+Policies apply to every field these clauses use. `min`/`max`/`sum`/`avg` over a masked
+field are denied; `count` is allowed. Joins are not supported.
+
+> Requires a VaultKit control plane with intent analytics support. Older control
+> planes ignore these parameters and return ungrouped rows.
+
+---
+
 ## AI Agent Usage
 
 VaultKit provides built-in tools for LLM agents.

{vaultkit-0.2.0 → vaultkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vaultkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "VaultKit Python SDK for policy-driven, runtime governed data access"
 authors = [
   { name = "VaultKit", email = "founders@vaultkit.io" }

{vaultkit-0.2.0 → vaultkit-0.3.0}/vaultkit/__init__.py

@@ -53,7 +53,7 @@ from .models import (
 # Optional (nice DX improvement)
 from .tools import ToolBuilder, ToolExecutor
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "VaultKitClient",

{vaultkit-0.2.0 → vaultkit-0.3.0}/vaultkit/client.py

@@ -19,7 +19,11 @@ from vaultkit.models.query_result import QueryResult
 from vaultkit.utils.retry import RetryConfig, with_retries
 from vaultkit.utils.validation import (
     require_str,
+    validate_aggregates,
     validate_filters,
+    validate_group_by,
+    validate_having,
+    validate_order_by,
     validate_limit,
 )
 
@@ -98,6 +102,10 @@ class VaultKitClient:
         fields: Optional[List[str]] = None,
         filters: Optional[List[Dict[str, Any]]] = None,
         limit: Optional[int] = None,
+        aggregates: Optional[List[Dict[str, Any]]] = None,
+        group_by: Optional[List[str]] = None,
+        having: Optional[List[Dict[str, Any]]] = None,
+        order_by: Optional[Dict[str, Any]] = None,
         purpose: Optional[str] = None,
         requester_region: Optional[str] = None,
         requester_clearance: Optional[str] = None,
@@ -106,6 +114,18 @@ class VaultKitClient:
         """
         Submit an intent request and return data — full grant lifecycle internal.
 
+        Analytical queries (single dataset, no joins):
+            aggregates  [{"func": "sum", "field": "amount", "alias": "total"}]
+                        func is one of count, sum, avg, min, max; "*" only with count.
+            group_by    ["region"] — every field in `fields` must be listed when given.
+            having      [{"field": "SUM(amount)", "operator": "gt", "value": 1000}]
+                        field must be an aggregate expression, not an alias.
+            order_by    {"column": "total", "direction": "desc"}
+
+        `fields` may be omitted when `aggregates` is given (e.g. a single COUNT(*)).
+        Requires a control plane that supports intent analytics; older ones
+        ignore these parameters.
+
         Raises:
             DeniedError             Policy rejected. Do not retry.
             ApprovalRequiredError   Needs human approval (request_id attached).
@@ -126,6 +146,10 @@ class VaultKitClient:
             fields=fields,
             filters=filters,
             limit=limit,
+            aggregates=aggregates,
+            group_by=group_by,
+            having=having,
+            order_by=order_by,
             purpose=purpose,
             requester_region=requester_region,
             requester_clearance=requester_clearance,
@@ -214,6 +238,10 @@ class VaultKitClient:
         fields: Optional[List[str]] = None,
         filters: Optional[List[Dict[str, Any]]] = None,
         limit: Optional[int] = None,
+        aggregates: Optional[List[Dict[str, Any]]] = None,
+        group_by: Optional[List[str]] = None,
+        having: Optional[List[Dict[str, Any]]] = None,
+        order_by: Optional[Dict[str, Any]] = None,
         purpose: Optional[str] = None,
         requester_region: Optional[str] = None,
         requester_clearance: Optional[str] = None,
@@ -223,6 +251,10 @@ class VaultKitClient:
         dataset = require_str("dataset", dataset)
         limit = validate_limit(limit)
         filters = validate_filters(filters)
+        aggregates = validate_aggregates(aggregates)
+        group_by = validate_group_by(group_by)
+        having = validate_having(having)
+        order_by = validate_order_by(order_by)
 
         req: Dict[str, Any] = {"dataset": dataset}
         body: Dict[str, Any] = {"request": req}
@@ -235,6 +267,14 @@ class VaultKitClient:
             req["purpose"] = str(purpose)
         if filters is not None:
             req["filters"] = filters
+        if aggregates is not None:
+            req["aggregates"] = aggregates
+        if group_by is not None:
+            req["group_by"] = group_by
+        if having is not None:
+            req["having"] = having
+        if order_by is not None:
+            req["order_by"] = order_by
         if requester_region is not None:
             body["requester_region"] = requester_region
         if requester_clearance is not None:
@@ -248,6 +288,7 @@ class VaultKitClient:
                     "poll": poll,
                     "has_fields": fields is not None,
                     "has_filters": filters is not None,
+                    "has_aggregates": aggregates is not None,
                     "limit": limit,
                 },
             )

{vaultkit-0.2.0 → vaultkit-0.3.0}/vaultkit/tools/definitions.py

@@ -115,6 +115,8 @@ def query_tool_def(
         "description": (
             "Query a governed dataset through VaultKit. Policies are enforced automatically: "
             "sensitive fields may be masked and some datasets require approval before data is returned. "
+            "Supports aggregation (count/sum/avg/min/max), grouping, having and sorting on a single dataset; "
+            "joins are not supported. "
             "Returns data or a pending status if approval is required."
         ),
         "input_schema": {
@@ -143,6 +145,71 @@ def query_tool_def(
                     "maximum": 10000,
                     "description": "Maximum number of rows to return.",
                 },
+                "aggregates": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "func": {"type": "string", "enum": ["count", "sum", "avg", "min", "max"]},
+                            "field": {
+                                "type": "string",
+                                "description": "A field of the selected dataset, or '*' with count.",
+                            },
+                            "alias": {
+                                "type": "string",
+                                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+                                "description": "Name of the result column. Use it in order_by.",
+                            },
+                        },
+                        "required": ["func", "field"],
+                    },
+                    "description": (
+                        "Aggregate functions over the selected dataset. When aggregating, every entry in "
+                        "'fields' is a grouping column. 'fields' may be omitted for a single total.\n\n"
+                        "Example: [{func: 'sum', field: 'amount', alias: 'total'}]\n"
+                        "min/max/sum/avg over masked fields are denied by policy; count is allowed."
+                    ),
+                },
+                "group_by": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Fields to group by. Optional: defaults to 'fields'. If given, it must include "
+                        "every entry in 'fields'."
+                    ),
+                },
+                "having": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "field": {
+                                "type": "string",
+                                "description": "An aggregate expression such as 'SUM(amount)'. Aliases are not allowed here.",
+                            },
+                            "operator": {"type": "string", "enum": ["gt", "lt", "eq", "gte", "lte"]},
+                            "value": {"type": "number"},
+                        },
+                        "required": ["field", "operator", "value"],
+                    },
+                    "description": (
+                        "Filters applied after aggregation. Requires 'aggregates'.\n\n"
+                        "Example: [{field: 'SUM(amount)', operator: 'gt', value: 1000}]"
+                    ),
+                },
+                "order_by": {
+                    "type": "object",
+                    "properties": {
+                        "column": {
+                            "type": "string",
+                            "description": "A field, an aggregate alias, or an aggregate expression.",
+                        },
+                        "direction": {"type": "string", "enum": ["asc", "desc"], "default": "asc"},
+                    },
+                    "required": ["column"],
+                    "description": "Sort order of the results.",
+                },
                 "purpose": {
                     "type": "string",
                     "description": (

{vaultkit-0.2.0 → vaultkit-0.3.0}/vaultkit/tools/executor.py

@@ -105,6 +105,10 @@ class ToolExecutor:
             fields=args.get("fields"),
             filters=args.get("filters"),
             limit=args.get("limit"),
+            aggregates=args.get("aggregates"),
+            group_by=args.get("group_by"),
+            having=args.get("having"),
+            order_by=args.get("order_by"),
             purpose=purpose,
             requester_region=args.get("requester_region") or self._default_requester_region,
         )

{vaultkit-0.2.0 → vaultkit-0.3.0}/vaultkit/utils/validation.py

@@ -85,3 +85,77 @@ def validate_filters(value: Optional[Any]) -> Optional[list]:
             )
 
     return value
+
+
+# Analytical clauses. Only the shape is checked here; the control plane
+# validates functions, fields and operators and returns a clear error.
+
+def _require_list_of_dicts(name: str, value: Optional[Any]) -> Optional[list]:
+    if value is None:
+        return None
+
+    if not isinstance(value, list):
+        raise ValidationError(
+            f"{name} must be a list",
+            context=ErrorContext(raw=value),
+        )
+
+    for item in value:
+        if not isinstance(item, dict):
+            raise ValidationError(
+                f"each {name} entry must be an object",
+                context=ErrorContext(raw=item),
+            )
+
+    return value
+
+
+def validate_aggregates(value: Optional[Any]) -> Optional[list]:
+    value = _require_list_of_dicts("aggregates", value)
+    if value is None:
+        return None
+
+    if not value:
+        raise ValidationError(
+            "aggregates cannot be empty",
+            context=ErrorContext(raw=value),
+        )
+
+    for agg in value:
+        if not agg.get("func") or not agg.get("field"):
+            raise ValidationError(
+                "each aggregate needs 'func' and 'field'",
+                context=ErrorContext(raw=agg),
+            )
+
+    return value
+
+
+def validate_group_by(value: Optional[Any]) -> Optional[list]:
+    if value is None:
+        return None
+
+    if not isinstance(value, list) or not all(isinstance(v, str) and v.strip() for v in value):
+        raise ValidationError(
+            "group_by must be a list of field names",
+            context=ErrorContext(raw=value),
+        )
+
+    return value
+
+
+def validate_having(value: Optional[Any]) -> Optional[list]:
+    return _require_list_of_dicts("having", value)
+
+
+def validate_order_by(value: Optional[Any]) -> Optional[Dict[str, Any]]:
+    if value is None:
+        return None
+
+    if not isinstance(value, dict) or not value.get("column"):
+        raise ValidationError(
+            "order_by must be an object with a 'column'",
+            context=ErrorContext(raw=value),
+        )
+
+    return value

{vaultkit-0.2.0 → vaultkit-0.3.0}/vaultkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: VaultKit Python SDK for policy-driven, runtime governed data access
 Author-email: VaultKit <founders@vaultkit.io>
 License: MIT
@@ -74,6 +74,37 @@ print(result.rows)
 
 ---
 
+## Analytical Queries
+
+Aggregate, group, filter on aggregates and sort within a single dataset:
+
+```python
+result = client.execute(
+    dataset="orders",
+    fields=["region"],
+    aggregates=[{"func": "sum", "field": "amount", "alias": "total"}],
+    having=[{"field": "SUM(amount)", "operator": "gt", "value": 1000}],
+    order_by={"column": "total", "direction": "desc"},
+    limit=10,
+    purpose="Quarterly revenue by region",
+)
+# [{"region": "US", "total": 18250}, {"region": "CA", "total": 4100}, ...]
+```
+
+- `aggregates`: `func` is one of `count`, `sum`, `avg`, `min`, `max`; use `field="*"` with `count`.
+- `group_by`: optional. Defaults to `fields`; if given, it must include every entry in `fields`.
+- `having`: needs an aggregate expression such as `SUM(amount)`, not an alias.
+- `order_by`: a field, an aggregate alias or an aggregate expression, `asc` (default) or `desc`.
+- `fields` can be omitted for a single total, e.g. `aggregates=[{"func": "count", "field": "*"}]`.
+
+Policies apply to every field these clauses use. `min`/`max`/`sum`/`avg` over a masked
+field are denied; `count` is allowed. Joins are not supported.
+
+> Requires a VaultKit control plane with intent analytics support. Older control
+> planes ignore these parameters and return ungrouped rows.
+
+---
+
 ## AI Agent Usage
 
 VaultKit provides built-in tools for LLM agents.