The Lexicon
The Lexicon is the set of terms a pack uses to read every question. Each term points to the exact table, value, or document that a word means. With terms, “AR” and “receivables” point to the same measure, however someone phrases the question. The Lexicon has more effect on answer quality than anything else. When a pack’s sources already contain the fact, most wrong answers come from misreading the question. A new document does not fix a misread.
Find it under Lexicon on the pack page, or with edisyl pack vocabulary in the CLI. In an AI chat client, the assistant uses the lexicon_ tools.
What a term is
Section titled “What a term is”A term has a preferred label (“Active supplier”), the other labels people use (“live vendor”), an optional definition, and a binding. The binding is what the word means in the pack. A term can bind to:
- a model, a measure, or a dimension in a data source,
- one value of a dimension,
- a topic drawn from the pack’s documents,
- a line of steering, such as a word that dates a period.
edisyl writes most terms when it compiles your documents and data. It learns more terms from questions. The listing marks each term as confirmed (a person reviewed it) or machine-made. A later compile may reword a machine-made term. It never rewords a confirmed term, and it never brings back a term you removed.
Fix a misread
Section titled “Fix a misread”-
See how the pack reads the question.
previewshows what each word matched and what it’s bound to, without running an ask:The assistant calls
lexicon_preview.“How does the books pack read ‘AR aging for written off invoices’?”
Terminal window edisyl pack vocabulary preview books "AR aging for written off invoices" -
Choose the edit that fits the miss.
Miss Edit A word matches nothing, or the wrong model, measure, or value createa term that points to the right element. If that element already has a term, the new word is added to it as another label.A term is bound to the right thing, but its name or definition is wrong renameordefineTwo terms are spellings of one thing mergeOne word is a label on two terms, and the pack asks which one you meant unlabelthe word from the term it doesn’t meanA machine-made term is junk, such as a topic that uses a file name removeA word means something only beside another (“units” beside orders) createwith--readsand--besideA verb should set the period on one date column (“shipped last quarter” uses the ship date) createwith--date-event -
Make the edit. For example, on an accounting pack:
The assistant calls
lexicon_create.“In the books pack, make ‘AR’ mean the invoices amount due, and also answer to ‘receivables’.”
Terminal window edisyl pack vocabulary create books "AR" --alias "receivables" \--measure invoices.amount_due --definition "Open invoice balance"edisyl pack vocabulary create books "written off" --value invoices.status=voidAsk your agent: “AR” should mean the open invoice balance. Show me the Lexicon edit first.
-
Confirm the fix. Run
previewon the question again. Check that the word now matches the term you meant. Then ask the same question again. Calibration picks up the edit automatically and regrades the questions the edit affects.
Every edit
Section titled “Every edit”Ask for the edit in chat. The assistant calls the matching tool.
| To | The assistant calls |
|---|---|
| List terms, or find terms that mention a word | lexicon_list |
| Read one term | lexicon_term |
| Create a term or add a label | lexicon_create |
| Rename a term or set its definition | lexicon_edit |
| Merge two terms | lexicon_merge |
| Take a label off a term | lexicon_unlabel |
| Confirm a term | lexicon_confirm |
| Remove a term | lexicon_remove |
“Merge ‘monthly actives’ into ‘active wallet’ in the growth-metrics pack.”
edisyl pack vocabulary growth-metrics # every termedisyl pack vocabulary growth-metrics -q churn # terms mentioning "churn"edisyl pack vocabulary show growth-metrics <term-id> # one term: definition, labels, bindings
edisyl pack vocabulary create growth-metrics "ARR" --measure subscriptions.annual_recurring_revenueedisyl pack vocabulary create growth-metrics "units" --reads orders.quantity --beside ordersedisyl pack vocabulary create growth-metrics "shipped" --date-event orders.ship_dateedisyl pack vocabulary define growth-metrics <term-id> "A wallet that swapped in the last 30 days"edisyl pack vocabulary rename growth-metrics <term-id> "Active wallet" --keep-previousedisyl pack vocabulary merge growth-metrics <term-id> --into <other-term-id>edisyl pack vocabulary unlabel growth-metrics <term-id> "traffic"edisyl pack vocabulary confirm growth-metrics <term-id>edisyl pack vocabulary remove growth-metrics <term-id> --confirm --reason "named after a file, not a term"Get model and member names from show and preview. Write them exactly as the pack’s catalog writes them. The CLI refuses an element that the data source’s semantic models don’t contain. Every edit is recorded under your name. Renaming, defining, or merging into a term also confirms it. Edits need manage_pack on the pack. Without it, the CLI returns “not found”.
On a pack built from documents alone
Section titled “On a pack built from documents alone”On these packs, every term is bound to a topic drawn from the documents. The edits that apply are rename, define, merge, unlabel, and remove. The Lexicon helps the pack recognize a reworded question it has answered before. It doesn’t control which passage an answer reads. When a document pack reads the wrong passage, point that kind of question at the right document under # Routing in PACK.md.
What doesn’t belong here
Section titled “What doesn’t belong here”| The problem | Where it goes |
|---|---|
| “Last quarter” is read against today instead of the data’s last day | PACK.md As of: |
| The tone or format of answers | PACK.md # Answer style |
| The pack used the wrong source | PACK.md # Routing |
| A fact no source in the pack states | teach the document that states it |
Don’t teach a definition as a note. A note becomes a document that answers cite. A term changes how every question that uses the word is read.
Start with the terms your team disagrees about, such as “active”, “revenue”, or “region”. A general reading most often gets these wrong.
See edisyl pack vocabulary for every flag.
Was this page helpful?
Thanks for the feedback.
