ctod 0.9.1 → 0.9.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2019 Metal Sheep
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2019 Metal Sheep
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,251 +1,251 @@
-<br>
-<p align="center"><img style="max-width: 300px" src="./logo.png"></p>
-<h1 align="center">CtoD</h1>
-<h3 align="center">Chat To Data</h3>
-
-<h6 align="center">
-    <a href="https://www.npmjs.com/package/ctod">
-        <img src="https://img.shields.io/npm/v/ctod.svg">
-    </a>
-    <a href="https://github.com/KHC-ZhiHao/ctod">
-        <img src="https://img.shields.io/github/stars/KHC-ZhiHao/ctod.svg?style=social">
-    </a>
-    <br>
-</h6>
-
-<br>
-
-## 摘要
-
-現在我們頻繁的有透過口語化的方式交付任務 LLM 處理並要求回應 JSON 的需求，透過 CtoD 你可以讓這個模式有架構化的進行。
-
-在對話過程中，CtoD 採用 [yup](https://github.com/jquense/yup) 來驗證請求與回復資料是否符合預期，以確保一致性，只要保持這個互動模式，就可以利用在 API 串接或是自動化系統上。
-
-我們還附帶支援 `OpenAI`, `Google`, `Llama3` 等相關 LLM 服務。
-
-## 安裝
-
-npm:
-
-```bash
-npm install ctod
-```
-
-yarn:
-
-```bash
-yarn add ctod
-```
-
-## 快速開始
-
-這個例子示範如何將藥物索引與客戶需求傳遞給聊天機器人，並返回最適合的結果，開發人員可以利用索引結果去資料庫搜尋最適合的藥物給消費者：
-
-```ts
-import { CtoD, OpenAICtodService } from 'ctod'
-    
-const ctod = new CtoD({
-    request: OpenAICtodService.createChatRequestWithJsonSchema({
-        apiKey: 'YOUR_API_KEY',
-        config: {
-            model: 'gpt-4o'
-        }
-    })
-})
-
-const brokerBuilder = ctod.createBrokerBuilder<{
-    indexes: string[]
-    question: string
-}>({
-    install: ({ attach }) => {
-        attach('start', async({ setPreMessages }) => {
-            setPreMessages([
-                {
-                    role: 'system',
-                    content: '你現在是一位擅長分類索引的藥師'
-                }
-            ])
-        })
-    }
-})
-
-const broker = brokerBuilder.create(async({ yup, data, setMessages }) => {
-    const { indexes, question } = data
-    setMessages([
-        {
-            role: 'user',
-            content: [
-                '我有以下索引',
-                `${JSON.stringify(indexes)}`,
-                `請幫我解析"${question}"可能是哪個索引`,
-                '且相關性由高到低排序並給予分數，分數由 0 ~ 1'
-            ]
-        }
-    ])
-    const item = yup.object({
-        name: yup.string().required().meta({
-            jsonSchema: {
-                description: '索引名稱'
-            }
-        }),
-        score: yup.number().required().meta({
-            jsonSchema: {
-                description: '評比分數'
-            }
-        })
-    }).required()
-    return {
-        indexes: yup.array(item).required().meta({
-            jsonSchema: {
-                description: '由高到低排序的索引'
-            }
-        })
-    }
-})
-
-broker.request({
-    indexes: ['胃痛', '腰痛', '頭痛', '喉嚨痛', '四肢疼痛'],
-    question: '喝咖啡，吃甜食，胃食道逆流'
-}).then(e => {
-    console.log('輸出結果：', e.indexes)
-    /*
-        [
-            {
-                name: '胃痛',
-                score: 1
-            },
-            {
-                name: '喉嚨痛',
-                score: 0.7
-            },
-            ...
-        ]
-     */
-}).catch(error => {
-    console.error('Error:', error)
-})
-
-```
-
-##  Plugin
-
-雖然 Broker 本身已經能夠處理大部分的事務，但透過 Plugin 可以協助改善複雜的流程，幫助專案工程化。
-
-每次發送請求時，Broker 會觸發一系列的生命週期，你可以從[原始碼](./lib/broker/openai.ts)中了解每個生命週期的參數與行為，並對其行為進行加工。
-
-現在，假設我們想要設計一個插件，它會在每次對話結束時將訊息備份到伺服器上：
-
-```ts
-import axios from 'axios'
-import { CtoDPlugin } from 'ctod'
-const backupPlugin = new CtoDPlugin({
-    name: 'backup-plugin',
-    // 定義參數為 sendUrl
-    params: yup => {
-        return {
-            sendUrl: yup.string().required()
-        }
-    },
-    // 現階段你可以在執行過程中接收到資訊，資訊結構由這裡定義。
-    receiveData: yup => {
-        return {
-            character: yup.string().required()
-        }
-    },
-    onInstall({ params, attach, receive }) {
-        const store = new Map()
-        // 假設我們有更多的自訂義資訊需要被傳遞進來，可以在 start 階段透過 plugins[key].send({ ... }) 傳遞
-        // 可以從 Applications 分類中的 請機器人角色扮演 觀看案例
-        receive(({ id, context }) => {
-            store.get(id).context = context
-        })
-        // 第一次對話的時候初始化資料
-        attach('start', async({ id }) => {
-            store.set(id, {
-                messages: [],
-                context: null
-            })
-        })
-        // 每次對話完畢後把對話存入狀態
-        attach('talkAfter', async({ id, lastUserMessage }) => {
-            store.get(id).messages.push(lastUserMessage)
-        })
-        // 結束對話後備份資料
-        attach('done', async({ id }) => {
-            await axios.post(params.sendUrl, store.get(id))
-            store.delete(id)
-        })
-    }
-})
-
-const ctod = new CtoD({
-    // ...
-    plugins: () => {
-        return {
-            backup: backupPlugin.use({
-                sendUrl: 'https://api/backup'
-            })
-        }
-    }
-})
-```
-
-## Examples
-
-[基礎用法 - 藥物查詢功能](./examples/openai.ts)
-
-[進階用法 - 請 AI COSPLAY](./examples/plugin.ts)
-
-## Other
-
-[計算 token 的方案: tiktoken](https://www.npmjs.com/package/tiktoken)
-
-## Version History
-
-### 0.9.x
-
-1. OpenAI 的 API 更新，現在可以透過 `setBaseUrl` 方法來設定 baseUrl。
-2. 新增 X Ai Service 的支援
-
-### 0.8.x
-
-1. 正規化 Service 的命名
-2. 新增 Google Service 的支援
-
-### 0.7.x
-
-感謝當今的模型對於json schema的支援，我們不再需要繁瑣的宣告，因此新增了透過註冊 CtoD 的方式來簡化流程。 
-
-### 0.6.x
-
-`bindYupToJsonSchemaToYup` 有一些依賴問題已經被移除，改用以下方案取代：
-
-```ts
-yup.array(item).required().meta({
-    jsonSchema: {
-        description: '由高到低排序的索引'
-    }
-})
-```
-
-1. 新增了 defineYupSchema 讓建立複雜的 Output 更加容易。
-
-### 0.5.x
-
-移除了 JSON Schema Info 的支援，而是透過 [yup-to-json-schema](https://github.com/sodaru/yup-to-json-schema) 進行生成資料格式。
-
-由於 `yup-to-json-schema` 的延伸套件要使用 `yup.string().description()` 方法需要進行全域註冊，在此我們提供了 `bindYupToJsonSchemaToYup` 這個方法，讓使用者可以自行決定是否要進行註冊。
-
-1. 可以在 question 中回應 array，會透過 join 進行合併。
-2. 可以省略 install 參數了。
-
-### 0.4.x
-
-主要是支援 llama3.cpp 或者是其他自建服務上流程的調整。
-
-1. 支援 llama3.cpp server service
-2. 新增 yup to json scheme。
-
-### 0.3.x
-
-為了支援更多平台與自建服務，我們捨棄了完全為了 ChatGPT 客制化的接口，這樣也能完整保持 Broker 與 Plugin 的一致性。
+<br>
+<p align="center"><img style="max-width: 300px" src="./logo.png"></p>
+<h1 align="center">CtoD</h1>
+<h3 align="center">Chat To Data</h3>
+
+<h6 align="center">
+    <a href="https://www.npmjs.com/package/ctod">
+        <img src="https://img.shields.io/npm/v/ctod.svg">
+    </a>
+    <a href="https://github.com/KHC-ZhiHao/ctod">
+        <img src="https://img.shields.io/github/stars/KHC-ZhiHao/ctod.svg?style=social">
+    </a>
+    <br>
+</h6>
+
+<br>
+
+## 摘要
+
+現在我們頻繁的有透過口語化的方式交付任務 LLM 處理並要求回應 JSON 的需求，透過 CtoD 你可以讓這個模式有架構化的進行。
+
+在對話過程中，CtoD 採用 [yup](https://github.com/jquense/yup) 來驗證請求與回復資料是否符合預期，以確保一致性，只要保持這個互動模式，就可以利用在 API 串接或是自動化系統上。
+
+我們還附帶支援 `OpenAI`, `Google`, `Llama3` 等相關 LLM 服務。
+
+## 安裝
+
+npm:
+
+```bash
+npm install ctod
+```
+
+yarn:
+
+```bash
+yarn add ctod
+```
+
+## 快速開始
+
+這個例子示範如何將藥物索引與客戶需求傳遞給聊天機器人，並返回最適合的結果，開發人員可以利用索引結果去資料庫搜尋最適合的藥物給消費者：
+
+```ts
+import { CtoD, OpenAICtodService } from 'ctod'
+    
+const ctod = new CtoD({
+    request: OpenAICtodService.createChatRequestWithJsonSchema({
+        apiKey: 'YOUR_API_KEY',
+        config: {
+            model: 'gpt-4o'
+        }
+    })
+})
+
+const brokerBuilder = ctod.createBrokerBuilder<{
+    indexes: string[]
+    question: string
+}>({
+    install: ({ attach }) => {
+        attach('start', async({ setPreMessages }) => {
+            setPreMessages([
+                {
+                    role: 'system',
+                    content: '你現在是一位擅長分類索引的藥師'
+                }
+            ])
+        })
+    }
+})
+
+const broker = brokerBuilder.create(async({ yup, data, setMessages }) => {
+    const { indexes, question } = data
+    setMessages([
+        {
+            role: 'user',
+            content: [
+                '我有以下索引',
+                `${JSON.stringify(indexes)}`,
+                `請幫我解析"${question}"可能是哪個索引`,
+                '且相關性由高到低排序並給予分數，分數由 0 ~ 1'
+            ]
+        }
+    ])
+    const item = yup.object({
+        name: yup.string().required().meta({
+            jsonSchema: {
+                description: '索引名稱'
+            }
+        }),
+        score: yup.number().required().meta({
+            jsonSchema: {
+                description: '評比分數'
+            }
+        })
+    }).required()
+    return {
+        indexes: yup.array(item).required().meta({
+            jsonSchema: {
+                description: '由高到低排序的索引'
+            }
+        })
+    }
+})
+
+broker.request({
+    indexes: ['胃痛', '腰痛', '頭痛', '喉嚨痛', '四肢疼痛'],
+    question: '喝咖啡，吃甜食，胃食道逆流'
+}).then(e => {
+    console.log('輸出結果：', e.indexes)
+    /*
+        [
+            {
+                name: '胃痛',
+                score: 1
+            },
+            {
+                name: '喉嚨痛',
+                score: 0.7
+            },
+            ...
+        ]
+     */
+}).catch(error => {
+    console.error('Error:', error)
+})
+
+```
+
+##  Plugin
+
+雖然 Broker 本身已經能夠處理大部分的事務，但透過 Plugin 可以協助改善複雜的流程，幫助專案工程化。
+
+每次發送請求時，Broker 會觸發一系列的生命週期，你可以從[原始碼](./lib/broker/openai.ts)中了解每個生命週期的參數與行為，並對其行為進行加工。
+
+現在，假設我們想要設計一個插件，它會在每次對話結束時將訊息備份到伺服器上：
+
+```ts
+import axios from 'axios'
+import { CtoDPlugin } from 'ctod'
+const backupPlugin = new CtoDPlugin({
+    name: 'backup-plugin',
+    // 定義參數為 sendUrl
+    params: yup => {
+        return {
+            sendUrl: yup.string().required()
+        }
+    },
+    // 現階段你可以在執行過程中接收到資訊，資訊結構由這裡定義。
+    receiveData: yup => {
+        return {
+            character: yup.string().required()
+        }
+    },
+    onInstall({ params, attach, receive }) {
+        const store = new Map()
+        // 假設我們有更多的自訂義資訊需要被傳遞進來，可以在 start 階段透過 plugins[key].send({ ... }) 傳遞
+        // 可以從 Applications 分類中的 請機器人角色扮演 觀看案例
+        receive(({ id, context }) => {
+            store.get(id).context = context
+        })
+        // 第一次對話的時候初始化資料
+        attach('start', async({ id }) => {
+            store.set(id, {
+                messages: [],
+                context: null
+            })
+        })
+        // 每次對話完畢後把對話存入狀態
+        attach('talkAfter', async({ id, lastUserMessage }) => {
+            store.get(id).messages.push(lastUserMessage)
+        })
+        // 結束對話後備份資料
+        attach('done', async({ id }) => {
+            await axios.post(params.sendUrl, store.get(id))
+            store.delete(id)
+        })
+    }
+})
+
+const ctod = new CtoD({
+    // ...
+    plugins: () => {
+        return {
+            backup: backupPlugin.use({
+                sendUrl: 'https://api/backup'
+            })
+        }
+    }
+})
+```
+
+## Examples
+
+[基礎用法 - 藥物查詢功能](./examples/openai.ts)
+
+[進階用法 - 請 AI COSPLAY](./examples/plugin.ts)
+
+## Other
+
+[計算 token 的方案: tiktoken](https://www.npmjs.com/package/tiktoken)
+
+## Version History
+
+### 0.9.x
+
+1. OpenAI 的 API 更新，現在可以透過 `setBaseUrl` 方法來設定 baseUrl。
+2. 新增 X Ai Service 的支援
+
+### 0.8.x
+
+1. 正規化 Service 的命名
+2. 新增 Google Service 的支援
+
+### 0.7.x
+
+感謝當今的模型對於json schema的支援，我們不再需要繁瑣的宣告，因此新增了透過註冊 CtoD 的方式來簡化流程。 
+
+### 0.6.x
+
+`bindYupToJsonSchemaToYup` 有一些依賴問題已經被移除，改用以下方案取代：
+
+```ts
+yup.array(item).required().meta({
+    jsonSchema: {
+        description: '由高到低排序的索引'
+    }
+})
+```
+
+1. 新增了 defineYupSchema 讓建立複雜的 Output 更加容易。
+
+### 0.5.x
+
+移除了 JSON Schema Info 的支援，而是透過 [yup-to-json-schema](https://github.com/sodaru/yup-to-json-schema) 進行生成資料格式。
+
+由於 `yup-to-json-schema` 的延伸套件要使用 `yup.string().description()` 方法需要進行全域註冊，在此我們提供了 `bindYupToJsonSchemaToYup` 這個方法，讓使用者可以自行決定是否要進行註冊。
+
+1. 可以在 question 中回應 array，會透過 join 進行合併。
+2. 可以省略 install 參數了。
+
+### 0.4.x
+
+主要是支援 llama3.cpp 或者是其他自建服務上流程的調整。
+
+1. 支援 llama3.cpp server service
+2. 新增 yup to json scheme。
+
+### 0.3.x
+
+為了支援更多平台與自建服務，我們捨棄了完全為了 ChatGPT 客制化的接口，這樣也能完整保持 Broker 與 Plugin 的一致性。