vertical-ai-sdk reference

Getting the SDK

The SDK is shared with API customers on request; it isn't on the public package index. Email hello@vaico.io and we'll send the current release with your key. Python 3.11 or newer. It depends only on pydantic and httpx — no compute engine ships client-side, every method is a real HTTP call to the API. YAML pack files need PyYAML (the [yaml] extra); there are no other extras.

Quickstart

from vertical_ai_sdk import Client

with Client(api_key="vaico_live_...") as client:
    result = client.overhead.nesc.grade(inp, source_ref="my-tool")
    # a typed GradeResult, not a dict -- result.grade, result.rule_refs, result.provenance

Use with Client(...) as client: so the underlying HTTP connection closes when you're done, or call client.close() yourself in a longer-lived process.

Domains

Every API-key route on the API has a typed method — 308 across 18 domains, listed below by the part of the system they serve (the same groups as /domains). They're generated from the live API schema, so new routes show up in the SDK without anyone hand-wrapping them. See /docs for the REST reference.

from vertical_ai_sdk.der._generated import CalculateStateOfChargeRequest

soc = client.der.calculate_state_of_charge(
    CalculateStateOfChargeRequest(present_energy_kwh=50.0, usable_energy_capacity_kwh=100.0, source_ref="my-tool")
)                                                          # soc.soc_percent == 50.0
client.utm.lookup_pole_class_horizontal_load(pole_class="H6")   # GET routes: keyword arguments
client.spida.parse_spida_file(file=Path("project.json"))           # uploads: bytes or Path

client.overhead.nesc.grade(inp, source_ref="...")    # NESC Rule 242
client.overhead.go95.grade(inp, source_ref="...")    # GO-95 Rule 42, aliased .cpuc
client.overhead.csa.grade(inp, source_ref="...")     # CSA C22.3 No.1 Table 27
client.overhead.csa.grade_proximity(inp, source_ref="...")   # Table 28
client.overhead.csa.grade_joint_use(inp, source_ref="...")   # Table 29

Async

import asyncio
from vertical_ai_sdk import AsyncClient

async def main():
    async with AsyncClient(api_key="vaico_live_...") as client:
        soc, limit = await asyncio.gather(
            client.der.calculate_state_of_charge(request),
            client.utm.lookup_pole_class_horizontal_load(pole_class="H6"),
        )

AsyncClient has the same 18 domain attributes, the same typed methods (each one async def), the same retry policy and the same exceptions as Client; only the I/O is awaited. The hand-written ergonomic methods and the jurisdiction facades are sync-only — every route is still reachable asynchronously through the generated methods. A StandardsPack is plain data and works with either client.

Errors & retries

Every non-2xx response raises a subclass of VerticalAiApiError, carrying the real status code and response body. Catch the base class to handle any API failure, or a subclass to react to one case:

from vertical_ai_sdk import RequestValidationError, ScopeError, TransportError

try:
    client.der.calculate_charge_duration({})
except RequestValidationError as exc:
    for err in exc.errors:          # FieldError(loc="body.charge_power_kw", message="Field required")
        print(err.loc, err.message)
except ScopeError:                  # 403: the key is valid but its scopes don't reach this route
    ...
except TransportError:               # no response at all, after the retries
    ...

• AuthenticationError 401 · ScopeError 403 · NotFoundError 404 · RequestValidationError 400/422 (with parsed .errors) · RateLimitError 429 (.retry_after) · ServerError 5xx.
• TransportError covers connection and timeout failures; the original exception is chained as its cause.
• Scopes do not nest — a key scoped to overhead alone does not reach the nesc, go95 or csa routes. A ScopeError names the scope it needed.

Retries. Connection errors, timeouts and 429/502/503/504 are retried automatically — two retries by default, jittered exponential backoff, and the server's Retry-After honoured. Every route is stateless compute, so retrying is safe. A 4xx request error is never retried, and neither is a 500 (an internal error that would simply repeat). Tune or disable it with Client(key, max_retries=0).

Unit conventions

There is no single fixed unit across every clearance route — lookup_nesc_table232_1_clearance returns meters, lookup_go95_table1_clearance returns inches. Every clearance result carries its own unit field — check it, don't assume. classify_clearance is deliberately unit-agnostic: it operates on whatever numbers you pass it, and keeping required/actual/your configured margin in the same unit is on you.

What's not in the SDK yet

Disclosed, not hidden:

• Hand-written ergonomics exist for overhead, underground, circuit and ADA. The other 13 domains work through the generated request-model methods — complete, but not yet given friendlier signatures. We add those where real usage shows they matter.
• Async is generated-methods-only; the hand-written methods and jurisdiction facades are sync-only.
• Standards coverage: 7 of the 16 production rule-template categories have a pack hook today (anchor capacity, grounding resistance, vegetation clearance, sag-tension, conductor ampacity, service voltage drop, transformer loading) and 2 more are partial (angle limits, framing). Not yet: pole strength factors, pole loading overrides, pole attachment separation, loading-area definitions, climbing and working space, avian protection.
• Underground's session-stateful tools (about 45 vault and circuit construction tools that are MCP-only) are session-scoped server-side and not REST-shaped, so a stateless client SDK doesn't cover them.
• Typed results depend on the server: routes the API declares as plain dictionaries return the parsed JSON rather than a model.
• Equipment framing (transformer/switch/riser/cutout-fuse mounting) and insulation/environmental-district hardware selection — real convergences found while surveying utility standards, each needing its own schema design.