zod schema (#4)

* add job zod schema

* refactor: update job parameter types to use specific schemas for chat, embedding, and image jobs

* feat: implement models() function for OpenAI, Ollama, and Anthropic providers

* docs: update README to reflect changes in models listing and add usage example

* refactor: make options field optional in baseJobSchema

* schema based on provider

* simplify chat stream

* fix utils

* add job result schema

* add google provider

* update README to include instructions for requesting support for new AI providers

* add groq example

* add job.remote()

* update schemas and fix dump type

* fmt

* fix test

* fix type

* rename job types

* add schema file

* refactor: reorganize chat job types and introduce ChatTool class

* add builder class

* seems working

* revert example

* fix some imports

* exclude zod in dist

* fix more types

* fix more types

* update types

* fix typo

* add provider

* update job schemas and add TypeScript check in github action

* add deepseek provider

* deepseek models

* fix job type

* zod v4

* fix test, add ChatStream

* fix job schema export

* add jobStream() helper

* rename example

* include response json in http error

* add job output schema

* fix vision chat

* add partial json

* fix readme

---------

Co-authored-by: Bruce Shi <shibocuhk@gmail.com>

Author: wangzuo

.github/workflows/test.yml

@@ -31,6 +31,8 @@ jobs:
         name: Install dependencies
         run: |
           bun install
+      # - id: tsc
+      #   run: bunx tsc
       - id: build
         name: Run build
         run: |

.gitignore

@@ -6,7 +6,7 @@ yarn-debug.log*
 yarn-error.log*
 lerna-debug.log*
 .pnpm-debug.log*
-
+.vscode
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 

README.md

@@ -1,7 +1,7 @@
 # fluent-ai
 
-![NPM Version](https://img.shields.io/npm/v/fluent-ai)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/modalityml/fluent-ai/test.yml)
+[![NPM Version](https://img.shields.io/npm/v/fluent-ai)](http://npmjs.com/fluent-ai)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/modalityml/fluent-ai/test.yml)](https://github.com/modalityml/fluent-ai/actions/workflows/test.yml)
 
 > [!WARNING]
 > This project is in beta. The API is subject to changes and may break.
@@ -10,21 +10,24 @@ fluent-ai is a lightweight, type-safe AI toolkit that seamlessly integrates mult
 
 ## Installation
 
+[Zod](https://zod.dev/) is a popular type of validation library for TypeScript and JavaScript that allows developers to define and validate data schemas in a concise and type-safe manner. fluent-ai is built upon zod.
+
 ```sh
-npm install fluent-ai
+npm install fluent-ai zod@next
 ```
 
 ## AI Service provider support
 
 fluent-ai includes support for multiple AI providers and modalities.
 
-| Provider  | chat               | embedding          | image              | listModels         |
+| provider  | chat completion    | embedding          | image generation   | list models        |
 | --------- | ------------------ | ------------------ | ------------------ | ------------------ |
-| anthropic | :white_check_mark: |                    |                    | :white_check_mark:	|
-| fal       |                    |                    | :white_check_mark: |					|
-| ollama    | :white_check_mark: | :white_check_mark: |					   | :white_check_mark:	|
-| openai    | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark:	|
-| voyageai  |                    | :white_check_mark: |                    |					|
+| anthropic | :white_check_mark: |                    |                    | :white_check_mark: |
+| fal       |                    |                    | :white_check_mark: |                    |
+| google    | :white_check_mark: |                    |                    |                    |
+| ollama    | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |
+| openai    | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| voyage    |                    | :white_check_mark: |                    |                    |
 
 By default, API keys for providers are read from environment variable (`process.env`) following the format `<PROVIDER>_API_KEY` (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).
 
@@ -47,40 +50,47 @@ Each request to AI providers is wrapped in a `Job`. which can also serialized an
 ### Method chaining
 
 ```ts
-import { openai, userPrompt } from "fluent-ai";
+import { openai, user } from "fluent-ai";
 
 const job = openai()
   .chat("gpt-4o-mini")
-  .messages([userPrompt("Hi")])
+  .messages([user("Hi")])
   .temperature(0.5)
   .maxTokens(1024);
 ```
 
 ### Declaration
 
-Alternatively, fluent-ai also supports job declaration from json object.
+Alternatively, fluent-ai supports declarative job creation using JSON objects, with full TypeScript autocompletion support.
 
 ```ts
 import { load } from "fluent-ai";
 
 const job = load({
   provider: "openai",
-  chat: {
+  type: "chat",
+  input: {
     model: "gpt-4o-mini",
-    params: {
-      messages: [{ role: "user", content: "hi" }],
-      temperature: 0.5,
-    },
+    messages: [{ role: "user", content: "hi" }],
+    temperature: 0.5,
   },
 });
 ```
 
+fluent-ai provides built-in TypeScript type definitions and schema validation for jobs:
+
+```ts
+import { type Job } from "fluent-ai"; // TypeScript type
+import { JobSchema } from "fluent-ai"; // Zod schema
+import { jobJSONSchema } from "fluent-ai"; // JSON Schema
+```
+
 ### Job serialization and deserialization
 
 To serialize a job to a JSON object, use the `dump` method:
 
 ```ts
-const obj = await job.dump();
+const payload = job.dump();
 ```
 
 This allows you to save the job's state for later use, such as storing it in a queue or database.
@@ -89,7 +99,7 @@ To recreate and execute a job from the JSON object, use the `load` function:
 ```ts
 import { load } from "fluent-ai";
 
-const job = load(obj);
+const job = load(payload);
 await job.run();
 ```
 
@@ -100,42 +110,14 @@ Chat completion, such as ChatGPT, is the most common AI service. It generates re
 ### Text generation
 
 ```ts
-import { openai, systemPrompt, userPrompt } from "fluent-ai";
+import { openai, system, user, text } from "fluent-ai";
 
 const job = openai()
   .chat("gpt-4o-mini")
-  .messages([systemPrompt("You are a helpful assistant"), userPrompt("Hi")]);
-
-const { text } = await job.run();
-```
-
-### Structured output
-
-Structured output from AI chat completions involves formatting the responses based on predefined json schema. This feature is essential when building applications with chat completions.
+  .messages([system("You are a helpful assistant"), user("Hi")]);
 
-[Zod](https://zod.dev/) is a popular type of validation library for TypeScript and JavaScript that allows developers to define and validate data schemas in a concise and type-safe manner. fluent-ai provides built-in integration for declare json-schema with zod. To use zod integration, first install `zod` from npm. Any parameter in fluent-ai that accepts a JSON schema will also work with a Zod schema.
-
-```sh
-npm install zod
-```
-
-fluent-ai provides a consistent `jsonSchema()` function for all providers to generate structured output. For more details, refer to the [structured output docs](/docs/chat-structured-outputs.md)
-
-```ts
-import { z } from "zod";
-import { openai, userPrompt } from "fluent-ai";
-
-const personSchema = z.object({
-  name: z.string(),
-  age: z.number(),
-});
-
-const job = openai()
-  .chat("gpt-4o-mini")
-  .messages([userPrompt("generate a person with name and age in json format")])
-  .jsonSchema(personSchema, "person");
-
-const { object } = await job.run();
+const result = await job.run();
+console.log(text(result));
 ```
 
 ### Function calling (tool calling)
@@ -163,9 +145,7 @@ To use the tool, add it to a chat job with a function-calling-enabled model, suc
 ```ts
 const job = openai().chat("gpt-4o-mini").tool(weatherTool);
 
-const { toolCalls } = await job
-  .messages([userPrompt("What is the weather in San Francisco?")])
-  .run();
+await job.messages([user("What is the weather in San Francisco?")]).run();
 ```
 
 ### Streaming support
@@ -175,52 +155,47 @@ Rather than waiting for the complete response, streaming enables the model to re
 ```ts
 const job = openai()
   .chat("gpt-4o-mini")
-  .messages([systemPrompt("You are a helpful assistant"), userPrompt("Hi")])
+  .messages([system("You are a helpful assistant"), user("Hi")])
   .stream();
 
-const { stream } = await job.run();
-for await (const chunk of stream) {
-  console.log(chunk);
+for await (const event of await job.run()) {
+  console.log(text(event));
 }
 ```
 
 fluent-ai supports streaming text, object and tool calls on demand. For more details, see the [streaming docs](/docs/chat-streaming.md).
 
-### Vision support
-
-You can leverage chat models with vision capabilities by including an image URL in your prompt.
+## Embedding
 
 ```ts
-import { openai, systemPrompt, userPrompt } from "fluent-ai";
+import { openai } from "fluent-ai";
 
-openai()
-  .chat("gpt-4o-mini")
-  .messages([
-    userPrompt("Describe the image", { image: { url: "<image_url>" } }),
-  ]);
+const job = openai().embedding("text-embedding-3-small").value("hello");
+const result = await job.run();
 ```
 
-## Embedding
+## Image generation
 
 ```ts
 import { openai } from "fluent-ai";
 
-const job = openai().embedding("text-embedding-3-small").input("hello");
+const job = openai().image("dalle-2").prompt("a cat").n(1).size("512x512");
 const result = await job.run();
 ```
 
-## Image generation
+## List models
+
+fluent-ai provides an easy way to retrieve all available models from supported providers (openai, anthropic, ollama).
 
 ```ts
 import { openai } from "fluent-ai";
 
-const job = openai().image("dalle-2").prompt("a cat").n(1).size("512x512");
-const result = await job.run();
+const models = await openai().models().run();
 ```
 
 ## Support
 
-Feel free to [open an issue](https://github.com/modalityml/fluent-ai/issues) or [start a discussion](https://github.com/modalityml/fluent-ai/discussions) if you have any questions. [Join our Discord community](https://discord.gg/HzGZWbY8Fx)
+Feel free to [open an issue](https://github.com/modalityml/fluent-ai/issues) or [start a discussion](https://github.com/modalityml/fluent-ai/discussions) if you have any questions. If you would like to request support for a new AI provider, please create an issue with details about the provider's API. [Join our Discord community](https://discord.gg/HzGZWbY8Fx) for help and updates.
 
 ## License
 

biome.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "ignore": [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/build/**"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": false,
+      "suspicious": {
+        "noExplicitAny": "off"
+      },
+      "style": {
+        "noNonNullAssertion": "off",
+        "useImportType": "off"
+      },
+      "correctness": {
+        "useExhaustiveDependencies": "warn"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "quoteStyle": "double",
+      "arrowParentheses": "always",
+      "bracketSameLine": false,
+      "bracketSpacing": true,
+      "jsxQuoteStyle": "double",
+      "quoteProperties": "asNeeded",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "json": {
+    "formatter": {
+      "trailingCommas": "none"
+    }
+  }
+}

build.ts

@@ -4,6 +4,7 @@ import dts from "bun-plugin-dts";
 const defaultBuildConfig: BuildConfig = {
   entrypoints: ["./src/index.ts"],
   outdir: "./dist",
+  external: ["zod"],
 };
 
 await Promise.all([

bun.lock

@@ -13,7 +13,7 @@ export interface StreamOptions {
 ```ts
 const { textStream } = await openai()
   .chat("gpt-4o-mini")
-  .messages([userPrompt("hi")])
+  .messages([user("hi")])
   .stream()
   .run();
 
@@ -28,9 +28,7 @@ for await (const text of textStream) {
 const { toolCallStream } = await openai()
   .chat("gpt-4o-mini")
   .tool(weatherTool)
-  .messages([
-    userPrompt("What's the weather like in Boston, Beijing, Tokyo today?"),
-  ])
+  .messages([user("What's the weather like in Boston, Beijing, Tokyo today?")])
   .stream()
   .run();
 
@@ -44,7 +42,7 @@ for await (const toolCalls of toolCallStream) {
 ```ts
 const { objectStream } = await openai()
   .chat("gpt-4o-mini")
-  .messages([userPrompt("generate a person with name and age in json format")])
+  .messages([user("generate a person with name and age in json format")])
   .responseSchema(personSchema)
   .objectStream()
   .run();
@@ -61,7 +59,7 @@ The original chunk object from providers
 ```ts
 const { stream } = await openai()
   .chat("gpt-4o-mini")
-  .messages([userPrompt("hi")]);
+  .messages([user("hi")]);
 
 for await (const chunk of stream) {
   console.log(chunk);