vaultkit 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: VaultKit Python SDK for policy-driven, runtime governed data access
 Author-email: VaultKit <founders@vaultkit.io>
 License: MIT
@@ -93,6 +93,24 @@ result = client.execute(
 
 - `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`.
+  An entry can also be a time bucket of a timestamp or date field, which groups by period
+  (`day`, `week`, `month`, `quarter` or `year`; `alias` and `timezone` are optional, and
+  the time zone defaults to UTC). Use one bucketed query for a trend instead of one query
+  per period:
+
+  ```python
+  client.execute(
+      dataset="payments",
+      aggregates=[{"func": "count", "field": "*", "alias": "failures"}],
+      filters=[{"field": "status", "operator": "eq", "value": "failed"}],
+      group_by=[{"field": "created_at", "bucket": "quarter", "alias": "quarter"}],
+      order_by={"column": "quarter"},
+      purpose="Failed payments per quarter",
+  )
+  ```
+
+  Bucketing a fully or partially masked field is denied, like grouping by it. Needs a
+  control plane with time buckets (vaultkit#106); older ones reject the request.
 - `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": "*"}]`.

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

@@ -67,6 +67,24 @@ result = client.execute(
 
 - `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`.
+  An entry can also be a time bucket of a timestamp or date field, which groups by period
+  (`day`, `week`, `month`, `quarter` or `year`; `alias` and `timezone` are optional, and
+  the time zone defaults to UTC). Use one bucketed query for a trend instead of one query
+  per period:
+
+  ```python
+  client.execute(
+      dataset="payments",
+      aggregates=[{"func": "count", "field": "*", "alias": "failures"}],
+      filters=[{"field": "status", "operator": "eq", "value": "failed"}],
+      group_by=[{"field": "created_at", "bucket": "quarter", "alias": "quarter"}],
+      order_by={"column": "quarter"},
+      purpose="Failed payments per quarter",
+  )
+  ```
+
+  Bucketing a fully or partially masked field is denied, like grouping by it. Needs a
+  control plane with time buckets (vaultkit#106); older ones reject the request.
 - `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": "*"}]`.

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

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

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

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

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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 from vaultkit.core.http import HttpClient, HttpConfig
 from vaultkit.core.polling import PollConfig, poll_until_done
@@ -103,7 +103,7 @@ class VaultKitClient:
         filters: Optional[List[Dict[str, Any]]] = None,
         limit: Optional[int] = None,
         aggregates: Optional[List[Dict[str, Any]]] = None,
-        group_by: Optional[List[str]] = None,
+        group_by: Optional[List[Union[str, Dict[str, str]]]] = None,
         having: Optional[List[Dict[str, Any]]] = None,
         order_by: Optional[Dict[str, Any]] = None,
         purpose: Optional[str] = None,
@@ -118,6 +118,11 @@ class VaultKitClient:
             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.
+                        A time bucket of a timestamp or date field groups by period:
+                        {"field": "created_at", "bucket": "quarter", "alias": "quarter",
+                         "timezone": "America/Toronto"}; bucket is one of day, week,
+                        month, quarter, year; alias and timezone (default UTC) are
+                        optional. One bucketed query replaces one query per period.
             having      [{"field": "SUM(amount)", "operator": "gt", "value": 1000}]
                         field must be an aggregate expression, not an alias.
             order_by    {"column": "total", "direction": "desc"}
@@ -190,6 +195,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)
@@ -239,7 +245,7 @@ class VaultKitClient:
         filters: Optional[List[Dict[str, Any]]] = None,
         limit: Optional[int] = None,
         aggregates: Optional[List[Dict[str, Any]]] = None,
-        group_by: Optional[List[str]] = None,
+        group_by: Optional[List[Union[str, Dict[str, str]]]] = None,
         having: Optional[List[Dict[str, Any]]] = None,
         order_by: Optional[Dict[str, Any]] = None,
         purpose: Optional[str] = None,
@@ -315,6 +321,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.3.0 → vaultkit-0.4.0}/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.3.0 → vaultkit-0.4.0}/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.3.0 → vaultkit-0.4.0}/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.3.0 → vaultkit-0.4.0}/vaultkit/tools/definitions.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional
 
