B3 Dict

An AI-first dictionary for the terminal. Ask about English words, idioms, or usage in mixed Vietnamese/English; the answer comes back in Vietnamese. Freeform questions, not a bilingual lookup table: "is draggable a real word?", "take for granted nghĩa là gì?", or paste a joke and ask how to read it.

Getting Started

Needs Node 22 or newer and an API key from OpenRouter, OpenAI or Fireworks.

npm install
cp .env.example .env       # then paste your key into .env
npm run build
npm link                   # puts `b3dict` on your PATH

b3dict                     # interactive: type a question, press enter
b3dict "take for granted"  # one-shot: print the answer and exit
b3dict "Is draggable an English word?"
b3dict "they are your to decide if they are good to go"   # check a sentence you wrote
b3dict "Agreed or Agree? Approved or Approve?"            # which one to use
b3dict "take for granted" --fresh    # skip the stored answer, ask again
b3dict "draggable" --json            # raw answer envelope

Answers are stored in data/b3-dict.db, so asking the same thing twice costs nothing the second time. .env and data/ live in this folder no matter where you run b3dict from. settings.json sits next to .env once you pick a model in the TUI. Installed from npm instead of a checkout, they move to ~/.local/share/b3-dict (or $XDG_DATA_HOME/b3-dict); set B3_DICT_HOME to put them anywhere else.

Want to see what each call cost and how long it took? Put your own LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_BASE_URL in .env and every model call shows up in your Langfuse project, question and answer included. b3dict ships no keys of its own, so without yours it sends nothing.

In the interactive screen, paste works for multiline questions. Once an answer is up: r asks again, s saves it to the wordbook, esc goes back, q quits. Press ↓ from the question box to reach History (everything you've asked) and Wordbook (what you starred); enter reopens a stored answer without calling the model, s stars or unstars the row. The same menu has Model, where you pick which model answers, and which provider when both keys are in .env (remembered next time, unless B3_DICT_PROVIDER or B3_DICT_MODEL is set), and Help, which lists the keys and where your files are. From the empty question box, esc or ctrl+c quits.

Seeing Fireworks costs in Langfuse

Traces arrive with token counts but an empty cost column for Fireworks models. Langfuse has no built-in price for them, so you add one yourself under Settings → Models in your Langfuse project. Two things go wrong easily:

• Match the full model id. b3dict sends accounts/fireworks/models/minimax-m3, not minimax-m3. A pattern of (?i)^(minimax-m3)$ matches nothing and the cost stays empty.
• Prices are per token, not per million. 0.3 means $0.30 for every token, which turns a tenth-of-a-cent lookup into hundreds of dollars.

For minimax-m3 at $0.30 in and $1.20 out per million tokens:

Fireworks also reports cached prompt tokens under the usage key input_cached_tokens. Without a price row for that key those tokens count as free, so add one with Fireworks' cached rate for your model. Every other Fireworks model needs its own definition the same way; take the rates from the Fireworks pricing page.

A definition only prices traces that arrive after you save it. Older ones keep their empty cost.

Development

npm run typecheck          # Typecheck
npm run lint               # Lint
npm test                   # Run tests
npm run dev -- "<query>"   # Run from source without building
npm run typecheck && npm run lint && npm test && npm run build   # Before creating a PR

Architecture

useReducer-based Model → Update → View. State in a single reducer, components dispatch actions, side effects in useEffect. Mirrors Bubbletea's discipline in a React idiom.

Documentation

• CLAUDE.md — Development guide
• GLOSSARY.md — Domain vocabulary
• docs/PRD.md — Product requirements
• docs/USER-STORIES.md — User stories and acceptance criteria
• docs/INK-TUI-UI-UX-GUIDELINE.md — Ink TUI design system and component specs
• docs/INK-TUI-TECH-SPECS.md — Technical stack and configuration

License

ISC