vaultkit 0.3.1__tar.gz → 0.4.0__tar.gz

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

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

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

{vaultkit-0.3.1 → 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"}
@@ -240,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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.3.1
+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": "*"}]`.