Chapter 1: Introduction: Fast Decisions, Not Generated Text

What TypeSafe AI Is

Most network engineers have written a script that regexes a syslog line and chains if statements to decide whether an event is worth a 3 a.m. page. That works until the judgment needed isn't "does this string match" but "is this customer-impacting." That is judgment, not pattern matching — the part a script has never handled well.

TypeSafe AI targets exactly that gap. Instead of treating models as text generators whose output a human reads, it exposes AI primitives: modular, composable building blocks meant for software integration. A primitive is one narrowly scoped question with a declared answer shape — you ask it to decide, and it hands back a value your code can use without translation.

Jev is TypeSafe's flagship model and first System One model. It evaluates typed questions against a state and returns structured results directly. Three terms carry the architecture:

• State — the evidence being judged (a syslog line, a ticket body, device JSON).
• Question — the judgment wanted, expressed as a typed primitive with instructions and criteria.
• Typed answer — what comes back: a label, a score, or a probability, plus a distribution over the possibilities.

Every evaluation goes through one API endpoint, POST /v1/systemone — no separate endpoint per question type. Most queries complete in roughly 100 milliseconds, fast enough to sit inline in a syslog ingestion path rather than a batch job.

Figure 1.1: System One Request and Response Shape

The friction TypeSafe removes: generative LLMs are excellent at human-readable text, but that strength becomes a liability when you need machine-readable output. The typical workaround coerces a text generator into structure, then parses the result back — adding complexity and failure points at every step. System One models skip that round trip and return typed, structured answers directly: a choice, a score, or a probability distribution — "text generation, no parsing."

A second property matters as much as the typing itself: answers come back as probability distributions, not just point values. When Jev routes a ticket to "routing," it also reports how much probability mass landed on "wireless" and "security" — the raw material for escalation rules built later in the book.

TypeSafe offers exactly three question types, each returning a different answer shape:

Choice selects from a known set with no inherent order — routing versus wireless versus security don't sit on a scale. Score positions a judgment on a spectrum and can return a value between defined levels, mapping naturally onto things engineers already scale: syslog severities, QoS classes, change-risk tiers. Noul returns the probability itself as the signal, with no separate confidence figure — a Noul of 0.97 for "hardware failure" is answer and certainty in one number, while 0.51 says the model can't separate the cases. All three can be combined in a single request evaluated in parallel against the same state.

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()
syslog_line = "Mar 14 02:17:44 core-rtr-01 %BGP-5-ADJCHANGE: neighbor 192.0.2.14 Down"

response = client.system_one(
    state=syslog_line,
    questions={
        "customer_impacting": Noul(instructions="Loss of customer-facing connectivity"),
        "owning_team": Choice(
            instructions="Which NOC team should own this event",
            criteria={"routing": "BGP/OSPF/IS-IS issues", "wireless": "AP/WLC/RF issues",
                      "security": "Firewall/ACL issues"},
        ),
        "severity": Score(
            instructions="Operational severity of this event",
            criteria=["Informational", "Degraded", "Outage, page on-call now"],
        ),
    },
)

print(response.answers["customer_impacting"].noul)   # 0.94
print(response.answers["owning_team"].choice)         # "routing"
print(response.answers["severity"].score)             # 2.1

TypeSafe AI supplies typed AI primitives rather than a text generator, and Jev is its first System One model, evaluating typed questions against a state through a single POST /v1/systemone endpoint. The three primitives — Choice, Score, and Noul — return a selected label, a position on a scale, and a yes-probability respectively, and all three can be asked about the same state in one parallel request.

System One Versus Generative LLMs

The name comes from cognitive science. In Kahneman's framework, System 1 is fast, automatic, and intuitive; System 2 is slower and deliberate. TypeSafe adopts the distinction directly and builds Jev to emphasize speed and focus. When a senior engineer glances at a syslog line and says "that's wireless, not routing," they're recognizing a pattern in under a second — System 1. Designing a new OSPF area layout, tracing failure modes — that's System 2. Confusing the two is the root of most disappointing AI deployments: System One models are purpose-built for rapid, constrained judgments suitable for software automation, not open-ended reasoning.

