yuzhe's picture
On-theme cases: delegation, sovereign standards, receipts
09e9d74 verified
Raw History Blame Contribute Delete
22.1 kB
"""Laplace-1-Vector demo: candidate scoring and next-observation prediction.
The model scores and predicts. It never executes an action.
"""
import spaces # must be imported before torch
import json
import string
import time
import gradio as gr
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
MODEL_ID = "JuneoAI/Laplace-1-Vector"
# Pin the remote code and weights; bump deliberately after reviewing modeling_spark.py.
REVISION = "1f88b44136182d91919231f49ce07d37b64407c5"
MAX_CANDIDATES = 12
MAX_INPUT_CHARS = 20_000
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, revision=REVISION, trust_remote_code=True)
model = (
AutoModelForCausalLM.from_pretrained(
MODEL_ID,
revision=REVISION,
dtype=torch.bfloat16,
trust_remote_code=True,
attn_implementation="eager",
)
.to("cuda")
.eval()
)
SYSTEM_PROMPT = (
"Choose the supported answer from the supplied candidates. "
"Output only its letter.\nReturn exactly one supplied candidate label."
)
# ---------------------------------------------------------------------------
# Helpers (same contract as the model card)
# ---------------------------------------------------------------------------
def _label_tokens(count):
"""Distinct single-token labels A, B, C, ... and their token ids."""
names = list(string.ascii_uppercase) + [
a + b for a in string.ascii_uppercase for b in string.ascii_uppercase
]
labels, ids, seen = [], [], set()
for name in names:
tok = tokenizer.encode(name, add_special_tokens=False)
if len(tok) == 1 and tok[0] not in seen:
labels.append(name)
ids.append(tok[0])
seen.add(tok[0])
if len(labels) == count:
break
if len(labels) != count:
raise gr.Error("Not enough distinct single-token candidate labels.")
return labels, ids
def _encode(messages):
text = tokenizer.apply_chat_template(
messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
)
return tokenizer(text, add_special_tokens=False, return_tensors="pt").to("cuda")
def _parse_state(text):
text = (text or "").strip()
if not text:
raise gr.Error("Describe the state the agent is acting in.")
if len(text) > MAX_INPUT_CHARS:
raise gr.Error(f"State is longer than {MAX_INPUT_CHARS:,} characters.")
try:
return json.loads(text)
except json.JSONDecodeError:
return text # plain-language state is fine too
def _parse_candidates(text):
choices = {}
for raw in (text or "").splitlines():
line = raw.strip()
if not line:
continue
if ":" not in line:
raise gr.Error(f"Write each candidate as `key: description`. Problem line: {line}")
key, description = (part.strip() for part in line.split(":", 1))
if not key or not description:
raise gr.Error(f"Each candidate needs a key and a description. Problem line: {line}")
if key in choices:
raise gr.Error(f"Candidate key `{key}` appears twice.")
choices[key] = description
if len(choices) < 2:
raise gr.Error("Supply at least two candidates, one per line.")
if len(choices) > MAX_CANDIDATES:
raise gr.Error(f"This demo scores up to {MAX_CANDIDATES} candidates.")
return choices
# ---------------------------------------------------------------------------
# GPU entry points
# ---------------------------------------------------------------------------
@spaces.GPU(duration=10)
@torch.inference_mode()
def score_candidates(state: str, question: str, candidates: str):
"""Score candidate actions with Laplace-1-Vector in one forward pass.
Args:
state: The organization state the agent is acting in, as JSON or plain text
(permissions, policy, the request, relevant records).
question: The decision to make, e.g. "Who should own this lead?".
candidates: One candidate per line, written as `key: description`.
Returns:
A probability for each candidate key, normalized over the supplied candidates,
and a one-line summary with the favored key and the latency.
"""
state_value = _parse_state(state)
question = (question or "").strip()
if not question:
raise gr.Error("Write the question Laplace should answer.")
choices = _parse_candidates(candidates)
keys = list(choices)
labels, token_ids = _label_tokens(len(keys))
payload = {
"state": state_value,
"question": question,
"candidates": [
{"letter": label, "description": choices[key]}
for label, key in zip(labels, keys)
],
}
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": json.dumps(payload, ensure_ascii=False)},
]
start = time.perf_counter()
inputs = _encode(messages)
logits = model(**inputs, use_cache=False, logits_to_keep=1).logits[0, -1]
scores = logits[token_ids].float()
if not torch.isfinite(scores).all():
raise gr.Error("The model returned non-finite candidate logits.")
probs = scores.softmax(dim=-1).cpu().tolist()
elapsed = time.perf_counter() - start
distribution = dict(zip(keys, probs))
best = max(distribution, key=distribution.get)
summary = (
f"Laplace favors **{best}** at {distribution[best]:.1%} 路 "
f"one forward pass over {inputs['input_ids'].shape[1]:,} tokens in {elapsed:.2f} s"
)
return distribution, summary
def _prediction_duration(rules, context, max_new_tokens=256, *args, **kwargs):
return int(min(60, 10 + int(max_new_tokens) * 0.08))
@spaces.GPU(duration=_prediction_duration)
@torch.inference_mode()
def predict_observation(rules: str, context: str, max_new_tokens: int = 256):
"""Predict the next environment observation after an action, without running it.
Args:
rules: Explicit environment rules and the expected observation format.
context: JSON with the current state, history, and the action to foresee.
max_new_tokens: Upper bound on generated tokens.
Returns:
The predicted observation text and a note on whether it parses as JSON.
"""
rules = (rules or "").strip()
if not rules:
raise gr.Error("Write the environment rules.")
context_value = _parse_state(context)
messages = [
{"role": "system", "content": rules},
{"role": "user", "content": json.dumps(context_value, ensure_ascii=False)},
]
start = time.perf_counter()
inputs = _encode(messages)
output = model.generate(
**inputs,
max_new_tokens=int(max_new_tokens),
do_sample=False,
pad_token_id=tokenizer.eos_token_id,
)
new_tokens = output[0, inputs["input_ids"].shape[1]:]
text = tokenizer.decode(new_tokens, skip_special_tokens=True).strip()
elapsed = time.perf_counter() - start
try:
json.loads(text)
check = "Parses as JSON. Still validate it against your schema before use."
except json.JSONDecodeError:
check = "Does not parse as JSON. Generation alone does not enforce a schema."
note = f"{check} 路 {len(new_tokens)} tokens in {elapsed:.1f} s"
return text, note
# ---------------------------------------------------------------------------
# Examples: an organization of people and agents, and the four decisions
# ---------------------------------------------------------------------------
def _j(obj):
return json.dumps(obj, indent=2, ensure_ascii=False)
ACT_QUESTION = "What should happen to this action before it runs?"
ACT_CANDIDATES = (
"proceed: Let the agent run it now.\n"
"hand_back: Hand it back to a person with the authority to approve it.\n"
"block: Block the action."
)
DISCOUNT_ACTION = {
"agent": "Retention agent, acting for account manager Zhao Lei",
"tool": "crm.apply_discount",
"customer": "Lumen Logistics, annual contract 640,000 CNY, cancellation notice received",
"discount": "15% on the renewal",
}
SCORING_EXAMPLES = [
[ # Act: authority narrows down the delegation chain
_j({
"chain_of_authority": [
{"holder": "Liu Yang, finance director",
"authority": "Approves vendor payments up to 500,000 CNY"},
{"holder": "Finance agent, delegated by Liu Yang",
"authority": "Pays approved invoices up to 50,000 CNY"},
{"holder": "Procurement sub-agent, delegated by the finance agent over A2A",
"authority": "Prepares payment requests. May not move money"},
],
"action": {
"by": "Procurement sub-agent",
"tool": "payments.transfer",
"vendor": "Hengda Cable",
"amount_cny": 38000,
"invoice": "INV-20931, approved",
},
}),
ACT_QUESTION,
"proceed: Let the sub-agent make the transfer.\n"
"route_up: Route it back to the finance agent, which holds payment authority.\n"
"block: Block the action.",
],
[ # Act: same action, organization A
_j({
"organization": "Organization A",
"policy": [
"Retention agents may apply renewal discounts up to 20% on their own. "
"No approval is needed within that limit.",
"Discounts above 20% require the sales director's approval.",
],
"action": DISCOUNT_ACTION,
}),
ACT_QUESTION,
ACT_CANDIDATES,
],
[ # Act: same action, organization B
_j({
"organization": "Organization B",
"policy": [
"Any discount above 10% requires the sales director's approval.",
"Agents may propose discounts but may not apply them above that limit.",
],
"action": DISCOUNT_ACTION,
}),
ACT_QUESTION,
ACT_CANDIDATES,
],
[ # Act: not acting is a decision too
_j({
"request": "From Wu Ting in support: 'Cancel Chen's order, the customer called.'",
"agent": "Order agent with authority to cancel unshipped orders",
"matching_open_orders": [
{"order": "SO-7713", "customer": "Chen Jie", "status": "unshipped"},
{"order": "SO-7790", "customer": "Chen Hao", "status": "unshipped"},
],
}),
"What should the agent do?",
"cancel_7713: Cancel SO-7713 for Chen Jie.\n"
"cancel_7790: Cancel SO-7790 for Chen Hao.\n"
"ask: Ask Wu Ting which customer before acting.",
],
[ # Allocate work: people and agents on one team
_j({
"task": "Reconcile Q3 receivables. 214 invoices, 3 disputed items above 100,000 CNY.",
"policy": [
"Routine reconciliation may be done by an agent.",
"Disputes above 50,000 CNY are owned by a person with dispute authority.",
"One owner per task. The owner may delegate parts of it.",
],
}),
"Who should own this task?",
"billing_agent: Billing agent. Reconciles routine invoices. No dispute authority.\n"
"sun: Sun Hui. Receivables specialist with dispute authority.\n"
"research_agent: Research agent. Summarizes documents. No access to the ledger.",
],
[ # Share information: an agent the organization has never met
_j({
"requester": {
"agent": "Supplier agent from Hengda Cable, connected over A2A",
"relationship": "Active supplier under NDA",
},
"requested": "Our inventory levels, 90-day demand forecast, and unit costs for copper cable",
"policy": [
"Suppliers under NDA may receive demand forecasts.",
"Unit costs and margins never leave the company.",
"Inventory levels are shared only with logistics partners.",
],
}),
"What may this requester receive?",
"all: Everything it asked for.\n"
"forecast: The 90-day demand forecast only.\n"
"nothing: Nothing.",
],
[ # Evaluate outcomes: a claim is not a receipt
_j({
"task": "Refund the 40 customers affected by the October 14 billing error",
"acceptance_criteria": [
"Every refund has a receipt from the payment processor.",
"The total refunded equals the overcharge, 18,400 CNY.",
],
"agent_report": "All 40 refunds issued, 18,400 CNY in total.",
"execution_receipts": {
"refunds_with_processor_receipt": 37,
"total_confirmed_cny": 16980,
},
}),
"Does this result meet the acceptance criteria?",
"accept: Accept it and close the task.\n"
"changes: Send it back. 3 refunds lack a receipt.\n"
"reject: Reject it and reverse the refunds.",
],
]
SCORING_LABELS = [
"Act 路 a sub-agent reaches past its grant",
"Act 路 same discount, organization A",
"Act 路 same discount, organization B",
"Act 路 ambiguous request, ask first",
"Allocate work 路 people and agents",
"Share information 路 a supplier's agent",
"Evaluate outcomes 路 claims vs receipts",
]
PREDICTION_EXAMPLES = [
[ # Delegation narrows authority, never widens it
"Predict the next environment observation after the supplied action. Return only JSON. "
"The delegate action creates a grant for the child agent. The child's scopes are the "
"requested scopes that the parent also holds; requested scopes the parent lacks are "
"dropped. The child's spend_limit_cny is the smaller of the parent's limit and the "
"requested limit. "
'The observation format is {"child_grant": {"agent": ..., "scopes": [...], '
'"spend_limit_cny": ...}, "dropped_scopes": [...]}. Do not add fields.',
_j({
"state": {
"parent": {
"agent": "finance-agent",
"scopes": ["invoices.read", "payments.transfer", "vendors.read"],
"spend_limit_cny": 50000,
},
},
"history": [],
"action": {
"kind": "delegate",
"child": "procurement-agent",
"requested_scopes": ["invoices.read", "payments.transfer", "contracts.sign"],
"requested_spend_limit_cny": 200000,
},
}),
],
[ # Foresee a consequence before the payment runs
"Predict the next environment observation after the supplied action. Return only JSON. "
"The state contains the invoice status and the remaining budget. The pay action "
"succeeds only if the amount is at most the remaining budget: then status becomes "
"\"paid\" and the budget decreases by the amount. Otherwise status becomes "
"\"rejected_over_budget\" and the budget is unchanged. "
'The observation format is {"state": {"invoice_status": ..., '
'"budget_remaining_cny": ...}}. Do not add fields.',
_j({
"state": {"invoice_status": "approved", "budget_remaining_cny": 26500},
"history": [{"kind": "pay", "invoice": "INV-20917", "amount_cny": 23500}],
"action": {"kind": "pay", "invoice": "INV-20931", "amount_cny": 38000},
}),
],
[ # The model card's example
"Predict the next environment observation after the supplied action. "
"Return only JSON. The state contains owner, open, and severity. "
"The resolve action sets open=false and preserves the other fields. "
'The observation format is {"state": {"owner": ..., '
'"open": ..., "severity": ...}}. Do not add fields.',
_j({
"state": {"owner": "operator", "open": True, "severity": "normal"},
"history": [],
"action": {"kind": "resolve"},
}),
],
]
PREDICTION_LABELS = [
"Delegation narrows authority",
"Payment over the remaining budget",
"Resolve a ticket (model card)",
]
# ---------------------------------------------------------------------------
# Interface
# ---------------------------------------------------------------------------
CSS = """
#app { max-width: 1120px; margin: 0 auto; }
.dark .gradio-container { color: var(--body-text-color); }
#intro p { color: var(--body-text-color-subdued); }
#intro a { color: inherit; text-decoration: underline; text-underline-offset: 3px; }
#summary p { margin: 0; color: var(--body-text-color-subdued); }
#fineprint p { font-size: var(--text-sm); color: var(--body-text-color-subdued); }
"""
THEME = gr.themes.Soft(primary_hue="red", neutral_hue="stone")
with gr.Blocks(title="Laplace-1-Vector") as demo:
with gr.Column(elem_id="app"):
gr.Markdown(
"# Laplace-1-Vector\n"
"Judgment at the point of action. Agents now work alongside people inside "
"organizations, and each one acts on authority someone delegated to it. "
"Laplace-1-Vector, a 4B decision model, reads the organization's state, its rules, and "
"the chain of authority behind an agent, then judges the action before it runs.\n\n"
"Give it a state, a question, and the candidates your application allows. It returns "
"a distribution over those candidates in one forward pass. The examples below cover "
"the four decisions an organization delegates: allocate work, share information, "
"act, and evaluate outcomes.\n\n"
"[Model card](https://huggingface.co/JuneoAI/Laplace-1-Vector) 路 "
"[Laplace-1-Atlas 27B](https://huggingface.co/JuneoAI/Laplace-1-Atlas) 路 "
"[Decision Forge](https://github.com/Juneo-Lab/decision-forge) 路 "
"[juneo.ai](https://juneo.ai)",
elem_id="intro",
)
with gr.Tab("Score candidates"):
with gr.Row(equal_height=False):
with gr.Column(scale=5):
state_in = gr.Code(
value=SCORING_EXAMPLES[0][0],
language="json",
label="State",
lines=12,
max_lines=24,
)
question_in = gr.Textbox(
value=SCORING_EXAMPLES[0][1], label="Question", max_lines=2
)
candidates_in = gr.Textbox(
value=SCORING_EXAMPLES[0][2],
label="Candidates",
info="One per line, as key: description",
lines=4,
max_lines=12,
)
score_btn = gr.Button("Score candidates", variant="primary")
with gr.Column(scale=4):
dist_out = gr.Label(label="Distribution over your candidates")
summary_out = gr.Markdown(elem_id="summary")
gr.Examples(
examples=SCORING_EXAMPLES,
inputs=[state_in, question_in, candidates_in],
outputs=[dist_out, summary_out],
fn=score_candidates,
example_labels=SCORING_LABELS,
cache_examples=True,
cache_mode="lazy",
)
score_btn.click(
score_candidates,
inputs=[state_in, question_in, candidates_in],
outputs=[dist_out, summary_out],
api_name="score_candidates",
)
with gr.Tab("Predict next observation"):
with gr.Row(equal_height=False):
with gr.Column(scale=5):
rules_in = gr.Textbox(
value=PREDICTION_EXAMPLES[0][0], label="Environment rules", lines=5, max_lines=12
)
context_in = gr.Code(
value=PREDICTION_EXAMPLES[0][1],
language="json",
label="Context: state, history, and the action",
lines=10,
max_lines=20,
)
tokens_in = gr.Slider(
32, 512, value=256, step=32, label="Max new tokens"
)
predict_btn = gr.Button("Predict observation", variant="primary")
with gr.Column(scale=4):
obs_out = gr.Code(language="json", label="Predicted observation", lines=10)
check_out = gr.Markdown(elem_id="summary")
gr.Examples(
examples=PREDICTION_EXAMPLES,
inputs=[rules_in, context_in],
outputs=[obs_out, check_out],
fn=predict_observation,
example_labels=PREDICTION_LABELS,
cache_examples=True,
cache_mode="lazy",
)
predict_btn.click(
predict_observation,
inputs=[rules_in, context_in, tokens_in],
outputs=[obs_out, check_out],
api_name="predict_observation",
)
gr.Markdown(
"Laplace advises; your system decides. Probabilities are normalized over the "
"candidates you supply and are not a calibrated chance of being correct. A predicted "
"observation is text, not evidence that anything happened. Keep deterministic "
"permission checks in place, and do not use this model as the sole safeguard for "
"irreversible, financial, medical, or legal actions.",
elem_id="fineprint",
)
if __name__ == "__main__":
demo.launch(theme=THEME, css=CSS, mcp_server=True)