Jev and LLMs: Fast Typed Decisions Plus Generated Language

"""Expense triage demo: Jev decides the outcome, Bedrock writes the email.

Flow for each expense:
1. Jev (TypeSafe) returns typed signals: category, scrutiny (0-3), receipt, policy.
2. A few lines of YOUR code turn those signals into an OUTCOME:
auto_approved | needs_review | rejected
(The 0.5 confidence floor is doc-grounded; value cutoffs are business rules.)
3. Bedrock writes the employee email that matches that outcome.

Jev owns the decision. Bedrock only writes the words.

Docs:
- TypeSafe primitives : https://docs.typesafe.ai/primitives
- Bedrock Converse API: https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html
"""

import boto3
import matplotlib.pyplot as plt
from typesafe_sdk import Choice, Noul, NoulCriteria, Score, TypeSafeClient

# ---- Config ----
TYPESAFE_API_KEY = "YOUR_TYPESAFE_API_KEY"
AWS_PROFILE = None # e.g. "my-profile"; None = default credential chain
AWS_REGION = "us-east-1"
BEDROCK_MODEL_ID = "us.amazon.nova-lite-v1:0"

typesafe = TypeSafeClient(api_key=TYPESAFE_API_KEY)
bedrock = boto3.Session(profile_name=AWS_PROFILE, region_name=AWS_REGION).client(
"bedrock-runtime"
)

# ---- 1. Jev: typed decision ----
def decide(expense: str) -> dict:
r = typesafe.system_one(
state=expense,
questions={
"category": Choice(
instructions="Which expense category is this",
criteria={
"travel": "Flights, hotels, ground transport",
"meals": "Meals, client dinners, team lunches",
"software": "Subscriptions, licenses, tools",
"equipment": "Hardware, devices, office equipment",
"other": "Anything that does not fit the categories above",
},
),
"scrutiny": Score(
instructions="How much scrutiny this expense warrants",
criteria=[
"Routine, clearly within policy",
"Slightly unusual but likely fine",
"Unusual, worth a human look",
"Suspicious or clearly non-compliant",
],
),
"has_receipt": Noul(
instructions="The report states that a receipt or proof of purchase is attached.",
criteria=NoulCriteria(
true="The report explicitly mentions a receipt, invoice, or e-ticket.",
false="The report says no receipt is available, or does not mention one.",
),
),
"policy_compliant": Noul(
instructions="The expense complies with a standard corporate expense policy.",
criteria=NoulCriteria(
true=(
"Has documentation, a clear business purpose, a reasonable "
"amount, and no personal or disallowed items."
),
false=(
"Missing documentation, unclear or personal purpose, an "
"unusually large or cash amount, or disallowed items."
),
),
),
},
)
return {
"category": r.answers["category"].choice,
"scrutiny": r.answers["scrutiny"].score,
"scrutiny_confidence": r.answers["scrutiny"].confidence,
"has_receipt": r.answers["has_receipt"].noul,
"policy_compliant": r.answers["policy_compliant"].noul,
}

# ---- 2. Your code: signals -> outcome ----
# The TypeSafe docs give us two things to build on:
# * The named "0.5 confidence floor" -- below it, the model is genuinely
# uncertain, so we must not act automatically (Confidence page).
# * The three-path pattern: high confidence -> act automatically;
# low confidence -> route to a human; and "thresholds scale with risk"
# (auto-approving is the automatic action, so it gets the strictest bar).
#
# The 0.5 confidence floor below is doc-grounded. The Noul/Score VALUE cutoffs
# (policy < 0.5 to reject, scrutiny bands) are business rules the docs say
# "live in your code" -- tune them against your own data.
CONFIDENCE_FLOOR = 0.5 # from the TypeSafe Confidence docs

def route(d: dict) -> str:
# Reject: the model is confident this is non-compliant or high scrutiny.
if d["policy_compliant"] < 0.5 or d["scrutiny"] >= 2.0:
return "rejected"

# Uncertain read -> send to a human (the docs' "low confidence: do not act").
if d["scrutiny_confidence"] < CONFIDENCE_FLOOR:
return "needs_review"

# Auto-approve only on a confident, clearly-clean expense (strictest bar,
# because this is the automatic action per "thresholds scale with risk").
if (
d["scrutiny"] < 1.0
and d["scrutiny_confidence"] >= 0.8
and d["has_receipt"] >= 0.5
and d["policy_compliant"] >= 0.8
):
return "auto_approved"

# Everything in between -> a human reviews.
return "needs_review"

# ---- 3. Bedrock: write the email for that outcome ----
EMAIL_TONE = {
"auto_approved": "The expense is approved. Warm, brief, confirm reimbursement will proceed.",
"needs_review": "The expense needs a manager review before approval. Polite, ask them to wait.",
"rejected": "The expense cannot be approved as submitted. Respectful, explain it needs changes/resubmission.",
}