Skip TypeSafe and prompt a generative model for JSON instead, and you implicitly rely on six assumptions that fail silently at some rate: validity (no code fences or preamble), schema compliance (no drifting or invented fields), type correctness (no "high" instead of 0.85), value constraints (values stay in range), consistent formatting (stable capitalization and field order), and no extraneous content (no explanatory text around the payload). Unconstrained prompt engineering delivers roughly 80–95% valid output with no guarantee for the rest — a pipeline processing 50,000 events a day at 95% success still throws 2,500 exceptions daily.

The industry's fix is constrained decoding: it compiles a schema into a finite state machine and masks invalid next tokens during generation, so the output is guaranteed valid — "mathematical guarantees instead of statistical ones." Major providers now ship structured-output modes built on this. TypeSafe goes further: because Jev emits typed answers as its native output, there is no prose layer to constrain in the first place.

Parallelization is architectural, not a performance tweak: one primitive's result never becomes hidden context that changes another primitive's result. In a generative agent loop, asking "which team owns this?" before "how severe is it?" can change the severity answer. With System One, judgments are independent — the same property that makes a stateless load balancer easier to reason about than a stateful one.

Figure 1.2: Generative LLM Prose Parsing Loop

Figure 1.3: One Parallel Typed Call

One honest caveat: structured outputs guarantee shape, not truth. The model can still misjudge or produce a plausible but wrong answer. Typed answers eliminate parsing failures; they do not eliminate the need for confidence thresholds and human review.

The third differentiator: System One answers come back with calibrated probabilities. A calibrated probability is one where the number means what it says — across many cases reported at 0.80, roughly 80% should be correct. That enables threshold-based routing: escalate uncertain cases to humans based on calibrated confidence rather than guessing from ambiguous text, the same shape as a routing protocol's administrative distance or a QoS scavenger class. A generative model instead hedges with "fairly confident" — you cannot threshold on an adverb.

answer = response.answers["owning_team"]
if answer.confidence >= 0.85:
    assign_to_queue(answer.choice)
else:
    assign_to_queue("noc_triage_review")

The System One name comes from Kahneman's fast, intuitive mode of thinking, and Jev is built for that mode rather than for deliberation or composition. Parsing prose fails at rates that are unacceptable in a production pipeline, while typed answers with calibrated probabilities let you route on explicit thresholds — but structural guarantees are not accuracy guarantees, and the model can still be confidently wrong.

Why This Matters for Network Operations

Consider two ways of answering "where should this packet go?" The first is a forwarding-table lookup: a longest-prefix match returns a typed next hop in microseconds, with no prose parsed along the way. The second is hiring a consultant to write a design document on optimal traffic engineering — valuable, nuanced, and taking three weeks. You'd never put that in the data plane. A System One call is the forwarding-table lookup of AI judgment; a generative LLM is the consultant's essay, belonging in the control plane where a human reads it. Most disappointing AI-in-NOC projects are essays deployed into data planes: a chat model wired into an alert pipeline, asked to "analyze and recommend," followed by months writing regexes to extract the recommendation. The problem was never the model's intelligence — it was a mismatch between output shape and job.

Once you look for bounded judgments, they're everywhere — the runbook steps that say "determine whether," "assess the," or "assign to the appropriate":

• Syslog triage. "Is this event customer-impacting?" is identical across Cisco, Arista, Juniper, and Aruba even though the string patterns differ — a Noul over the raw log line, instead of a regex library rewritten per vendor and per release.
• Ticket routing. Choosing the assignment group for a free-text ServiceNow incident is a Choice over a fixed set of teams.
• Change review. "How risky is this?" for a proposed Junos or IOS-XE change is a Score against a rubric — routine, elevated, high-risk — with values that can fall between levels.
• Alert deduplication. Is a new Splunk alert the same problem as an incident opened eleven minutes ago? A Noul over a state containing both payloads.
• Customer impact classification. Does this incident need a Salesforce case? Another Noul, with a confidence threshold deciding whether a human confirms first.

