Chapter 3: Getting Started: Your First System One Request

Environment Setup

Every example in this book runs through one Python package and one environment variable. The SDK "automatically reads your TYPESAFE_API_KEY environment variable and uses the jev-latest model by default." Treat the key like an SNMPv3 credential or a TACACS+ key: export it for interactive work, keep it out of Git via .gitignore, and store it in a real secret manager (Ansible Vault, Kubernetes Secret, CI encrypted variables) for anything unattended.

export TYPESAFE_API_KEY="ts_live_your_key_here"
echo "${TYPESAFE_API_KEY:0:8}..."   # print only a prefix, never the whole key

A detail that bites automation engineers constantly: a variable exported in your interactive shell is not automatically visible to a systemd service, a cron job, or a Docker container. When a script works by hand but fails under the scheduler, check the environment first — the same way you'd check whether a route exists in the VRF the traffic actually lands in.

The SDK requires Python 3.10 or higher and installs with either of the two common package managers. Use a per-project virtual environment — the equivalent of putting each service in its own VRF instead of letting dependencies leak into the global routing table.

python3 -m venv ~/venvs/noc-triage
source ~/venvs/noc-triage/bin/activate
pip install typesafe-sdk          # or: uv add typesafe-sdk

Before writing triage logic, prove three things independently: the package imports, the key is readable, and the API answers. The cheapest live check is GET /v1/models — it consumes no input tokens, so it's the network engineer's equivalent of a ping before a traceroute.

curl -s https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

The most reliable end-to-end smoke test is the smallest possible real request: one short state, one Noul question. If it returns, your key, network path, Python version, and billing account are all confirmed live in one round trip. Log the returned request_id from this first call on — it is the only identifier that ties your side of a conversation to TypeSafe's.

The SDK raises three distinct exception types: TypeSafeError for validation issues such as empty questions or empty criteria, TypeSafeAPIError for unsuccessful server responses, and TypeSafeAPIConnectionError for connection or timeout failures. Knowing which one you got tells you whether the problem is in your request, on the server, or in the path between them.

Key Takeaway: The entire setup is one package and one environment variable: install typesafe-sdk on Python 3.10+, export TYPESAFE_API_KEY, and let TypeSafeClient() pick the key up on its own. Prove access with the smallest possible real request rather than assuming it works, and log the returned request_id from day one.

Figure 3.1: Environment setup sequence, from interpreter check to a verified live request

Anatomy of a Request

You give Jev something to look at (state) and a set of named, typed questions about it (questions). Everything else — model selection, timeouts, retries, extra headers — is optional tuning.

Figure 3.2: Anatomy of a System One request and response

state is "text, a JSON object, or an array to evaluate." The best mental model for network engineers is packet classification: state is the packet header plus payload; the questions are the ACL entries and QoS classifiers matched against it. A classifier can only act on fields present in the packet — Jev can only answer from what you put in state. For a single syslog event the raw line is usually enough; when triage depends on context ("is this the fourth flap in ten minutes?"), that context has to be structured into the state as an object, because Jev evaluates what you give it and nothing else. Keep the state tight — you're billed on input tokens at $42 per billion, with output free.

questions is "a non-empty mapping of question names to question objects." The keys are names you invent; the values are Noul (yes/no), Choice (multiple options), or Score (rating on a scale).

Choice criteria are a dict; Score criteria are an ordered list where position 0 is the bottom of the scale. Descriptions on Choice labels are technically optional (the SDK accepts None per label), but write them anyway for production triage — a label like routing means one thing to you and may be ambiguous to a model inferring intent from six characters. Descriptions are the equivalent of an ACL remark line: optional, but operationally essential. The question-name keys you choose become the keys of the response's answers dictionary, so pick names that will survive contact with downstream systems like ServiceNow.

model is optional and overrides the client default; when None, the call inherits the client's configured model, which defaults to jev-latest.

