vaultkit 0.1.0__py3-none-any.whl

vaultkit/tools/executor.py

@@ -0,0 +1,199 @@
+# vaultkit/tools/executor.py
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from vaultkit.errors.exceptions import (
+    ApprovalRequiredError,
+    DeniedError,
+    GrantExpiredError,
+    GrantRevokedError,
+    PolicyBundleRevokedError,
+    QueuedError,
+    ValidationError,
+)
+
+if TYPE_CHECKING:
+    from vaultkit.client import VaultKitClient
+
+
+class ToolExecutor:
+    """
+    Provider-agnostic dispatcher for tool calls -> VaultKitClient methods.
+
+    Any agent runtime can use this as long as it can provide:
+      - tool_name: str
+      - tool_args: dict
+
+    Example (pseudo):
+        name = tool_call["name"]
+        args = tool_call["args"]
+        result = executor.execute(name, args)
+    """
+
+    def __init__(
+        self,
+        client: "VaultKitClient",
+        *,
+        default_purpose: Optional[str] = None,
+        default_requester_region: Optional[str] = None,
+    ) -> None:
+        self._client = client
+        self._default_purpose = default_purpose
+        self._default_requester_region = default_requester_region
+
+    def execute(self, tool_name: str, tool_args: Dict[str, Any]) -> Dict[str, Any]:
+        """Dispatch a tool call. Always returns a dict — never raises."""
+        try:
+            if tool_name == "vaultkit_discover":
+                return self._execute_discover(tool_args)
+            if tool_name == "vaultkit_query":
+                return self._execute_query(tool_args)
+            if tool_name == "vaultkit_check_approval":
+                return self._execute_check_approval(tool_args)
+
+            return self._error(
+                f"Unknown tool '{tool_name}'. "
+                "Available: vaultkit_discover, vaultkit_query, vaultkit_check_approval.",
+                code="unknown_tool",
+            )
+        except Exception as e:
+            return self._translate_error(e)
+
+    # dispatch
+
+    def _execute_discover(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        environment = args.get("environment", "production")
+        requester_region = args.get("requester_region")
+        dataset_region = args.get("dataset_region")
+
+        datasets = self._client.datasets(
+            environment=environment,
+            requester_region=requester_region,
+            dataset_region=dataset_region,
+        )
+
+        visibility_map = {
+            "allow": "accessible",
+            "require_approval": "requires approval",
+            "deny": "not accessible",
+        }
+
+        return {
+            "status": "ok",
+            "datasets": [
+                {
+                    "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
+            ],
+            "count": len(datasets),
+        }
+
+    def _execute_query(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        dataset = args.get("dataset")
+        if not dataset:
+            return self._error("'dataset' is required for vaultkit_query.", code="validation_error")
+
+        purpose = args.get("purpose") or self._default_purpose
+
+        result = self._client.execute(
+            dataset=dataset,
+            fields=args.get("fields"),
+            filters=args.get("filters"),
+            limit=args.get("limit"),
+            purpose=purpose,
+            requester_region=args.get("requester_region") or self._default_requester_region,
+        )
+
+        response: Dict[str, Any] = {
+            "status": "ok",
+            "dataset": dataset,
+            "row_count": result.row_count,
+            "data": result.data,
+        }
+
+        if result.masked_fields:
+            response["note"] = f"Fields {result.masked_fields} were masked per data policy."
+
+        return response
+
+    def _execute_check_approval(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        request_id = args.get("request_id")
+        if not request_id:
+            return self._error("'request_id' is required for vaultkit_check_approval.", code="validation_error")
+
+        poll_result = self._client.poll_request(request_id=request_id)
+
+        if poll_result.is_granted and poll_result.grant_ref:
+            fetch = self._client.fetch(grant_ref=poll_result.grant_ref)
+            return {
+                "status": "approved",
+                "row_count": fetch.row_count,
+                "data": fetch.data,
+                "masked_fields": fetch.masked_fields,
+            }
+
+        if poll_result.is_denied:
+            return {"status": "denied", "reason": poll_result.reason or "Approval was denied."}
+
+        return {
+            "status": "pending",
+            "message": "Approval is still pending. Try again shortly.",
+            "request_id": request_id,
+        }
+
+    # error translation
+
+    def _translate_error(self, exc: Exception) -> Dict[str, Any]:
+        msg = str(exc)
+        error_code = getattr(exc, "error_code", "error")
+
+        if isinstance(exc, DeniedError):
+            policy_id = getattr(exc, "policy_id", None)
+            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",
+            )
+
+        if isinstance(exc, ApprovalRequiredError):
+            return {
+                "status": "pending_approval",
+                "message": (
+                    "This request requires human approval. "
+                    f"Use vaultkit_check_approval with request_id='{exc.request_id}' to check status."
+                ),
+                "request_id": exc.request_id,
+            }
+
+        if isinstance(exc, (GrantExpiredError, GrantRevokedError)):
+            return self._error(
+                f"{msg} Re-submit your query to get a fresh grant.",
+                code=error_code,
+            )
+
+        if isinstance(exc, PolicyBundleRevokedError):
+            return self._error(
+                "The VaultKit policy bundle has been revoked. "
+                "No data access is possible. Escalate to your VaultKit administrator.",
+                code="bundle_revoked",
+            )
+
+        if isinstance(exc, ValidationError):
+            return self._error(f"Invalid query: {msg}", code="validation_error")
+
+        if isinstance(exc, QueuedError):
+            return {"status": "queued", "message": msg, "request_id": exc.request_id}
+
+        return self._error(f"Unexpected error: {type(exc).__name__}: {msg}", code=error_code)
+
+    # helpers
+
+    @staticmethod
+    def _error(message: str, *, code: str = "error") -> Dict[str, Any]:
+        return {"status": code, "error": message}

vaultkit/tools/schemas.py

@@ -0,0 +1,39 @@
+"""
+Backward-compatible module.
+
+If you previously imported:
+  from vaultkit.tools.schemas import query_tool_schema
+
+You can keep doing so, but these now generate *OpenAI* tools by default.
+
+Prefer the new canonical definitions via:
+  from vaultkit.tools.definitions import query_tool_def
+  ToolBuilder(...).build(provider=ToolProvider.ANTHROPIC)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .adapters.openai import to_openai_tool
+from .definitions import (
+    check_approval_tool_def,
+    discover_tool_def,
+    query_tool_def,
+)
+
+
+def discover_tool_schema(*, dataset_names: Optional[List[str]] = None) -> Dict[str, Any]:
+    return to_openai_tool(discover_tool_def(dataset_names=dataset_names))
+
+
+def query_tool_schema(
+    *,
+    dataset_names: Optional[List[str]] = None,
+    schema_hints: Optional[Dict[str, List[str]]] = None,
+) -> Dict[str, Any]:
+    return to_openai_tool(query_tool_def(dataset_names=dataset_names, schema_hints=schema_hints))
+
+
+def check_approval_tool_schema() -> Dict[str, Any]:
+    return to_openai_tool(check_approval_tool_def())

vaultkit/utils/__init__.py

@@ -0,0 +1 @@
+__all__ = []

vaultkit/utils/retry.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import time
+import random
+import logging
+from dataclasses import dataclass
+from typing import Callable, TypeVar, Optional
+
+from vaultkit.errors.exceptions import RateLimitError, TransportError, ServerError
+
+T = TypeVar("T")
+
+logger = logging.getLogger("vaultkit.retry")
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    max_attempts: int = 3
+    base_sleep_s: float = 0.5
+    max_sleep_s: float = 4.0
+
+    # Add jitter (±20%)
+    jitter_ratio: float = 0.2
+
+
+def retryable(exc: Exception) -> bool:
+    return isinstance(exc, (RateLimitError, TransportError, ServerError))
+
+
+def with_retries(
+    fn: Callable[[], T],
+    *,
+    config: RetryConfig,
+) -> T:
+    attempt = 0
+    sleep_s = config.base_sleep_s
+
+    while True:
+        attempt += 1
+
+        try:
+            return fn()
+
+        except Exception as e:
+            is_retryable = retryable(e)
+
+            if attempt >= config.max_attempts or not is_retryable:
+                logger.debug(
+                    "retry.exit",
+                    extra={
+                        "attempt": attempt,
+                        "retryable": is_retryable,
+                        "error_type": type(e).__name__,
+                    },
+                )
+                raise
+
+            # Apply jitter
+            jitter = random.uniform(
+                -sleep_s * config.jitter_ratio,
+                sleep_s * config.jitter_ratio,
+            )
+
+            sleep_time = min(
+                max(0.0, sleep_s + jitter),
+                config.max_sleep_s,
+            )
+
+            logger.debug(
+                "retry.sleep",
+                extra={
+                    "attempt": attempt,
+                    "sleep_s": sleep_time,
+                    "error_type": type(e).__name__,
+                },
+            )
+
+            time.sleep(sleep_time)
+
+            # Exponential backoff
+            sleep_s = min(sleep_s * 2, config.max_sleep_s)

vaultkit/utils/validation.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from vaultkit.errors.base import ErrorContext
+from vaultkit.errors.exceptions import ValidationError
+
+
+def require_str(name: str, value: Optional[str]) -> str:
+    if value is None:
+        raise ValidationError(
+            f"{name} is required",
+            context=ErrorContext(raw={name: value}),
+        )
+
+    result = str(value).strip()
+    if not result:
+        raise ValidationError(
+            f"{name} cannot be empty",
+            context=ErrorContext(raw={name: value}),
+        )
+
+    return result
+
+
+def require_dict(name: str, value: Any) -> Dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValidationError(
+            f"{name} must be an object/dict",
+            context=ErrorContext(raw={name: value}),
+        )
+    return value
+
+
+def require_list(name: str, value: Any) -> list:
+    if not isinstance(value, list):
+        raise ValidationError(
+            f"{name} must be a list",
+            context=ErrorContext(raw={name: value}),
+        )
+    return value
+
+
+def validate_limit(value: Optional[int]) -> Optional[int]:
+    if value is None:
+        return None
+
+    if not isinstance(value, int):
+        raise ValidationError(
+            "limit must be an integer",
+            context=ErrorContext(raw=value),
+        )
+
+    if value <= 0:
+        raise ValidationError(
+            "limit must be greater than 0",
+            context=ErrorContext(raw=value),
+        )
+
+    if value > 10000:
+        raise ValidationError(
+            "limit cannot exceed 10000",
+            context=ErrorContext(raw=value),
+        )
+
+    return value
+
+
+def validate_filters(value: Optional[Any]) -> Optional[list]:
+    if value is None:
+        return None
+
+    if not isinstance(value, list):
+        raise ValidationError(
+            "filters must be a list",
+            context=ErrorContext(raw=value),
+        )
+
+    # light structural validation
+    for f in value:
+        if not isinstance(f, dict):
+            raise ValidationError(
+                "each filter must be an object",
+                context=ErrorContext(raw=f),
+            )
+
+    return value

vaultkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: vaultkit
+Version: 0.1.0
+Summary: VaultKit Python SDK for policy-driven, runtime governed data access
+Author-email: VaultKit <founders@vaultkit.io>
+License: MIT
+Project-URL: Homepage, https://github.com/vaultkit-inc/vaultkit-sdk-python
+Project-URL: Documentation, https://docs.vaultkit.io
+Project-URL: Source, https://github.com/vaultkit-inc/vaultkit-sdk-python
+Project-URL: Issues, https://github.com/vaultkit-inc/vaultkit-sdk-python/issues
+Keywords: ai,data,sdk,governance,security,agents,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+
+# VaultKit Python SDK
+
+> Secure, policy-driven data access for AI agents and applications.
+
+VaultKit is a control plane for governed data access. This SDK allows Python applications and AI agents to safely query data with built-in policy enforcement, approval workflows, and auditability.
+
+---
+
+## Features
+
+- Policy-enforced data access (masking, approval, deny)
+- First-class support for AI agents (OpenAI, Anthropic)
+- Built-in approval workflows
+- Automatic polling and retries
+- Schema-aware dataset discovery
+- Simple, high-level API via `execute()`
+
+---
+
+## Installation
+
+```bash
+pip install vaultkit
+```
+
+---
+
+## Quick Start
+
+```python
+from vaultkit import VaultKitClient
+
+client = VaultKitClient(
+    base_url="http://localhost:3000",
+    token="YOUR_TOKEN",
+    org="YOUR_ORG",
+)
+
+result = client.execute(
+    dataset="users",
+    fields=["id", "email"],
+    limit=10,
+    purpose="Analyze user activity",
+)
+
+print(result.rows)
+```
+
+---
+
+## AI Agent Usage
+
+VaultKit provides built-in tools for LLM agents.
+
+```python
+from vaultkit.tools import ToolBuilder, ToolExecutor, ToolProvider
+
+builder = ToolBuilder(client)
+
+tools = builder.build(
+    provider=ToolProvider.OPENAI,
+    include_check_approval=True,
+)
+
+executor = ToolExecutor(client)
+
+result = executor.execute(
+    "vaultkit_query",
+    {
+        "dataset": "users",
+        "limit": 5,
+        "purpose": "Analyze user trends",
+    },
+)
+```
+
+See full example: [`examples/agent_openai_demo.py`](examples/agent_openai_demo.py)
+
+---
+
+## Approval Flow
+
+Some queries require human approval before data is returned.
+
+```python
+from vaultkit.errors.exceptions import ApprovalRequiredError
+
+try:
+    client.execute(dataset="sensitive_data", purpose="Analysis")
+except ApprovalRequiredError as e:
+    print(f"Approval required. Request ID: {e.request_id}")
+```
+
+Once approved, resume with:
+
+```python
+result = client.poll_request(request_id="req_123")
+```
+
+---
+
+## API Overview
+
+### High-Level
+
+| Method | Description |
+|---|---|
+| `client.execute(...)` | Full lifecycle: query → poll → fetch. Recommended for most use cases. |
+
+### Low-Level
+
+| Method | Description |
+|---|---|
+| `client.query(...)` | Submit an intent request, get a `QueryResult` |
+| `client.poll(result)` | Block until a queued result reaches a terminal state |
+| `client.fetch(grant_ref=...)` | Redeem a grant for data |
+| `client.poll_request(request_id=...)` | Poll by request ID (used in approval flows) |
+
+### Discovery
+
+| Method | Description |
+|---|---|
+| `client.datasets()` | List authorized datasets from the registry |
+| `client.schema("users")` | Get field-level schema for a dataset |
+
+---
+
+## How It Works
+
+```
+Client → VaultKit → Policy Engine → Data Source
+                         ↓
+                  Enforced Policies
+```
+
+1. Queries are evaluated against policy bundles at runtime
+2. Sensitive fields may be masked based on requester context
+3. Some datasets require human approval before access is granted
+4. All access is logged and auditable
+
+---
+
+## Why VaultKit?
+
+Traditional access control is static — permissions are set upfront and rarely change. VaultKit enables:
+
+- **Runtime, policy-driven access** — decisions made at query time based on context
+- **AI-safe data access** — purpose and clearance are first-class query parameters
+- **Auditability and compliance** — every request is tracked with correlation IDs
+
+---
+
+## Environment Variables
+
+```bash
+export VAULTKIT_URL=http://localhost:3000
+export VAULTKIT_TOKEN=your_token
+export VAULTKIT_ORG=your_org
+```
+
+Or use a `.env` file (see [`.env.example`](.env.example)).
+
+---
+
+## Local Development
+
+Start VaultKit locally with Docker:
+
+```bash
+docker compose up
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+---
+
+## License
+
+MIT

vaultkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+vaultkit/__init__.py,sha256=xOscURPo7m01LpD36Px0bNKEz04QuMSM9oWSyTq9HTQ,1775
+vaultkit/client.py,sha256=ojdvJD4B5C81SBEDLHVCIqUVmCveyGKi3u0jcbjPDug,14499
+vaultkit/core/__init__.py,sha256=d4IG0OxUXj2HffepzQcYixHlZeuuuDMAFa09H_6LtmU,12
+vaultkit/core/http.py,sha256=0eu91QTQr8I4YtRQSoemNVgKC6yY8L8q3E9ezEcsKsk,5451
+vaultkit/core/polling.py,sha256=K_Y-5MvemWaeTppNPsBdevK5f_wkBB9KUPA_PZUBDe4,4163
+vaultkit/errors/__init__.py,sha256=nh2Uu7MjIVcp3rD8uQTYidZXD-ysdV62dlj78AA6WhE,691
+vaultkit/errors/base.py,sha256=U8ctwfA7d6IBXN5NBzIIn-sPTkd1kYZiLNQNNyaeBYU,835
+vaultkit/errors/exceptions.py,sha256=sNZSqqONoT1DoSFLDsiZaO0jC5PBZIcHt_dt3gGAUKQ,4954
+vaultkit/models/__init__.py,sha256=uUf4xeeM2Xz5hS-OZA9oAhy7LWLQd60Dv22Pw0Ff6uI,248
+vaultkit/models/dataset_info.py,sha256=tJDklLxx7YYqUJ6xM2ICDMLqtozAyaaRtEN5ppHaVDE,699
+vaultkit/models/dataset_schema.py,sha256=F7Dtz2doNka5lwUyMZNC-y_vFu1OHIMxXmxNgIJxwuo,1957
+vaultkit/models/fetch_result.py,sha256=eTIsO3KXw-ga9XD3XFGygXLKrE0vLaRRKPPfd65box8,1547
+vaultkit/models/query_result.py,sha256=u-CJlebz1xbYjDDaKYkZ7Q0-0-frLPx0KkvUww7aBW0,2233
+vaultkit/tools/__init__.py,sha256=TnuStyD_9vVwiJ_aXO0TFx112w0ZHO_QfSajRTOizN0,162
+vaultkit/tools/builder.py,sha256=Wui6reEqDSyKlGZg7-cPu3XLO7P9WEmHRSAtWzuoLIM,4137
+vaultkit/tools/definitions.py,sha256=_p-LxBIGOSDnUruywMQfDc7HhXRYgDvMAOmQX2PIwGU,6163
+vaultkit/tools/executor.py,sha256=1qNXEONY1-qVICAZ5mZQxUoGfMUEHjlHLWDvFbjbuZ0,6859
+vaultkit/tools/schemas.py,sha256=EXP8PjOucffvuB1bGRYiSWBJ6nrZxz-AH2HUWsIxkRQ,1107
+vaultkit/tools/adapters/__init__.py,sha256=r3-XRYvPkobjr0zA3bhKLSI8hH7j7oEkTaRpOTzdL3c,186
+vaultkit/tools/adapters/anthropic.py,sha256=sV0rsgq-wEMBM5Yi6iwvvHpr_wBHG08GXugErgqqtbU,490
+vaultkit/tools/adapters/openai.py,sha256=zmkI6y3m9HF7ppOqqLvqLoKIrYhTsp29pHeSYgxAFc4,658
+vaultkit/utils/__init__.py,sha256=d4IG0OxUXj2HffepzQcYixHlZeuuuDMAFa09H_6LtmU,12
+vaultkit/utils/retry.py,sha256=ONhY98EV3MviWN9nP-WRO5rNws_L1D6yK01kj5AneIY,1943
+vaultkit/utils/validation.py,sha256=DBA_xS7frqn4IQTSFL0edxmG4oHwNmalAF9gHiXP7Vs,2183
+vaultkit-0.1.0.dist-info/METADATA,sha256=b2BVQy5RSul26ouSwFEqpajGwYo4gx-kcwV9BYkRhLs,4821
+vaultkit-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+vaultkit-0.1.0.dist-info/top_level.txt,sha256=c2ZPwFHOBzAB3cplCOpzxS7rp5RrYId8W3o2gnxOIUg,9
+vaultkit-0.1.0.dist-info/RECORD,,

vaultkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vaultkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vaultkit