Repository navigation
Add d1 agent skill guidance #137
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -10,7 +10,7 @@ | |
|
|
||
| Every question you ask a decision model uses one of three types: | ||
|
|
||
| - **Noul**: A yes/no question that returns a probability between 0 and 1. Think of it as a boolean on a sliding scale. "Is this message spam?" might return `0.92`, meaning a 0.92 probability that the answer is yes. | ||
|
|
||
| - **Choice**: A pick-one-from-many question that returns a probability distribution over named options. "Which department should handle this?" might return `{"billing": 0.65, "technical": 0.30, "account": 0.05}`. | ||
|
|
||
|
|
@@ -22,11 +22,11 @@ | |
| |---|---|---| | ||
| | Pick one from a set of unordered categories | **Choice** | Which department handles this ticket? | | ||
| | Rate something along an ordered scale with defined levels | **Score** | How severe is this bug? | | ||
| | Yes or no, where the probability itself is useful | **Noul** | Does this message contain personal data? | | ||
|
|
||
| **Noul vs Score**: A Noul at 0.5 means maximum uncertainty between yes and no. It says nothing about degree or intensity. If you want to measure degree (skill level, frustration, severity), use a Score with defined levels. If you need a yes/no gate, use a Noul. | ||
|
Check warning on line 27 in lfm/models/decision-models.mdx
|
||
|
|
||
| **When the answer could fit more than one type**, think about what your code does next. If it branches on a category, use a Choice. If it compares against a threshold on a continuum, use a Score. If it gates on a boolean, use a Noul. | ||
|
|
||
| ## Setup | ||
|
|
||
|
|
@@ -40,12 +40,42 @@ | |
| export LIQUID_API_KEY="liquid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | ||
| ``` | ||
|
|
||
| ## Agent Skill | ||
|
|
||
| The [Liquid d1 agent skill](https://github.com/Liquid4All/liquid-d1-skills) helps coding agents find opportunities for d1 and integrate it into an application. It can inspect an existing codebase, recommend structured replacements for prompt-and-parse LLM calls, and help design effective Choice, Score, and Noul questions. | ||
|
|
||
| Install the skill for the coding agent you use: | ||
|
|
||
| <Tabs> | ||
| <Tab title="Claude Code"> | ||
| ```bash | ||
| claude plugin marketplace add Liquid4All/liquid-d1-skills | ||
| claude plugin install liquid-d1@liquid-ai | ||
| ``` | ||
| </Tab> | ||
| <Tab title="Codex"> | ||
| ```bash | ||
| codex plugin marketplace add Liquid4All/liquid-d1-skills | ||
| codex plugin add liquid-d1@liquid-ai | ||
| ``` | ||
| </Tab> | ||
| <Tab title="Other agents"> | ||
| ```bash | ||
| npx skills add Liquid4All/liquid-d1-skills --skill liquid-d1 | ||
| ``` | ||
|
|
||
| Choose your agent when prompted. | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| After installation, start a new agent session and try: | ||
|
|
||
| ```text | ||
| Use the Liquid d1 skill to inspect this project for generated-text calls that are really bounded decisions. Recommend d1 replacements for classification, routing, scoring, reranking, and yes/no gates. | ||
|
Contributor
There was a problem hiding this comment. please delete the https://docs.liquid.ai/.well-known/skills/decision-model/skill.md file from the repo when replacing it with an external skill |
||
| ``` | ||
|
|
||
| The skill includes API and SDK references, guidance for Liquid, Vercel AI Gateway, and OpenRouter, and a dependency-free script for testing requests. Keep `LIQUID_API_KEY` in your environment instead of including it in a prompt. | ||
|
|
||
| ## Your First Call | ||
|
|
||
| A single API call contains three things: | ||
|
|
@@ -61,7 +91,7 @@ | |
| -H "Authorization: Bearer $LIQUID_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "model": "d1", | ||
|
Contributor
There was a problem hiding this comment. please replace d1:free across entire documentation (decision-models-guide.mdx + build-a-game-with-decision-models.mdx). i will update it in https://github.com/Liquid4All/cookbook/tree/main/examples/road-decider |
||
| "state": "I have been waiting over three weeks for my order and nobody has responded to my emails. This is completely unacceptable.", | ||
| "questions": { | ||
| "is_complaint": { | ||
|
|
@@ -79,7 +109,7 @@ | |
|
|
||
| ```python | ||
| import os | ||
| from typesafe_sdk import TypeSafeClient, Noul | ||
|
|
||
| client = TypeSafeClient( | ||
| api_key=os.environ["LIQUID_API_KEY"], | ||
|
|
@@ -87,7 +117,7 @@ | |
| ) | ||
|
|
||
| result = client.system_one( | ||
| model="d1", | ||
| state="I have been waiting over three weeks for my order and nobody has responded to my emails. This is completely unacceptable.", | ||
| questions={ | ||
| "is_complaint": Noul( | ||
|
|
@@ -112,7 +142,7 @@ | |
| }); | ||
|
|
||
| const result = await client.systemOne({ | ||
| model: "d1", | ||
| state: "I have been waiting over three weeks for my order and nobody has responded to my emails. This is completely unacceptable.", | ||
| questions: { | ||
| is_complaint: { | ||
|
|
@@ -130,7 +160,7 @@ | |
|
|
||
| ```json | ||
| { | ||
| "model": "d1", | ||
| "answers": { | ||
| "is_complaint": { | ||
| "type": "noul", | ||
|
|
@@ -165,7 +195,7 @@ | |
| -H "Authorization: Bearer $LIQUID_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "model": "d1", | ||
| "state": "You'\''re an absolute idiot and I hope your company goes bankrupt. I'\''m going to find out where you work.", | ||
| "questions": { | ||
| "is_harmful": { | ||
|
|
@@ -181,7 +211,7 @@ | |
| from typesafe_sdk import Noul | ||
|
|
||
| result = client.system_one( | ||
| model="d1", | ||
| state="You're an absolute idiot and I hope your company goes bankrupt. I'm going to find out where you work.", | ||
| questions={ | ||
| "is_harmful": Noul( | ||
|
|
@@ -194,7 +224,7 @@ | |
| <Tab title="TypeScript"> | ||
| ```typescript | ||
| const result = await client.systemOne({ | ||
| model: "d1", | ||
| state: "You're an absolute idiot and I hope your company goes bankrupt. I'm going to find out where you work.", | ||
| questions: { | ||
| is_harmful: { | ||
|
|
@@ -242,7 +272,7 @@ | |
| -H "Authorization: Bearer $LIQUID_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "model": "d1", | ||
| "state": "Hi, I was charged twice for my subscription last month. The amounts are $29.99 on March 3rd and again on March 5th. Can you refund the duplicate charge?", | ||
| "questions": { | ||
| "intent": { | ||
|
|
@@ -262,10 +292,10 @@ | |
| </Tab> | ||
| <Tab title="Python"> | ||
| ```python | ||
| from typesafe_sdk import Choice | ||
|
|
||
| result = client.system_one( | ||
| model="d1", | ||
| state="Hi, I was charged twice for my subscription last month. The amounts are $29.99 on March 3rd and again on March 5th. Can you refund the duplicate charge?", | ||
| questions={ | ||
| "intent": Choice( | ||
|
|
@@ -285,7 +315,7 @@ | |
| <Tab title="TypeScript"> | ||
| ```typescript | ||
| const result = await client.systemOne({ | ||
| model: "d1", | ||
| state: "Hi, I was charged twice for my subscription last month. The amounts are $29.99 on March 3rd and again on March 5th. Can you refund the duplicate charge?", | ||
| questions: { | ||
| intent: { | ||
|
|
@@ -354,7 +384,7 @@ | |
| -H "Authorization: Bearer $LIQUID_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "model": "d1", | ||
| "state": "Our production API is returning 500 errors on every request. All customers are affected. Revenue impact is approximately $12,000 per hour. Started 15 minutes ago.", | ||
| "questions": { | ||
| "urgency": { | ||
|
|
@@ -373,10 +403,10 @@ | |
| </Tab> | ||
| <Tab title="Python"> | ||
| ```python | ||
| from typesafe_sdk import Score | ||
|
|
||
| result = client.system_one( | ||
| model="d1", | ||
| state="Our production API is returning 500 errors on every request. All customers are affected. Revenue impact is approximately $12,000 per hour. Started 15 minutes ago.", | ||
| questions={ | ||
| "urgency": Score( | ||
|
|
@@ -395,7 +425,7 @@ | |
| <Tab title="TypeScript"> | ||
| ```typescript | ||
| const result = await client.systemOne({ | ||
| model: "d1", | ||
| state: "Our production API is returning 500 errors on every request. All customers are affected. Revenue impact is approximately $12,000 per hour. Started 15 minutes ago.", | ||
| questions: { | ||
| urgency: { | ||
|
|
@@ -462,7 +492,7 @@ | |
| -H "Authorization: Bearer $LIQUID_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "model": "d1", | ||
| "state": "{\"message\": \"The checkout page crashes with a white screen whenever I try to apply a promo code. I'\''ve tried three different browsers. This is blocking a $4,200 order for our team and we need to place it before our procurement window closes on Friday.\", \"account\": {\"plan\": \"enterprise\", \"arr\": 52000, \"customer_since\": \"2022-03-15\"}}", | ||
| "questions": { | ||
| "is_bug": { | ||
|
|
@@ -495,7 +525,7 @@ | |
| <Tab title="Python"> | ||
| ```python | ||
| import json | ||
| from typesafe_sdk import Choice, Noul, Score | ||
|
|
||
| ticket = { | ||
| "message": "The checkout page crashes with a white screen whenever I try to apply a promo code. I've tried three different browsers. This is blocking a $4,200 order for our team and we need to place it before our procurement window closes on Friday.", | ||
|
|
@@ -507,7 +537,7 @@ | |
| } | ||
|
|
||
| result = client.system_one( | ||
| model="d1", | ||
| state=json.dumps(ticket), | ||
| questions={ | ||
| "is_bug": Noul( | ||
|
|
@@ -546,7 +576,7 @@ | |
| }; | ||
|
|
||
| const result = await client.systemOne({ | ||
| model: "d1", | ||
| state: JSON.stringify(ticket), | ||
| questions: { | ||
| is_bug: { | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please update this in the decision-models-guide.mdx as well and reference this section (#agent-skills) for information on installation, etc.