Python SDK

from vadyl import Client
import os

vadyl = Client(
    api_url="https://api.vadyl.app/v1",
    token=os.environ["VADYL_TOKEN"],
    tenant="acme",
    project="billing",
    # optional — pin to a feature branch
    branch=os.environ.get("VADYL_BRANCH"),
)

# Typed filter, sort, pagination, and relation expansion
recent = vadyl.orders.list(
    filter={
        "status":    {"in": ["paid", "fulfilled"]},
        "total":     {"gt": 100},
        "createdAt": {"gte": "now-30d"},
    },
    sort=[{"field": "createdAt", "direction": "desc"}],
    page_size=50,
    include=["customer", "items.product"],
)

# recent.data: list[Order]
# recent.page.next: cursor for next page
print(len(recent.data), recent.page.next)

# Idempotent create — safe to retry
customer = vadyl.customers.create(
    {"email": "ada@example.com", "name": "Ada Lovelace"},
    idempotency_key=f"signup:{session.id}",
)

# Update with optimistic concurrency
updated = vadyl.customers.update(
    customer.id,
    {"name": "Ada L."},
    if_match=customer.concurrency_token,
)

# Delete (soft-delete on entities with that lifecycle)
vadyl.customers.delete(customer.id)

# Sync streaming subscription with the same filter AST as queries
with vadyl.orders.subscribe(
    filter={"status": {"eq": "paid"}},
    kinds=["created", "updated"],
) as sub:
    for evt in sub.events():
        # evt.kind, evt.entity_id, evt.changed_fields, evt.occurred_at
        # Field NAMES only — re-read for values
        order = vadyl.orders.read(evt.entity_id)
        print("paid:", order)

# Or async
async with vadyl.aio.orders.subscribe(...) as sub:
    async for evt in sub: ...

# Start a durable workflow
run = vadyl.workflows.fulfill_order.start(
    order_id="ord_abc",
)

# Send a signal (e.g. from a webhook)
vadyl.workflows.fulfill_order.signal(
    run.id, "shipped",
    {"trackingNumber": "1Z..."},
)

# Query run state
state = vadyl.workflows.fulfill_order.query(run.id)

# Run an agent — typed plan IR, capability-aware model routing
run = vadyl.agents.SupportAgent.run(
    prompt="Refund order #12345 due to defect",
    user_id=session.user_id,
    budget={"max_tokens": 50_000, "max_tool_calls": 30},
)

# Stream the run
for step in run.stream():
    print(step.kind, step.summary)

# Recall memory for an agent
facts = vadyl.agents.SupportAgent.memory.recall(
    kind="preference",
    subject=session.user_id,
)

from vadyl import (
    VadylError,
    AccessDeniedError,
    ValidationError,
    ConflictError,
    QuotaExceededError,
)

try:
    vadyl.orders.update(id, {"status": "refunded"})
except AccessDeniedError as err:
    print(err.reason_code, err.correlation_id)
except ConflictError:
    # optimistic-concurrency mismatch — re-read and retry
    ...
except VadylError as err:
    print(err.code, str(err))

from vadyl import handler

@handler.core
async def charge_order(ctx, order_id: str):
    order = await ctx.entities.Order.read(order_id)

    charge = await ctx.connections.stripe.create_charge(
        amount=order.total,
        currency=order.currency,
        idempotency_key=f"charge:{order.id}",
    )

    await ctx.entities.Order.update(order.id, {
        "status": "paid",
        "chargeId": charge.id,
    })

    await ctx.events.emit("order.paid", {"orderId": order.id})
    return {"ok": True, "charge_id": charge.id}