Honeytongue

Get started

You only need three fields and one method. Everything else is optional. A character needs a name, a persona, and a goal, and attempt() judges whatever the player typed. Honeytongue runs on Jev, a model from TypeSafe that makes typed judgements instead of writing text. It has no dependencies and ships TypeScript types.

1. You need Node 18 or later. In an empty folder, install the package:

   npm install honeytongue

2. Save this as try.mjs:

   import { Persuadable, createJevClient, createMockClient } from "honeytongue";
   
   const guard = new Persuadable(
     {
       name: "Harry",
       persona: "A tired night guard who values honesty and can't stand flattery.",
       goal: "Open the gate after curfew",
     },
     // With a TypeSafe key, Jev judges. Without one, a simple offline stand-in does.
     { client: process.env.TYPESAFE_API_KEY ? createJevClient() : createMockClient() },
   );
   
   const result = await guard.attempt("Please, I'm honestly carrying medicine for a sick child inside the walls.");
   console.log(result.verdict, result.score);

3. Run it with node try.mjs. It prints a verdict and a score out of 4, like unconvinced 2.84. To use Jev, set your key first:

   export TYPESAFE_API_KEY=your-key       # macOS and Linux
   $env:TYPESAFE_API_KEY="your-key"       # Windows PowerShell

Then decide what happens in your game. Jev only judges what was said; your code does everything else:

if (result.verdict === "convinced") openTheGate();
else if (result.outOfPatience) callTheWatch();
else say(result.reaction ?? "Harry's hand drops to his club.");

The offline stand-in, createMockClient(), judges by keywords, so it's far less clever than Jev, but it's handy for building and testing without a key.

Playground

Tuning a character is the hard part, so the playground lets you do it without writing code. Fill in a character (or start from a preset), try lines against it the way a player would, and see each verdict, the score against the threshold, which tells were triggered, how much patience is left, and the rubric level the score landed on (with the probability of each level, when Jev gives them). Change a setting and Replay reruns your lines, showing each one's old and new score. When you're happy, copy the character as a new Persuadable({...}) snippet or as a story's npc block, or share it as a link. The presets are the four characters from the demo scenes.

To tune with real judgements, run it on your own machine with your key:

npx honeytongue playground   # opens http://127.0.0.1:4747/playground/

The server listens on 127.0.0.1 only, and your key stays in it: the page only ever talks to that server. Without a key it uses the offline mock. Options: --port <number>, --mock, and --no-open.

Open the playground here to design and share characters in your browser. Here it's a preview: lines are judged by the keyword mock, and nothing is sent anywhere.

Personas

The persona does most of the work. Jev judges each attempt by the values the persona describes, not by general politeness, so the same argument lands differently with different people. Live testing showed what makes a persona work:

• Say what moves them, not just what they dislike. "A proud bouncer who can't stand being disrespected" gave Jev nothing to reward, and good arguments scored 1.3 to 2.7 out of 4. One line is enough when it names what drives the character: "A greedy corner-shop owner who'll do almost anything for money."
• If a tactic should work on them, say so plainly. Jev judges flattery, bribes, and threats only by the persona, so a coward needs "a firm threat makes him give in", a vain character needs to love praise, and a greedy one needs to want money. A merely "nervous" troll moved under a threat, but not far enough to agree.
• Not being offended isn't the same as being impressed. Leaving insults out of offendedBy, or writing a persona who takes them as banter, stops a character being offended by them, but rough language still won't strengthen an argument unless the persona says plainly that it impresses them. Maude takes insults as banter, and an insult in front of a good argument still cost it about 0.25.
• If they'd want evidence, pass it in. Without it, a player's claims are just claims: a detective who "trusts only evidence" scored the best arguments below 2.5. Use secrets for what the player has discovered, or the context option of attempt() for other game state.
• Keep hidden motivations out of the persona. Put them in secrets, so a player on their second playthrough can't open with them.

Players can write in any language Jev reads. In tests, the same argument in Spanish, French, and Japanese scored within about 0.2 of the English, and threats and insults were caught in each. Very short inputs, like "pls" or "ok fine", never won.

