ctod 0.9.4 → 1.0.0

package/.nvmrc

@@ -0,0 +1 @@
+24

package/README.md

@@ -13,17 +13,22 @@
     <br>
 </h6>
 
+<p align="center">
+    English  | 
+    <a href="./README_ZH.md">繁體中文</a>
+</p>
+
 <br>
 
-## 摘要
+## Summary
 
-現在我們頻繁的有透過口語化的方式交付任務 LLM 處理並要求回應 JSON 的需求，透過 CtoD 你可以讓這個模式有架構化的進行。
+Nowadays, we frequently need to assign tasks to LLMs in a conversational manner and request JSON responses. CtoD allows you to structure this pattern in an organized way.
 
-在對話過程中，CtoD 採用 [yup](https://github.com/jquense/yup) 來驗證請求與回復資料是否符合預期，以確保一致性，只要保持這個互動模式，就可以利用在 API 串接或是自動化系統上。
+During the conversation, CtoD uses [zod](https://zod.dev/basics) to validate whether the request and response data meet expectations, ensuring consistency. By maintaining this interaction pattern, you can utilize it for API integration or automation systems.
 
-我們還附帶支援 `OpenAI`, `Google`, `Llama3` 等相關 LLM 服務。
+We also support mainstream LLM services such as `OpenAI`, `Google`, `X`, `anthropic`, `llama.cpp`, both cloud-based and local.
 
-## 安裝
+## Installation
 
 npm:
 
@@ -37,9 +42,9 @@ yarn:
 yarn add ctod
 ```
 
-## 快速開始
+## Quick Start
 
-這個例子示範如何將藥物索引與客戶需求傳遞給聊天機器人，並返回最適合的結果，開發人員可以利用索引結果去資料庫搜尋最適合的藥物給消費者：
+This example demonstrates how to pass a medication index and customer requirements to a chatbot and return the most suitable results. Developers can use the index results to search the database for the most appropriate medication for consumers:
 
 ```ts
 import { CtoD, OpenAICtodService } from 'ctod'
@@ -62,60 +67,48 @@ const brokerBuilder = ctod.createBrokerBuilder<{
             setPreMessages([
                 {
                     role: 'system',
-                    content: '你現在是一位擅長分類索引的藥師'
+                    content: 'You are a pharmacist skilled at categorizing indexes'
                 }
             ])
         })
     }
 })
 
