vertical-ai-sdk reference

Install

$ pip install vertical-ai-sdk

That's the whole install. client.overhead, client.underground, and client.ada are all always available — none of them depend on their own source harness package (see what's not here yet for why that matters). The [overhead]/[underground]/[ada] extras still exist and are still accepted — they're currently no-ops, kept as a stable install surface in case a domain ever needs a real dependency again.

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")
    # result is 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 if you're keeping a client alive across a longer-lived process.

Domains

Three domain clients ship today, each a thin, typed wrapper — no compute logic, no lookup tables, every method a real HTTP call. See /domains for the full 17-domain API surface; everything not listed below is reachable directly over REST (see /docs).

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

Error handling

Every non-2xx response raises VerticalAiApiError, carrying the real status code and response body so you can distinguish auth, validation, and server failures without parsing exception text:

from vertical_ai_sdk import VerticalAiApiError

try:
    result = client.overhead.nesc.grade(inp, source_ref="my-tool")
except VerticalAiApiError as exc:
    if exc.status_code == 403:
        # your key's scope doesn't reach this route -- see /pricing
        ...
    print(exc.status_code, exc.detail, exc.path)

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 — every one of these is reachable directly over the REST API today (see /docs):

• 14 domains with no client at all yet: DER, thermal, controls, datacenter, substation (USM), generation/DER interconnection (UGM), building electrical (UBM), transmission structure (UTM), circuit (fault current/ampacity/grounding), the O-Calc/SPIDA/PLS pole-model bridges, field-capture, and line siting.
• ada's other 23 REST routes — the 3 wrapped were chosen to prove the mechanism, not because the rest matter less.
• underground's ~45 session-stateful MCP-only tools (vault/circuit construction) — session-scoped server-side, not REST-shaped, out of scope for a stateless client SDK.
• A declarative YAML/JSON StandardsPack config loader — today it's Python-subclass only.
• Equipment framing (transformer/switch/riser/cutout-fuse mounting), conductor ampacity, and insulation/environmental-district hardware selection — real convergences found while surveying utility standards, each needing its own schema design.