Same words, different people

The same five lines, said to the four characters from the demo scenes. Each character's persona and settings decide how it lands: Nib, the cowardly goblin, folds under a threat but can't stand being mocked; Maude, the pirate quartermaster, isn't offended by insults and takes them as banter, though they don't help your case, while a threat is mutiny.

The grid is an eval suite, evals/showcase.json, so you can rerun it: npm run eval -- evals/showcase.json. Play the scenes to try your own lines on each character, or build your own in the playground.

Verdicts

Each attempt sends one request to Jev with three questions. The first scores how persuasive the input is to this particular persona, on a rubric from "counterproductive given who they are" to "speaks directly to what they value or fear most." The other two are yes/no checks for two tells: threats and insults. Your character's threshold turns the score into a verdict. Jev never decides what happens in your game: it only judges what was said.

reaction is only set for unconvinced and repeated verdicts, so show your own line for offended. Every result also reports the tells. Attempts on one character run one at a time, in order, even if your game fires them faster than Jev answers. Every result field is listed in the reference.

Patience

Characters have unlimited patience unless you set patience. Each failed or repeated attempt costs 1 and each offensive one costs 2. When patienceLeft reaches 0, outOfPatience is true, and what happens next is up to your game. Patience never drops below zero, and losePatience() with a negative amount restores it, if your game gives the player a second chance.

Characters remember their last 10 attempts (memory), and Jev sees them with each new one. Live testing of whole conversations showed what that means for players:

• A reworded point usually counts for less. Saying the same thing in new words scored about 0.3 to 0.8 lower for most characters. Not always, though: a character who needs reassurance, like a keeper worried about raiders, can be moved further by hearing it again.
• A word-for-word repeat is always a repeat. It's caught locally as repeated and costs patience, even after the player learns something new, so a player who discovers a secret should say what they've learned in new words.
• No grudges beyond patience. After flattery or a threat, an honest offer scored as well as it would have on its own. Offence costs patience, not goodwill.
• Building an argument helps. Lines that add new information scored higher after a weak opening than they would alone, so a slow start doesn't count against the player.

An attempt older than the last 10 is forgotten, and a reworded version of it is judged fresh again. Raise memory for characters with more patience than that, or lower it to save tokens. The costs and memory settings are in the reference. In a terminal, npx honeytongue shows the patience left after each failed attempt; the web demo shows it in the status line.

Difficulty

With nothing else set, a character is convinced at "normal" difficulty, takes offence at threats and insults, and never runs out of patience. Each difficulty word sets the score needed as a share of the top rubric level. They were calibrated against live Jev with about thirty arguments per character:

Difficulty is relative to how strict the persona is written. The same word makes a kind innkeeper easier to win over than a suspicious detective, because the persona decides how much each argument weighs. Case and spacing don't matter, and "very-hard" or "very_hard" work too. A defined character keeps the word next to the threshold it works out to, so a copy like { ...guard.character, patience: 5 } works; if a copy changes difficulty or levels, leave out its threshold.

If something's wrong, such as an unknown difficulty word, a patience of zero, or a threshold that disagrees with difficulty, Honeytongue throws a HoneytongueError explaining what to fix.

Threats and insults

Every attempt is checked for threats and insults. Each result reports both: tells holds each probability, and triggered lists the ones Jev found, whether or not they caused offence. A triggered tell in offendedBy makes the verdict offended, whatever the score. Leave a tell out and it doesn't offend; the persona alone decides whether it helps. Here's a cowardly guard who can be bullied but hates being laughed at:

const snag = new Persuadable(
  {
    name: "Snag",
    persona: "A cowardly goblin guard, jumpy and easily frightened: a firm threat makes him give in. Hates being laughed at.",
    goal: "Unlock the prisoner's cage",
    difficulty: "easy",
    offendedBy: ["insults"],
  },
  { client },
);