Each is a question a competent engineer answers in about two seconds using judgment, not calculation — and each today either consumes human attention or is approximated badly by brittle rules.

The governing architectural principle: System One positions AI as a structured decision-making component inside deterministic software workflows, not an autonomous agent that runs the network. "Keep control flow, deterministic rules, and side effects in code. Break broad judgments into narrow, typed questions with explicit instructions and criteria." Code decides what happens — which API to call, which ticket to open, whether to page someone. The model contributes one judgment your code couldn't compute, as a value, never an action. The model never touches a device, closes a ticket, or pages anyone; code does, having consulted the model like any other data source.

Figure 1.4: Code Owns Control Flow; the Model Supplies Judgment

The other half of the rule: break broad judgments into narrow, typed questions rather than asking one big "analyze this alert and tell me what to do." Three narrow questions combined with an if statement you wrote are auditable; one broad question with uninspectable internal reasoning is not. The model supplies programmable common sense — it knows a BGP notification is more serious than a cleared counter without you encoding that — while the intelligence about your network (escalation matrix, maintenance windows, on-call rotation) stays in your code, in version control.

A System One call belongs in the fast path of an operations pipeline the way a forwarding-table lookup belongs in a data plane, while generative text belongs where a human reads it. Bounded judgments hide throughout NOC workflows — syslog triage, ticket routing, change review, deduplication, customer-impact calls — and the durable design rule is that code keeps control flow and side effects while the model supplies narrow, typed judgments.

How This Guide Is Organized

Every chapter builds toward one system: a multi-vendor NOC triage service. It ingests syslog and alert data from Cisco IOS-XE and NX-OS, Arista EOS, Juniper Junos, and Aruba AOS-CX devices, plus alerts from Splunk and incidents already open in ServiceNow. For each event it asks Jev a small set of typed questions — which team owns this, how severe is it, is it customer-impacting, is it a duplicate — then writes team, severity, and confidence back into ServiceNow, creates or updates a Salesforce case for customer-facing situations, and routes to a human review queue where confidence is low.

Figure 1.5: NOC Triage Flow

Chapters ahead build each piece: Chapter 5 the routing Choice, Chapter 6 the severity Score, Chapter 7 the impact Nouls, Chapter 8 the confidence gate, Chapter 11 the real ServiceNow/Splunk/Salesforce wiring, and Chapter 12 the full assembled pipeline.

Chapter 10 is worth a preview: Jev is fast and intuitive rather than deliberative, with corresponding weaknesses — notably arithmetic and instructions interpreted more literally than intended. This book covers those honestly, because designing around a known limitation is ordinary engineering and discovering one in production is not.

You do not need all of these to follow along. The multi-vendor framing exists because the judgment layer stays the same while syslog dialects differ — precisely the argument for a typed question instead of a per-vendor regex library.

Three prerequisites, and only three: Basic Python — functions, dictionaries, if statements, installing a package with pip; no decorators or async fluency required. JSON — enough to read a nested object like {"choice": "routing", "confidence": 0.91}. REST familiarity — what an HTTP POST is, what an API key does, and the difference between a connection error, an authentication error, and a validation error. What is explicitly not assumed is machine learning — Chapter 2 supplies exactly the background needed, introduced in networking terms first.

This guide is organized around one continuously developed system, a multi-vendor NOC triage service that reads Cisco, Arista, Juniper, Aruba, and Splunk events and writes judgments back into ServiceNow and Salesforce. Twelve chapters move from primitives to confidence gating to full integration, and the only prerequisites are basic Python, JSON literacy, and REST familiarity — no machine-learning background required.

Key Terms