-const broker = brokerBuilder.create(async({ yup, data, setMessages }) => {
+const broker = brokerBuilder.create(async({ zod, data, setMessages }) => {
     const { indexes, question } = data
     setMessages([
         {
             role: 'user',
             content: [
-                '我有以下索引',
+                'I have the following indexes',
                 `${JSON.stringify(indexes)}`,
-                `請幫我解析"${question}"可能是哪個索引`,
-                '且相關性由高到低排序並給予分數，分數由 0 ~ 1'
+                `Please help me analyze which index "${question}" might belong to`,
+                'Rank by relevance from high to low and give scores, scores range from 0 to 1'
             ]
         }
     ])
-    const item = yup.object({
-        name: yup.string().required().meta({
-            jsonSchema: {
-                description: '索引名稱'
-            }
-        }),
-        score: yup.number().required().meta({
-            jsonSchema: {
-                description: '評比分數'
-            }
-        })
-    }).required()
+    const item = zod.object({
+        name: zod.string().describe('Index name'),
+        score: zod.number().describe('Score')
+    })
     return {
-        indexes: yup.array(item).required().meta({
-            jsonSchema: {
-                description: '由高到低排序的索引'
-            }
-        })
+        indexes: zod.array(item).describe('Indexes sorted from high to low')
     }
 })
 
 broker.request({
-    indexes: ['胃痛', '腰痛', '頭痛', '喉嚨痛', '四肢疼痛'],
-    question: '喝咖啡，吃甜食，胃食道逆流'
+    indexes: ['Stomach pain', 'Back pain', 'Headache', 'Sore throat', 'Limb pain'],
+    question: 'Drinking coffee, eating sweets, acid reflux'
 }).then(e => {
-    console.log('輸出結果：', e.indexes)
+    console.log('Output:', e.indexes)
     /*
         [
             {
-                name: '胃痛',
+                name: 'Stomach pain',
                 score: 1
             },
             {
-                name: '喉嚨痛',
+                name: 'Sore throat',
                 score: 0.7
             },
             ...
@@ -124,53 +117,52 @@ broker.request({
 }).catch(error => {
     console.error('Error:', error)
 })
-
 ```
 
-##  Plugin
+## Plugin
 
-雖然 Broker 本身已經能夠處理大部分的事務，但透過 Plugin 可以協助改善複雜的流程，幫助專案工程化。
+While Broker itself can handle most tasks, Plugins can help improve complex workflows and assist in project engineering.
 
-每次發送請求時，Broker 會觸發一系列的生命週期，你可以從[原始碼](./lib/broker/openai.ts)中了解每個生命週期的參數與行為，並對其行為進行加工。
+Each time a request is sent, Broker triggers a series of lifecycles. You can understand the parameters and behaviors of each lifecycle from the [source code](./lib/broker/chat.ts) and modify their behaviors.
 
-現在，假設我們想要設計一個插件，它會在每次對話結束時將訊息備份到伺服器上：
+Now, let's say we want to design a plugin that backs up messages to the server after each conversation ends:
 
 ```ts
 import axios from 'axios'
 import { CtoDPlugin } from 'ctod'
 const backupPlugin = new CtoDPlugin({
     name: 'backup-plugin',
-    // 定義參數為 sendUrl
-    params: yup => {
+    // Define parameter as sendUrl
+    params: zod => {
         return {
-            sendUrl: yup.string().required()
+            sendUrl: zod.string()
         }
     },
-    // 現階段你可以在執行過程中接收到資訊，資訊結構由這裡定義。
-    receiveData: yup => {
+    // You can receive information during execution, and the information structure is defined here.
+    receiveData: zod => {
         return {
-            character: yup.string().required()
+            character: zod.string()
         }
     },
     onInstall({ params, attach, receive }) {
         const store = new Map()
-        // 假設我們有更多的自訂義資訊需要被傳遞進來，可以在 start 階段透過 plugins[key].send({ ... }) 傳遞
-        // 可以從 Applications 分類中的 請機器人角色扮演 觀看案例
+        // If we have more custom information that needs to be passed in, it can be passed through plugins[key].send({ ... }) during the start phase
+        // See the "Ask the bot to roleplay" case in the Applications category
         receive(({ id, context }) => {
             store.get(id).context = context
         })
-        // 第一次對話的時候初始化資料
+        // Initialize data on first conversation
         attach('start', async({ id }) => {
             store.set(id, {
                 messages: [],
                 context: null
             })
         })
-        // 每次對話完畢後把對話存入狀態
+        // Save the conversation to state after each conversation
         attach('talkAfter', async({ id, lastUserMessage }) => {
             store.get(id).messages.push(lastUserMessage)
         })
-        // 結束對話後備份資料
+        // Backup data after conversation ends
         attach('done', async({ id }) => {
             await axios.post(params.sendUrl, store.get(id))
             store.delete(id)
@@ -192,60 +184,63 @@ const ctod = new CtoD({
 
 ## Examples
 
-[基礎用法 - 藥物查詢功能](./examples/openai.ts)
+[Basic Usage - Medication Query Function](./examples/openai.ts)
 
-[進階用法 - 請 AI COSPLAY](./examples/plugin.ts)
+[Advanced Usage - Ask AI to COSPLAY](./examples/plugin.ts)
 
-## Other
+## Version History
 
-[計算 token 的方案: tiktoken](https://www.npmjs.com/package/tiktoken)
+### 1.0.x
 
-## Version History
+1. Support zod as schema definition tool and remove yup support.
+2. Use nodenext as compilation target.
+3. Change Google Service to use @google/genai package.
+4. Rename Llama3Cpp to LlamaCpp.
 
 ### 0.9.x
 
-1. OpenAI 的 API 更新，現在可以透過 `setBaseUrl` 方法來設定 baseUrl。
-2. 新增 X Ai Service 的支援
+1. OpenAI API update, now you can set baseUrl through `setBaseUrl` method.
+2. Add support for X Ai Service
 
 ### 0.8.x
 
-1. 正規化 Service 的命名
-2. 新增 Google Service 的支援
+1. Standardize Service naming
+2. Add support for Google Service
 
 ### 0.7.x
 
-感謝當今的模型對於json schema的支援，我們不再需要繁瑣的宣告，因此新增了透過註冊 CtoD 的方式來簡化流程。 
+Thanks to today's model support for json schema, we no longer need tedious declarations, so we added a simplified process through CtoD registration.
 
 ### 0.6.x
 
-`bindYupToJsonSchemaToYup` 有一些依賴問題已經被移除，改用以下方案取代：
+`bindYupToJsonSchemaToYup` had some dependency issues and has been removed, replaced with the following solution:
 
 ```ts
 yup.array(item).required().meta({
     jsonSchema: {
-        description: '由高到低排序的索引'
+        description: 'Indexes sorted from high to low'
     }
 })
 ```
 
-1. 新增了 defineYupSchema 讓建立複雜的 Output 更加容易。
+1. Added defineYupSchema to make creating complex Outputs easier.
 
 ### 0.5.x
 
-移除了 JSON Schema Info 的支援，而是透過 [yup-to-json-schema](https://github.com/sodaru/yup-to-json-schema) 進行生成資料格式。
+Removed JSON Schema Info support and instead generate data formats through [yup-to-json-schema](https://github.com/sodaru/yup-to-json-schema).
 
-由於 `yup-to-json-schema` 的延伸套件要使用 `yup.string().description()` 方法需要進行全域註冊，在此我們提供了 `bindYupToJsonSchemaToYup` 這個方法，讓使用者可以自行決定是否要進行註冊。
+Since the `yup-to-json-schema` extension requires global registration to use the `yup.string().description()` method, we provide the `bindYupToJsonSchemaToYup` method here, allowing users to decide whether to register.
 
-1. 可以在 question 中回應 array，會透過 join 進行合併。
-2. 可以省略 install 參數了。
+1. Can respond with array in question, which will be merged through join.
+2. Install parameter can now be omitted.
 
 ### 0.4.x
 
-主要是支援 llama3.cpp 或者是其他自建服務上流程的調整。
+Mainly adjustments to support llama3.cpp or other self-hosted service workflows.
 
-1. 支援 llama3.cpp server service
-2. 新增 yup to json scheme。
+1. Support llama3.cpp server service
+2. Add yup to json schema.
 
 ### 0.3.x
 
-為了支援更多平台與自建服務，我們捨棄了完全為了 ChatGPT 客制化的接口，這樣也能完整保持 Broker 與 Plugin 的一致性。
+To support more platforms and self-hosted services, we abandoned the fully customized interface for ChatGPT, which also maintains the consistency of Broker and Plugin.

package/README_ZH.md

@@ -0,0 +1,246 @@
+<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>
+
+<p align="center">
+    <a href="./README.md">English</a>  | 
+    繁體中文
+</p>
+
+<br>
+
+## 摘要
+
+現在我們頻繁的有透過口語化的方式交付任務 LLM 處理並要求回應 JSON 的需求，透過 CtoD 你可以讓這個模式有架構化的進行。
+
+在對話過程中，CtoD 採用 [zod](https://zod.dev/basics) 來驗證請求與回復資料是否符合預期，以確保一致性，只要保持這個互動模式，就可以利用在 API 串接或是自動化系統上。
+
+我們還附帶支援 `OpenAI`, `Google`, `X`, `anthropic`, `llama.cpp` 等主流 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({ zod, data, setMessages }) => {
+    const { indexes, question } = data
+    setMessages([
+        {
+            role: 'user',
+            content: [
+                '我有以下索引',
+                `${JSON.stringify(indexes)}`,
+                `請幫我解析"${question}"可能是哪個索引`,
+                '且相關性由高到低排序並給予分數，分數由 0 ~ 1'
+            ]
+        }
+    ])
+    const item = zod.object({
+        name: zod.string().describe('索引名稱'),
+        score: zod.number().describe('評比分數')
+    })
+    return {
+        indexes: zod.array(item).describe('由高到低排序的索引')
+    }
+})
+
+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/chat.ts)中了解每個生命週期的參數與行為，並對其行為進行加工。
+
+現在，假設我們想要設計一個插件，它會在每次對話結束時將訊息備份到伺服器上：
+
+```ts
+import axios from 'axios'
+import { CtoDPlugin } from 'ctod'
+const backupPlugin = new CtoDPlugin({
+    name: 'backup-plugin',
+    // 定義參數為 sendUrl
+    params: zod => {
+        return {
+            sendUrl: zod.string()
+        }
+    },
+    // 現階段你可以在執行過程中接收到資訊,資訊結構由這裡定義。
+    receiveData: zod => {
+        return {
+            character: zod.string()
+        }
+    },
+    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)
+
+## Version History
+
+### 1.0.x
+
+1. 支援 zod 作為 schema 定義工具，並移除 yup 的支援。
+2. 改由 nodenext 作為編譯目標。
+3. 將 Google Service 改使用 @google/genai 套件。
+4. 將 Llama3Cpp 改名為 LlamaCpp。
+
+### 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 的一致性。