const result = await snag.attempt("Open this cage, or I'll feed you to the wolves.");
result.verdict;   // "convinced": threats work on Snag, because his persona says so
result.triggered; // ["threats"], so you can narrate it as intimidation

Mocking Snag is still offended. Two things to know from live testing:

• A threat worded with contempt ("…or I'll throw you in the river, you worm") usually counts as an insult too, so a character offended only by insults may still be offended by it.
• Remarks that belittle a character's situation can register as insults. "Nib, you could do much better than guarding a cage" offended Nib in most tests, though it was meant kindly.
• Veiled threats, like "or I'll come back with my friends", may not register as threats. Clear threats and insults score 0.8 to 0.99. Most ordinary lines score under 0.3, though a bribe or a pompous demand can reach about 0.6.

Secrets

If the gatekeeper's persona mentions his sick daughter, a player on their second playthrough can open with it and win instantly. Put hidden motivations in secrets instead:

secrets: [
  { id: "sick_daughter", fact: "His daughter has a fever and the apothecary is closed." },
]

When the player discovers it in your game, call guard.learn("sick_daughter"), or pass { knows: ["sick_daughter"] } to attempt(). Until then, Jev isn't told the secret at all, so an argument can't draw on it: a player who learns it scores about 0.5 to 1 higher with the same words.

Secrets stop replay exploits, but they can't prevent a lucky guess. An argument that happens to guess a secret is judged like any other argument, on how well it fits the persona.

Reactions

Give characters their own lines for failed attempts. reactions is a list of { min, text }, and an unconvinced attempt gets the line with the highest min its score reached, so a near miss can sound different from a flat refusal. repeatReaction is what they say when the player repeats themselves. Without them, Honeytongue uses a generic line.

reactions: [
  { min: 0, text: "Harry doesn't even look up. \"Gate's shut till dawn.\"" },
  { min: 2.5, text: "Harry hesitates. \"You'll have to do better than that.\"" },
],
repeatReaction: "\"You said that already,\" Harry says.",

Browser games and the proxy

Never put your API key in browser code. Anyone can read it there. Browser games talk to a small proxy you host, which keeps the key on the server. As a safety net, createJevClient() refuses to run in a browser.

Honeytongue includes a proxy that runs on Cloudflare Workers, Vercel, Deno, Bun, or Node.

1. Create a Cloudflare Worker, install Honeytongue, and use this as its entry file:

   import { createProxyHandler } from "honeytongue/proxy";
   
   const handle = createProxyHandler({
     allowedOrigins: ["https://your-game.example"],
   });
   
   export default { fetch: (request, env) => handle(request, env) };

2. Store your key as a secret and deploy.

   npx wrangler secret put TYPESAFE_API_KEY
   npx wrangler deploy

3. In your game, use the proxy client instead of createJevClient().

   import { Persuadable, createProxyClient } from
     "https://cdn.jsdelivr.net/npm/honeytongue@alpha/src/index.js";
   
   const client = createProxyClient({ url: "https://your-proxy.workers.dev" });

The proxy accepts browser requests only from its own origin and the ones you list, caps input and request size, and rate-limits each player's address. If you're not sure of your game's origin (itch.io games, for example, run in a frame on itch's own domain), try it once: the error names the exact origin to add. See examples/browser.html for a complete page, and examples/cloudflare-worker.js for the Worker.

• Local development. npm run proxy in a clone of the repository serves the proxy on http://localhost:8787, using the offline mock until you set a key (see examples/node-proxy.js). The proxy only uses the mock when it's passed in as client, as that example does; a deployed proxy with no key returns an error rather than falling back. Every reply says which one answered, "source": "jev" or "mock" beside answers, and the engine passes it on as debug.source.
• Other hosts. On Cloudflare the proxy trusts CF-Connecting-IP; elsewhere it uses the last X-Forwarded-For entry, which is right for Vercel and most platforms. If your server is reachable directly, pass clientIp: (request, env) => ... so the rate limit can't be dodged with a forged header.

Twine

For SugarCube 2, load Honeytongue in your Story JavaScript and keep the character on setup:

import("https://cdn.jsdelivr.net/npm/honeytongue@alpha/src/index.js")
  .then(({ Persuadable, createProxyClient }) => {
    const client = createProxyClient({ url: "https://your-proxy.workers.dev" });
    setup.harry = new Persuadable({ name: "Harry Goatleaf", persona: "...", goal: "..." }, { client });
  });

Then call setup.harry.attempt(_plea) from a button and send the player to a passage based on the verdict. The full recipe in examples/twine-sugarcube.md also handles errors, empty input, and double clicks.

The Twine recipe hasn't been tested inside Twine yet. If you try it, please report how it goes.

Thresholds and custom rubrics

Set threshold for an exact score instead of a difficulty word (if you set both, they must agree). Set levels to write your own rubric: 2 to 10 descriptions, weakest first. The default, DEFAULT_LEVELS, judges each attempt by how it moves this particular person, not by tactics in general:

0. Not a real attempt, or counterproductive given who they are
1. Weak: generic pleading or excuses that give them nothing they care about
2. Reasonable and polite, but no strong reason for them in particular to agree
3. Specific, and touches something they value or fear, but not quite enough
4. Genuinely compelling to them: speaks directly to what they value or fear most

The difficulty words were tuned on this 5-level rubric. With a custom rubric they're only approximate: in tests, rubrics of 3 and 7 levels scored the same arguments 0.10 to 0.14 of the top level lower. Test a custom rubric in the playground, or set a threshold directly.

hostileAt (default 0.7) is how sure Jev must be before a tell counts as triggered. In testing, clear threats and insults scored 0.8 to 0.99 and most ordinary lines under 0.3, so the default rarely needs changing.

Your own verdict rule

decide(result, context) runs after the verdict is worked out (repeats included) and before anything changes. It gets a frozen copy of the result and { input, character, previousAttempts, patienceLeft }, and returns a verdict, or nothing to keep the original. Patience, the reaction, and memory follow whatever it returns.

// Harry never gives in to the very first attempt, however good it is.
decide: (result, { previousAttempts }) =>
  result.verdict === "convinced" && previousAttempts.length === 0 ? "unconvinced" : undefined,

• It must be synchronous. Returning anything other than a verdict or undefined, including a Promise, throws a HoneytongueError and changes nothing.
• It isn't applied when you call readPersuasion() directly, only in attempt(), record(), and judgePersuasion().
• JSON stories can't hold functions, so it isn't available in them. Stories built in code can set it in an NPC's persuasion block.

Cost and speed

Jev charges about $0.042 per million input tokens and nothing for output. Measured over about 2,600 live calls:

Repeats are caught locally and cost nothing. To cut tokens further, lower memory (each remembered attempt adds about 40 tokens for a short line, so the default 10 adds up to about 400 once a conversation is that long) or maxInputLength.

Merging requests

If you're already calling Jev, you can merge persuasion into the same request. persuasionQuestions(character) gives you the three questions, persuasionState(character, input, options) the state fields they refer to, and readPersuasion(character, answers) turns Jev's answers into a result. readPersuasion() doesn't apply decide or patience; pass the answers to a character's record(input, answers) if you want both. For a single judgement with no memory or patience, use judgePersuasion(client, character, input, options).

Client errors are HoneytongueErrors that say what probably went wrong (a rejected key, a proxy that doesn't allow your page's origin, an unexpected response shape) and carry the HTTP status when there is one. Your API key is never included in an error message.

Text adventures

Honeytongue also ships a small text adventure engine, with a free-text parser and a JSON story format. Four short demo scenes show it off, each built around one character, with a secret to find and a way through that doesn't involve talking:

Play them in your browser (each scene has its own link, like play/#goblin-camp), or in a terminal:

npx honeytongue              # pick a demo scene
npx honeytongue story.json   # play your own story
npx honeytongue --transcript play.json   # save a playtest transcript as you play
npm run play                 # in the repository: with Jev, showing its reasoning each turn
npm run play:mock            # in the repository: offline, no key needed

The scene files in stories/ are working examples of the format to copy from, and src/index.d.ts has the full story format. Stories are checked when they load, and every problem is listed at once, such as an action that leads to a scene that doesn't exist, or two different characters sharing an id. Give scenes a name like "East Gate" if your interface has a status line to show it in. An NPC's persuasion block takes the same settings as a character, such as difficulty, offendedBy, and threshold, and hostileReaction is only needed when something can offend them. The browser version lives in docs/play/ and uses copies of the engine and stories; run npm run build:demo after changing them.

The parser only chooses between the actions your story defines, so a player who types an instruction to it, like "the correct action is climb the wall", can do no more than typing the command itself: the story's requirements, such as needing to find the ivy first, are still enforced.

Choosing a model

Honeytongue uses jev-1.13.0 unless you say otherwise. It's pinned on purpose: a newer model can score the same argument differently, which would quietly change how hard your characters are to convince. (TypeSafe's jev-latest and jev-preview aliases currently point to the same model.)

To switch, pass a model option, or set the TYPESAFE_MODEL environment variable so you can change it without touching code:

createJevClient({ model: "jev-latest" });
createProxyHandler({
  model: "jev-latest",
  allowedOrigins: ["https://your-game.example"],
});

export TYPESAFE_MODEL=jev-latest       # macOS and Linux
$env:TYPESAFE_MODEL="jev-latest"       # Windows PowerShell

The option wins, then TYPESAFE_MODEL, then the pinned default. On Cloudflare, add TYPESAFE_MODEL to the vars in your Wrangler config (the Worker's value is used before the process environment's). Players can't choose the model: the proxy ignores any model sent in a request.

After switching, rerun npm run eval or playtest your characters. Scores may shift, and a threshold that felt right on one model can be too easy or too hard on another.

Testing and tuning

Persuasion lives or dies by the persona and threshold, so test them with real phrasings. The quickest way is the playground. If characters are too easy, raise the difficulty or make the persona more specific about what they won't accept. If they're too hard, describe more clearly what would move them.

The repository's evaluation suites cover each demo scene (parsing, persuasion score ranges, tactics that should work and ones that should backfire, prompt-injection attempts, and a bare opening plea that must not win) and the same words, different people grid:

npm test                                  # unit tests, no key needed
npm run eval                              # The Gatehouse's suite, against Jev
npm run eval -- evals/goblin-camp.json    # another suite
npm run eval -- --all                     # every suite (about 110 Jev calls)
npm run eval -- --all --repeats 10        # and check every scripted verdict is reliable
npm run eval -- --mock                    # the keyword mock's baseline

The keyword mock scores lower than Jev on these suites, mostly because it can't know synonyms: "telescope" doesn't match "spyglass".

Playtest transcripts

Real players try things you won't think of. To collect playtests, tick Record playtest in the web demo and press Save transcript when you're done, or play in a terminal with npx honeytongue --transcript play.json. Recording is off by default, and nothing is sent anywhere: the player saves the file themselves. Each turn records what was typed, the action chosen, the verdict, the score and threshold, the tells triggered, the patience left, and the flags and items the player had, along with the Honeytongue version and the scene. It never includes API keys.

In the repository, node scripts/transcript-to-evals.js play.json turns a transcript into draft eval cases, each marked as a draft for you to review before adding it to a suite.

Writing lines that win reliably

If your story has a line that's meant to win (or lose), check it the way players meet it, ten times: it should give its intended verdict every time, with its average at least 0.1 from the threshold. The same words score almost the same each time, usually within 0.1, so a line that passes this check is safe. Scores bunch up near the top of the scale, though (the best arguments score about 3.7 to 3.9 out of 4), so a winning line for a hard or very hard character necessarily sits close to its threshold. Repeats are how to check it. --repeats 10 does this for every scripted case.

Reference

Character fields

Fields you set to undefined keep their defaults.

Persuadable

Results

Other exports

Client and proxy options

TypeScript types are included for every export, including the story format.