def write_email(expense: str, outcome: str) -> str:
system = (
"You write short, professional expense-notification emails to employees. "
"You are told the OUTCOME that was already decided by another system. "
"Do NOT change, question, or re-decide the outcome. Write only the email: "
"a subject line and 3-5 sentences. Do not invent policy details."
)
user = (
f"Outcome: {outcome}\n"
f"Guidance: {EMAIL_TONE[outcome]}\n\n"
f"Expense report:\n{expense}"
)
resp = bedrock.converse(
modelId=BEDROCK_MODEL_ID,
system=[{"text": system}],
messages=[{"role": "user", "content": [{"text": user}]}],
inferenceConfig={"maxTokens": 400, "temperature": 0.4},
)
return resp["output"]["message"]["content"][0]["text"]

# ---- Demo: three expenses, one per outcome ----
# (label, expense text) -- label is used on the chart.
EXPENSES = [
(
"$12 software plugin\n(documented)",
"Software: $12.00 monthly subscription to a code-editor plugin for an "
"engineer's daily development work. Standard pre-approved tool, well within "
"the $50/month software limit. Itemized invoice attached.",
),
(
"$780 flight\n(mildly unusual)",
"Travel: $780 round-trip economy flight SFO-JFK for a customer meeting, "
"booked two days in advance. E-ticket attached, clear business purpose. "
"Slightly above the typical domestic fare, so a quick manager check is warranted.",
),
(
"$4,850 cash\n(no receipt)",
"Other: $4,850 'consulting, paid in cash.' No receipt. Purpose unclear.",
),
]

OUTCOME_COLORS = {
"auto_approved": "#2E8B57", # green
"needs_review": "#E8A200", # amber
"rejected": "#C0392B", # red
}

def make_chart(rows: list) -> None:
"""Render a summary chart of the demo results for the article.

rows: list of dicts with keys label, decision, outcome.
"""
labels = [r["label"] for r in rows]
scrutiny = [r["decision"]["scrutiny"] for r in rows]
receipt = [r["decision"]["has_receipt"] for r in rows]
policy = [r["decision"]["policy_compliant"] for r in rows]
outcomes = [r["outcome"] for r in rows]

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(13, 5))
fig.suptitle("Expense triage: Jev signals + routed outcome",
fontsize=14, fontweight="bold")

x = range(len(labels))

# Left: scrutiny score (0-3), bar colored by the routed outcome.
bar_colors = [OUTCOME_COLORS[o] for o in outcomes]
ax1.bar(x, scrutiny, color=bar_colors, width=0.55)
ax1.set_xticks(list(x))
ax1.set_xticklabels(labels, fontsize=9)
ax1.set_ylim(0, 3.2)
ax1.set_ylabel("scrutiny score (0=routine .. 3=suspicious)")
ax1.set_title("Jev scrutiny score (bar color = outcome)")
ax1.grid(axis="y", linestyle=":", alpha=0.5)
ax1.set_axisbelow(True)
for i, (s, o) in enumerate(zip(scrutiny, outcomes)):
ax1.text(i, s + 0.06, o.replace("_", " "), ha="center", va="bottom",
fontsize=9, fontweight="bold", color=OUTCOME_COLORS[o])

# Right: the two yes/no signals as grouped bars.
w = 0.35
ax2.bar([i - w/2 for i in x], receipt, width=w, color="#4C78A8", label="has_receipt")
ax2.bar([i + w/2 for i in x], policy, width=w, color="#8E6FB0", label="policy_compliant")
ax2.set_xticks(list(x))
ax2.set_xticklabels(labels, fontsize=9)
ax2.set_ylim(0, 1.05)
ax2.axhline(0.5, color="red", linestyle="--", linewidth=1)
ax2.set_ylabel("probability (0 = no .. 1 = yes)")
ax2.set_title("Jev yes/no signals")
ax2.legend(fontsize=9)
ax2.grid(axis="y", linestyle=":", alpha=0.5)
ax2.set_axisbelow(True)

plt.tight_layout(rect=[0, 0, 1, 0.94])
out = "results.png"
plt.savefig(out, dpi=140, bbox_inches="tight")
print(f"\nSaved results chart to {out}")

def main() -> None:
rows = []
for label, expense in EXPENSES:
decision = decide(expense)
outcome = route(decision)
rows.append({"label": label, "decision": decision, "outcome": outcome})

print("=" * 70)
print(f"EXPENSE : {expense}")
print(f"JEV : category={decision['category']} "
f"scrutiny={decision['scrutiny']:.2f} (conf {decision['scrutiny_confidence']:.2f}) "
f"receipt={decision['has_receipt']:.2f} "
f"policy={decision['policy_compliant']:.2f}")
print(f"OUTCOME : {outcome}")
print("-" * 70)
print(write_email(expense, outcome))
print()

make_chart(rows)

if __name__ == "__main__":
main()