For a NOC service writing severity and team assignments into ServiceNow, pin jev-1.13.0 in production while running jev-latest in staging — the same change-control discipline that stops you from pushing a new vendor release to sixty access switches without a deliberate promotion.

response = client.system_one(
    state=syslog_line,
    questions=triage_questions,
    model="jev-1.13.0",
)

Other optional per-call parameters: retry (retry policy), timeout (override in seconds), extra_headers, and extra_body (shallow-merged extra fields). In a syslog pipeline, timeout and retry matter most — a triage service that blocks indefinitely on one call is worse than one that drops the event and logs it.

Key Takeaway: A request is state plus questions. state accepts text, a JSON object, or an array, and questions is a non-empty mapping whose keys become the keys of the response. Everything else, including model, is optional — but pinning jev-1.13.0 in production instead of riding jev-latest is the same change-control instinct you already apply to device firmware.

Worked Example: Classifying a Cisco Syslog Line

Cisco IOS-XE syslog follows %FACILITY-SEVERITY-MNEMONIC: Message-text. FACILITY names the subsystem (LINEPROTO for line protocol, LINK for physical interface, SYS, OSPF, BGP); the severity digit runs 0–7 (lower = more severe); MNEMONIC is a short uppercase code like UPDOWN.

*Feb 14 09:40:12.418: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/0/24, changed state to down

LINEPROTO means a Layer 2 event, not Layer 1 (LINK-3-UPDOWN is the physical-layer counterpart). The 5 is Cisco's own severity, Notice — "normal but significant," typically used for interface state changes. This is exactly where the device's built-in severity stops being enough: Cisco stamps every LINEPROTO-5-UPDOWN as a 5 whether the port is an unused desk drop or a voice uplink. GigabitEthernet1/0/24 is an access-stack port, a strong hint this is an edge port — but the severity digit can't express that. A Score question about operational severity produces a judgment the facility code structurally cannot. The same pattern scales across the NOC: Arista EOS, Junos, and Aruba AOS-CX all implement essentially the same eight severity levels, so one set of typed questions covers the whole multi-vendor estate.

Three questions, one call: subsystem is a Choice (the answer is one of a fixed set of teams), operational_severity is a Score (a graded judgment on an ordered scale), and actionable_tonight is a Noul (paging is yes/no).

triage_questions = {
    "subsystem": Choice(
        instructions="Which NOC team owns the subsystem this message came from",
        criteria={
            "interface": "Physical port, line protocol, or link state events",
            "routing": "OSPF, BGP, EIGRP adjacency and convergence events",
            "system": "Config changes, reloads, process crashes, hw faults",
            "wireless": "Access point, WLAN, or controller events",
        },
    ),
    "operational_severity": Score(
        instructions=(
            "How severe this event is for network operations, considering "
            "scope of impact rather than the severity digit in the message"
        ),
        criteria=[
            "Routine state change on a single edge port, no user impact",
            "Localized issue affecting one access port or one user",
            "Service-affecting issue on an uplink, trunk, or shared segment",
            "Widespread outage affecting a site or many users",
        ],
    ),
    "actionable_tonight": Noul(
        instructions="Needs a human to act during the current shift",
    ),
}

response = client.system_one(state=syslog_line, questions=triage_questions)

Every Choice label carries a description in the vocabulary of a network engineer, the same signal a runbook gives a new NOC hire. The Score criteria are ordered least to most severe, and the instruction explicitly tells the model to reason about scope of impact rather than copy the 5 out of the message — without that instruction, "severity 5" is a reasonable literal answer, and you'd get what you asked for rather than what you meant. One request, three answers, is also the cost argument: you're billed on input tokens, so bundling questions avoids re-sending the same syslog line three times.

Figure 3.3: The syslog triage call as a request/response sequence

The SDK offers both a synchronous TypeSafeClient and an asynchronous AsyncTypeSafeClient, used with await. Synchronous blocking is right for a cron job, a CLI tool, or any script where simplicity beats throughput. Async lets many requests be in flight at once — what you want when a Splunk forwarder hands you hundreds of events a minute.

