vaultkit 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.2.0
+Version: 0.3.1
 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.1}/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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vaultkit"
-version = "0.2.0"
+version = "0.3.1"
 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.1}/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.1"
 
 __all__ = [
     "VaultKitClient",

{vaultkit-0.2.0 → vaultkit-0.3.1}/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,
@@ -166,6 +190,7 @@ class VaultKitClient:
             raise DeniedError(
                 result.reason or "Request denied by policy",
                 policy_id=result.policy_id,
+                reason=result.reason,
             )
 
         # Case 1: data already returned (reuse path)
@@ -214,6 +239,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 +252,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 +268,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 +289,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,
                 },
             )
@@ -274,6 +316,7 @@ class VaultKitClient:
                 raise DeniedError(
                     result.reason or "Request denied",
                     policy_id=result.policy_id,
+                    reason=result.reason,
                 )
             if result.is_pending and not poll:
                 raise QueuedError(

{vaultkit-0.2.0 → vaultkit-0.3.1}/vaultkit/core/http.py

@@ -166,6 +166,7 @@ class HttpClient:
                     raw.get("error")
                     or raw.get("message")
                     or raw.get("detail")
+                    or raw.get("reason")
                     or msg
                 )
         except Exception:

{vaultkit-0.2.0 → vaultkit-0.3.1}/vaultkit/errors/exceptions.py

@@ -62,10 +62,12 @@ class DeniedError(VaultKitError):
         message: str,
         *,
         policy_id: Optional[str] = None,
+        reason: Optional[str] = None,
         context: Optional[ErrorContext] = None,
     ) -> None:
         super().__init__(message, context=context)
         self.policy_id = policy_id
+        self.reason = reason or message
 
 
 class QueuedError(VaultKitError):
@@ -185,10 +187,13 @@ def map_http_error(status_code: int, message: str, *, context: ErrorContext) ->
         return AuthError(message, context=context)
 
     if status_code == 403:
-        if error_type == "policy_denied":
+        # The intent API answers a denial with {"status": "denied", "policy_id", "reason"};
+        # older backends sent {"type": "policy_denied"}.
+        if error_type == "policy_denied" or raw.get("status") == "denied":
             return DeniedError(
                 message,
                 policy_id=raw.get("policy_id"),
+                reason=raw.get("reason"),
                 context=context,
             )
         return ForbiddenError(message, context=context)

{vaultkit-0.2.0 → vaultkit-0.3.1}/vaultkit/models/fetch_result.py

@@ -42,12 +42,23 @@ class FetchResult:
     @property
     def masked_fields(self) -> List[str]:
         """
-        Masked field names from meta, if your API returns them there.
+        Masked field names from meta.
+
+        funl sends meta.masked_fields as a map of field -> mask method
+        ({"email": "partial"}); a plain list of names is also accepted.
         Returns [] safely if meta is absent or has no masked_fields key.
         """
         value = (self.meta or {}).get("masked_fields")
+        if isinstance(value, dict):
+            return list(value.keys())
         return value if isinstance(value, list) else []
 
+    @property
+    def masking_methods(self) -> Dict[str, str]:
+        """Mask method per masked field, e.g. {"email": "partial"}. Empty if the API sent a list."""
+        value = (self.meta or {}).get("masked_fields")
+        return dict(value) if isinstance(value, dict) else {}
+
     @property
     def is_empty(self) -> bool:
         return not self.rows

{vaultkit-0.2.0 → vaultkit-0.3.1}/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.1}/vaultkit/tools/executor.py

@@ -86,7 +86,6 @@ class ToolExecutor:
                     "name": d.dataset,
                     "datasource": d.datasource,
                     "visibility": visibility_map.get(getattr(d, "visibility", None), getattr(d, "visibility", None)),
-                    "field_count": len(getattr(d, "fields", []) or []),
                 }
                 for d in datasets
             ],
@@ -105,6 +104,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,
         )
@@ -117,6 +120,7 @@ class ToolExecutor:
         }
 
         if result.masked_fields:
+            response["masked_fields"] = result.masked_fields
             response["note"] = f"Fields {result.masked_fields} were masked per data policy."
 
         return response
@@ -154,12 +158,17 @@ class ToolExecutor:
 
         if isinstance(exc, DeniedError):
             policy_id = getattr(exc, "policy_id", None)
+            reason = getattr(exc, "reason", None) or exc.message
             extra = f" (policy_id={policy_id})" if policy_id else ""
-            return self._error(
-                f"Access denied by VaultKit policy{extra}. Reason: {msg}. "
-                "Do not retry — this denial is deterministic.",
-                code="denied",
-            )
+            return {
+                "status": "denied",
+                "reason": reason,
+                "policy_id": policy_id,
+                "error": (
+                    f"Access denied by VaultKit policy{extra}. Reason: {reason}. "
+                    "Do not retry — this denial is deterministic."
+                ),
+            }
 
         if isinstance(exc, ApprovalRequiredError):
             return {

{vaultkit-0.2.0 → vaultkit-0.3.1}/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.1}/vaultkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.2.0
+Version: 0.3.1
 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.