Python SDK

Supports sync and async. Requires Python 3.10+.

Install

pip install vengtoo

Source: github.com/vengtoo/vengtoo-python

Quick start

from vengtoo import Vengtoo, Subject, Resource, Action

client = Vengtoo(api_key="vgt_...")

decision = client.check(
    subject=Subject(id="user-123", type="user"),
    action="read",
    resource=Resource(id="doc-456", type="document"),
)

Using with the local agent

client = Vengtoo(base_url="http://localhost:8181")

Full response

from vengtoo import EvaluationRequest

resp = client.evaluate(EvaluationRequest(
    subject=Subject(id="user-123", type="user"),
    resource=Resource(id="doc-456", type="document"),
    action=Action(name="read"),
    context={"ip": "10.0.0.1"},
))
# resp.decision, resp.context.reason, resp.context.policy_id, resp.context.access_path

Async

decision = await client.async_check(
    subject=Subject(id="user-123", type="user"),
    action="read",
    resource=Resource(id="doc-456", type="document"),
)

resp = await client.async_evaluate(request)

FastAPI

from fastapi import FastAPI, Depends
from vengtoo import Vengtoo, Subject

app = FastAPI()
vengtoo = Vengtoo(api_key="vgt_...")

def current_subject(request) -> Subject:
    return Subject(id=request.state.user_id, type="user")

@app.get("/documents/{id}")
async def get_doc(id: str, _=Depends(vengtoo.require("document", "read", current_subject))):
    return {"id": id}

The third argument resolves the caller from the request and returns a Subject. Adapt it to your auth layer:

def current_subject(request) -> Subject:
    return Subject(external_id=request.headers["authorization-user-id"], type="user")

Options

Vengtoo(
    api_key="vgt_...",
    base_url="http://localhost:8181",
    timeout=5.0,        # seconds, default 10
    max_retries=3,      # default 2
)

Error handling

from vengtoo import Vengtoo, VengtooError

try:
    client.check(subject, "read", resource)
except VengtooError as e:
    if e.is_auth_error:
        # 401 — invalid API key
        pass
    if e.is_server_error:
        # 5xx — already retried
        pass
    print(e.status_code, e.message)

Client lifecycle

The Python SDK reuses HTTP connections. Close the client when done:

client = Vengtoo(api_key="vgt_...")
# ... use client ...
client.close()

# Or for async:
await client.async_close()

Types

Type	Fields
Subject	type (required), id, external_id, properties
Resource	type (required), id, external_id, properties. If neither id nor external_id is set, "*" is sent automatically for type-level policy matching.
Action	name
EvaluationRequest	subject, resource, action, context
EvaluationResponse	decision, context
EvaluationContext	reason, reason_code, policy_id, access_path