async def triage(syslog_line: str):
    client = AsyncTypeSafeClient()
    response = await client.system_one(
        state=syslog_line,
        questions=triage_questions,
    )
    return response

response = asyncio.run(triage(syslog_line))

The published rate limits are 250,000 tokens/second and 1,200 requests/minute. A synchronous single-threaded loop hits wall-clock latency as its ceiling long before the API's rate limit — that's usually the trigger to move to async. Note: the documentation confirms the class name and await usage but doesn't publish full async lifecycle details (context manager vs. explicit close); if unsure, start synchronous.

Key Takeaway: A complete triage call is one raw syslog line as state and three typed questions — a Choice for owning team, a Score for operational severity, a Noul for whether to page — sent in a single request. Write descriptions and rubric levels in operational language, and state explicitly when you want judgment about impact rather than the severity digit already in the message. Start synchronous; move to async only when volume demands it.

Reading the Response

The call returns a SystemOneResponse. answers is "a dictionary of all answer objects keyed by question name" — ask about subsystem, read back answers["subsystem"]. Alongside it, three type-specific collections narrow the view: nouls (yes/no answers), choices, and scores, each keyed by question name. Use answers to iterate uniformly; use the typed collections when code only cares about one kind of answer, such as a paging rule that reads only nouls.

Figure 3.4: Structure of a SystemOneResponse for the syslog triage example

The response also carries metadata: request_id (the x-typesafe-request-id header), model (which model answered), and raw_http_response (an escape hatch for anything the typed fields don't surface).

Two behaviors surprise people coming from traditional APIs. First, a Noul returns a probability, not a boolean — a number you threshold, not a yes you act on. Second, a Score returns an expected score that can be fractional: in the syslog example, 1.12 means the model is mostly on "localized issue affecting one access port" with meaningful weight still on the routine level below it — exactly the right read for a single edge port going down.

subsystem = response.answers["subsystem"]
severity = response.answers["operational_severity"]
actionable = response.answers["actionable_tonight"]

print(f"team: {subsystem.choice}  severity: {severity.score:.2f}  page: {actionable.noul:.3f}")

# Route to a human when the model is not sure enough to act alone
if subsystem.confidence < 0.80:
    print(f"LOW CONFIDENCE — queue for review (request_id={response.request_id})")
else:
    print(f"Assigning to team: {subsystem.choice}")

That confidence gate is the single most important habit to form early. An automation that assigns tickets at 94% confidence and escalates at 60% is trustworthy; one that assigns every ticket with equal conviction is not — the first time it silently routes a core routing failure to the wireless queue, your team stops trusting the whole pipeline.

usage reports input_tokens and output_tokens, each an integer or None — handle the None case so a missing field doesn't crash a pipeline. Only input_tokens is billed, at $42 per billion, with output free.

usage = response.usage
input_tokens = usage.input_tokens if usage and usage.input_tokens is not None else 0
cost_usd = input_tokens * 42 / 1_000_000_000
print(f"input_tokens={input_tokens} cost=${cost_usd:.8f} request_id={response.request_id}")

A NOC processing a million syslog events a month at roughly 200 input tokens each lands around 200 million input tokens — a little over eight dollars. The expensive mistake isn't per-event cost; it's re-sending the same state three times because you asked three questions in three separate calls, which triples the only number you're billed on. Bundle your questions, and log input_tokens with request_id together on every call.

One honest limitation: Jev is built for fast, typed judgment, not calculation. Don't ask it to total your token spend or do arithmetic on values inside the state — do the math in Python, and let Jev classify, score, and tell you how sure it is.

Key Takeaway: answers is keyed by your question names and yields noul as a probability, choice as a label, and score as an expected value that may be fractional, each accompanied by confidence and probabilities. Gate automation on confidence rather than acting on every answer identically, and log usage.input_tokens with request_id on every call — input tokens are the only thing billed, at $42 per billion, with output free.

Key Terms