+from vaultkit.utils.validation import TIME_BUCKETS
+
 
 def discover_tool_def(
     *,
@@ -110,6 +112,25 @@ def query_tool_def(
         "required": ["logic", "conditions"],
     }
 
+    time_bucket = {
+        "type": "object",
+        "properties": {
+            "field": {"type": "string", "description": "A timestamp or date field of the dataset."},
+            "bucket": {"type": "string", "enum": list(TIME_BUCKETS)},
+            "alias": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+                "description": "Name of the result column (default <field>_<bucket>). Use it in order_by.",
+            },
+            "timezone": {
+                "type": "string",
+                "description": "IANA time zone the periods start in, e.g. 'America/Toronto'. Default UTC.",
+            },
+        },
+        "required": ["field", "bucket"],
+        "additionalProperties": False,
+    }
+
     return {
         "name": "vaultkit_query",
         "description": (
@@ -117,6 +138,8 @@ def query_tool_def(
             "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. "
+            "For a trend over time (per day, week, month, quarter or year), send ONE query that groups by a "
+            "time bucket of a timestamp field, not one query per period. "
             "Returns data or a pending status if approval is required."
         ),
         "input_schema": {
@@ -173,10 +196,17 @@ def query_tool_def(
                 },
                 "group_by": {
                     "type": "array",
-                    "items": {"type": "string"},
+                    "items": {"oneOf": [{"type": "string"}, time_bucket]},
                     "description": (
-                        "Fields to group by. Optional: defaults to 'fields'. If given, it must include "
-                        "every entry in 'fields'."
+                        "Fields to group by, or time buckets of a timestamp or date field. Optional: "
+                        "defaults to 'fields'. If given, it must include every entry in 'fields'; a "
+                        "bucketed field is not listed in 'fields'.\n\n"
+                        "Example, failed payments per quarter in one query: "
+                        "fields: [], aggregates: [{func: 'count', field: '*', alias: 'failures'}], "
+                        "filters: [{field: 'status', operator: 'eq', value: 'failed'}], "
+                        "group_by: [{field: 'created_at', bucket: 'quarter', alias: 'quarter'}], "
+                        "order_by: {column: 'quarter'}. Each row has the quarter's start date and its count. "
+                        "Mix with plain fields: group_by: ['status', {field: 'created_at', bucket: 'month'}]."
                     ),
                 },
                 "having": {
@@ -203,7 +233,7 @@ def query_tool_def(
                     "properties": {
                         "column": {
                             "type": "string",
-                            "description": "A field, an aggregate alias, or an aggregate expression.",
+                            "description": "A field, an aggregate or time bucket alias, or an aggregate expression.",
                         },
                         "direction": {"type": "string", "enum": ["asc", "desc"], "default": "asc"},
                     },

{vaultkit-0.3.0 → vaultkit-0.4.0}/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
             ],
@@ -121,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
@@ -158,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.3.0 → vaultkit-0.4.0}/vaultkit/utils/validation.py

@@ -131,19 +131,64 @@ def validate_aggregates(value: Optional[Any]) -> Optional[list]:
     return value
 
 
+# Units a group_by time bucket can use. The control plane checks the field is
+# a timestamp or date column and that the time zone exists.
+TIME_BUCKETS = ("day", "week", "month", "quarter", "year")
+TIME_BUCKET_KEYS = {"field", "bucket", "alias", "timezone"}
+
+
 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):
+    if not isinstance(value, list):
         raise ValidationError(
-            "group_by must be a list of field names",
+            "group_by must be a list of field names or time buckets",
             context=ErrorContext(raw=value),
         )
 
+    for entry in value:
+        if isinstance(entry, dict):
+            _validate_time_bucket(entry)
+        elif not (isinstance(entry, str) and entry.strip()):
+            raise ValidationError(
+                "group_by must be a list of field names or time buckets",
+                context=ErrorContext(raw=value),
+            )
+
     return value
 
 
+def _validate_time_bucket(entry: Dict[str, Any]) -> None:
+    unknown = set(entry) - TIME_BUCKET_KEYS
+    if unknown:
+        raise ValidationError(
+            f"group_by time bucket has unknown keys: {', '.join(sorted(unknown))}",
+            context=ErrorContext(raw=entry),
+        )
+
+    field = entry.get("field")
+    if not isinstance(field, str) or not field.strip():
+        raise ValidationError(
+            "group_by time bucket needs a 'field'",
+            context=ErrorContext(raw=entry),
+        )
+
+    bucket = entry.get("bucket")
+    if not isinstance(bucket, str) or bucket.lower() not in TIME_BUCKETS:
+        raise ValidationError(
+            f"group_by time bucket must be one of {', '.join(TIME_BUCKETS)}",
+            context=ErrorContext(raw=entry),
+        )
+
+    for key in ("alias", "timezone"):
+        if key in entry and not (isinstance(entry[key], str) and entry[key].strip()):
+            raise ValidationError(
+                f"group_by time bucket '{key}' must be a non-empty string",
+                context=ErrorContext(raw=entry),
+            )
+
+
 def validate_having(value: Optional[Any]) -> Optional[list]:
     return _require_list_of_dicts("having", value)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: VaultKit Python SDK for policy-driven, runtime governed data access
 Author-email: VaultKit <founders@vaultkit.io>
 License: MIT
@@ -93,6 +93,24 @@ result = client.execute(
 
 - `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`.
+  An entry can also be a time bucket of a timestamp or date field, which groups by period
+  (`day`, `week`, `month`, `quarter` or `year`; `alias` and `timezone` are optional, and
+  the time zone defaults to UTC). Use one bucketed query for a trend instead of one query
+  per period:
+
+  ```python
+  client.execute(
+      dataset="payments",
+      aggregates=[{"func": "count", "field": "*", "alias": "failures"}],
+      filters=[{"field": "status", "operator": "eq", "value": "failed"}],
+      group_by=[{"field": "created_at", "bucket": "quarter", "alias": "quarter"}],
+      order_by={"column": "quarter"},
+      purpose="Failed payments per quarter",
+  )
+  ```
+
+  Bucketing a fully or partially masked field is denied, like grouping by it. Needs a
+  control plane with time buckets (vaultkit#106); older ones reject the request.
 - `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": "*"}]`.