@baziapi/ai-tools 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# BaZi API - AI Agents & LLM Function Calling Tools (`@baziapi/ai-tools`)
+
+Official pre-built tool integrations for connecting LLMs, AI Agents, and Chatbots directly with the BaZi Four Pillars calculation engine.
+
+---
+
+## 📦 Supported Frameworks
+
+- **OpenAI Function Calling / Assistants API**
+- **Vercel AI SDK (`ai`)**
+- **LangChain (TypeScript & Python)**
+- **LlamaIndex / CrewAI / AutoGen**
+
+---
+
+## 🚀 Usage
+
+### 1. OpenAI Assistants / Chat Completions
+
+```typescript
+import OpenAI from 'openai';
+import { BaziClient } from '@baziapi/sdk';
+import { baziOpenAITool, executeOpenAIBaziCall } from '@baziapi/ai-tools';
+
+const openai = new OpenAI();
+const bazi = new BaziClient({ apiKey: process.env.BAZI_API_KEY });
+
+const runner = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [
+    { role: 'user', content: 'What is the Day Master of someone born 1998-08-12 at 10:30 male?' },
+  ],
+  tools: [baziOpenAITool],
+});
+```
+
+### 2. Vercel AI SDK (`ai`)
+
+```typescript
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { BaziClient } from '@baziapi/sdk';
+import { createBaziVercelTool } from '@baziapi/ai-tools';
+
+const client = new BaziClient({ apiKey: process.env.BAZI_API_KEY });
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  tools: {
+    calculateBazi: createBaziVercelTool(client),
+  },
+  prompt: 'Calculate BaZi chart for a male born 1998-08-12 10:30 in Dhaka.',
+});
+```
+
+### 3. LangChain TypeScript
+
+```typescript
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { BaziClient } from '@baziapi/sdk';
+import { createBaziLangChainConfig } from '@baziapi/ai-tools';
+
+const client = new BaziClient({ apiKey: process.env.BAZI_API_KEY });
+const baziTool = new DynamicStructuredTool(createBaziLangChainConfig(client));
+```
+
+---
+
+## 📄 License
+
+MIT License.

package/dist/index.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+const zod = require('zod');
+
+const baziOpenAITool = {
+  type: "function",
+  function: {
+    name: "calculate_bazi_chart",
+    description: "Calculates complete Chinese Four Pillars of Destiny (BaZi / \u516B\u5B57) astrological chart with Heavenly Stems, Earthly Branches, Five Elements, Ten Gods, Hidden Stems, and Luck Pillars from birth date and time.",
+    parameters: {
+      type: "object",
+      properties: {
+        birthDate: {
+          type: "string",
+          description: "Birth date in YYYY-MM-DD format (e.g. '1998-08-12')"
+        },
+        birthTime: {
+          type: "string",
+          description: "Birth time in 24-hour HH:mm format (e.g. '10:30'). Defaults to '12:00' if unknown."
+        },
+        gender: {
+          type: "string",
+          enum: ["male", "female"],
+          description: "Gender of the person. Determines Luck Pillar forward/backward progression direction."
+        },
+        timezone: {
+          type: "string",
+          default: "Asia/Shanghai",
+          description: "IANA Timezone string (e.g. 'Asia/Dhaka', 'America/New_York', 'Europe/London')"
+        },
+        language: {
+          type: "string",
+          enum: ["en", "zh"],
+          default: "en",
+          description: "Language for terminology and names ('en' for English pinyin/translations, 'zh' for Chinese)"
+        }
+      },
+      required: ["birthDate", "birthTime", "gender"]
+    }
+  }
+};
+async function executeOpenAIBaziCall(client, toolArgs) {
+  const calcFn = client.calculate ? client.calculate.bind(client) : client.bazi?.calculate.bind(client.bazi);
+  if (!calcFn) {
+    throw new Error("Invalid BaziClient instance provided.");
+  }
+  return calcFn({
+    birthDate: toolArgs.birthDate,
+    birthTime: toolArgs.birthTime || "12:00",
+    gender: toolArgs.gender,
+    timezone: toolArgs.timezone || "Asia/Shanghai",
+    language: toolArgs.language || "en"
+  });
+}
+
+const baziToolSchema = zod.z.object({
+  birthDate: zod.z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Must be in YYYY-MM-DD format (e.g. 1998-08-12)").describe("Birth date in YYYY-MM-DD format"),
+  birthTime: zod.z.string().regex(/^\d{2}:\d{2}$/, "Must be in HH:mm 24-hour format (e.g. 10:30)").default("12:00").describe("Birth time in 24-hour HH:mm format"),
+  gender: zod.z.enum(["male", "female"]).describe("Gender of the individual (required for luck pillar calculation)"),
+  timezone: zod.z.string().default("Asia/Shanghai").describe("IANA Timezone string (e.g. Asia/Dhaka, America/New_York)"),
+  language: zod.z.enum(["en", "zh"]).default("en").describe("Language for chart output")
+});
+function createBaziVercelTool(client) {
+  return {
+    description: "Calculates Chinese Four Pillars of Destiny (BaZi) astrological chart with Heavenly Stems, Earthly Branches, Ten Gods, and Luck Pillars.",
+    parameters: baziToolSchema,
+    execute: async (args) => {
+      const result = await client.calculate({
+        birthDate: args.birthDate,
+        birthTime: args.birthTime,
+        gender: args.gender,
+        timezone: args.timezone,
+        language: args.language
+      });
+      return result;
+    }
+  };
+}
+
+function createBaziLangChainConfig(client, overrides = {}) {
+  return {
+    name: overrides.name || "calculate_bazi_chart",
+    description: overrides.description || "Calculates complete Chinese Four Pillars of Destiny (BaZi) astrological chart with Heavenly Stems, Earthly Branches, Five Elements, and Ten Gods.",
+    schema: baziToolSchema,
+    func: async (input) => {
+      const chart = await client.calculate({
+        birthDate: input.birthDate,
+        birthTime: input.birthTime,
+        gender: input.gender,
+        timezone: input.timezone,
+        language: input.language
+      });
+      return JSON.stringify(chart);
+    }
+  };
+}
+
+exports.baziOpenAITool = baziOpenAITool;
+exports.baziToolSchema = baziToolSchema;
+exports.createBaziLangChainConfig = createBaziLangChainConfig;
+exports.createBaziVercelTool = createBaziVercelTool;
+exports.executeOpenAIBaziCall = executeOpenAIBaziCall;

package/dist/index.d.cts

@@ -0,0 +1,190 @@
+import * as _baziapi_sdk from '@baziapi/sdk';
+import { BaziClient } from '@baziapi/sdk';
+import * as zod from 'zod';
+import { z } from 'zod';
+
+/**
+ * @file openai/toolDefinition.ts
+ * @description Official OpenAI Function / Tool Calling Schema for BaZi calculations.
+ */
+/**
+ * OpenAI Tool Definition for BaZi Four Pillars calculation.
+ * Compatible with OpenAI Chat Completions API, Assistant API, and Agents SDK.
+ */
+declare const baziOpenAITool: {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                birthDate: {
+                    type: string;
+                    description: string;
+                };
+                birthTime: {
+                    type: string;
+                    description: string;
+                };
+                gender: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                timezone: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                language: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};
+interface BaziClientLike {
+    calculate?: (input: {
+        birthDate: string;
+        birthTime?: string;
+        gender: 'male' | 'female';
+        timezone?: string;
+        language?: 'en' | 'zh';
+    }) => Promise<unknown>;
+    bazi?: {
+        calculate: (input: {
+            birthDate: string;
+            birthTime?: string;
+            gender: 'male' | 'female';
+            timezone?: string;
+            language?: 'en' | 'zh';
+        }) => Promise<unknown>;
+    };
+}
+/**
+ * Helper to execute an OpenAI tool call with a BaziClient instance.
+ */
+declare function executeOpenAIBaziCall(client: BaziClientLike, toolArgs: {
+    birthDate: string;
+    birthTime?: string;
+    gender: 'male' | 'female';
+    timezone?: string;
+    language?: 'en' | 'zh';
+}): Promise<unknown>;
+
+declare const baziToolSchema: z.ZodObject<{
+    birthDate: z.ZodString;
+    birthTime: z.ZodDefault<z.ZodString>;
+    gender: z.ZodEnum<["male", "female"]>;
+    timezone: z.ZodDefault<z.ZodString>;
+    language: z.ZodDefault<z.ZodEnum<["en", "zh"]>>;
+}, "strip", z.ZodTypeAny, {
+    birthDate: string;
+    birthTime: string;
+    gender: "male" | "female";
+    timezone: string;
+    language: "en" | "zh";
+}, {
+    birthDate: string;
+    gender: "male" | "female";
+    birthTime?: string | undefined;
+    timezone?: string | undefined;
+    language?: "en" | "zh" | undefined;
+}>;
+type BaziToolInput = z.infer<typeof baziToolSchema>;
+/**
+ * Creates a Vercel AI SDK tool definition.
+ *
+ * @example
+ * ```typescript
+ * import { createBaziVercelTool } from '@baziapi/ai-tools';
+ * import { BaziClient } from '@baziapi/sdk';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const client = new BaziClient({ apiKey: process.env.BAZI_API_KEY! });
+ *
+ * const { text } = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools: {
+ *     calculateBazi: createBaziVercelTool(client),
+ *   },
+ *   prompt: 'Calculate BaZi chart for a male born on August 12, 1998 at 10:30 AM in Dhaka.',
+ * });
+ * ```
+ */
+declare function createBaziVercelTool(client: BaziClient): {
+    description: string;
+    parameters: z.ZodObject<{
+        birthDate: z.ZodString;
+        birthTime: z.ZodDefault<z.ZodString>;
+        gender: z.ZodEnum<["male", "female"]>;
+        timezone: z.ZodDefault<z.ZodString>;
+        language: z.ZodDefault<z.ZodEnum<["en", "zh"]>>;
+    }, "strip", z.ZodTypeAny, {
+        birthDate: string;
+        birthTime: string;
+        gender: "male" | "female";
+        timezone: string;
+        language: "en" | "zh";
+    }, {
+        birthDate: string;
+        gender: "male" | "female";
+        birthTime?: string | undefined;
+        timezone?: string | undefined;
+        language?: "en" | "zh" | undefined;
+    }>;
+    execute: (args: BaziToolInput) => Promise<_baziapi_sdk.BaziCalculateResponse>;
+};
+
+interface LangChainToolConfig {
+    name?: string;
+    description?: string;
+}
+/**
+ * Creates a LangChain structured tool configuration for BaZi calculations.
+ *
+ * @example
+ * ```typescript
+ * import { DynamicStructuredTool } from '@langchain/core/tools';
+ * import { createBaziLangChainConfig } from '@baziapi/ai-tools';
+ * import { BaziClient } from '@baziapi/sdk';
+ *
+ * const client = new BaziClient({ apiKey: 'bazi_xxxx' });
+ * const config = createBaziLangChainConfig(client);
+ *
+ * const baziTool = new DynamicStructuredTool(config);
+ * ```
+ */
+declare function createBaziLangChainConfig(client: BaziClient, overrides?: LangChainToolConfig): {
+    name: string;
+    description: string;
+    schema: zod.ZodObject<{
+        birthDate: zod.ZodString;
+        birthTime: zod.ZodDefault<zod.ZodString>;
+        gender: zod.ZodEnum<["male", "female"]>;
+        timezone: zod.ZodDefault<zod.ZodString>;
+        language: zod.ZodDefault<zod.ZodEnum<["en", "zh"]>>;
+    }, "strip", zod.ZodTypeAny, {
+        birthDate: string;
+        birthTime: string;
+        gender: "male" | "female";
+        timezone: string;
+        language: "en" | "zh";
+    }, {
+        birthDate: string;
+        gender: "male" | "female";
+        birthTime?: string | undefined;
+        timezone?: string | undefined;
+        language?: "en" | "zh" | undefined;
+    }>;
+    func: (input: BaziToolInput) => Promise<string>;
+};
+
+export { baziOpenAITool, baziToolSchema, createBaziLangChainConfig, createBaziVercelTool, executeOpenAIBaziCall };
+export type { BaziToolInput, LangChainToolConfig };

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+import * as _baziapi_sdk from '@baziapi/sdk';
+import { BaziClient } from '@baziapi/sdk';
+import * as zod from 'zod';
+import { z } from 'zod';
+
+/**
+ * @file openai/toolDefinition.ts
+ * @description Official OpenAI Function / Tool Calling Schema for BaZi calculations.
+ */
+/**
+ * OpenAI Tool Definition for BaZi Four Pillars calculation.
+ * Compatible with OpenAI Chat Completions API, Assistant API, and Agents SDK.
+ */
+declare const baziOpenAITool: {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                birthDate: {
+                    type: string;
+                    description: string;
+                };
+                birthTime: {
+                    type: string;
+                    description: string;
+                };
+                gender: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                timezone: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                language: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};
+interface BaziClientLike {
+    calculate?: (input: {
+        birthDate: string;
+        birthTime?: string;
+        gender: 'male' | 'female';
+        timezone?: string;
+        language?: 'en' | 'zh';
+    }) => Promise<unknown>;
+    bazi?: {
+        calculate: (input: {
+            birthDate: string;
+            birthTime?: string;
+            gender: 'male' | 'female';
+            timezone?: string;
+            language?: 'en' | 'zh';
+        }) => Promise<unknown>;
+    };
+}
+/**
+ * Helper to execute an OpenAI tool call with a BaziClient instance.
+ */
+declare function executeOpenAIBaziCall(client: BaziClientLike, toolArgs: {
+    birthDate: string;
+    birthTime?: string;
+    gender: 'male' | 'female';
+    timezone?: string;
+    language?: 'en' | 'zh';
+}): Promise<unknown>;
+
+declare const baziToolSchema: z.ZodObject<{
+    birthDate: z.ZodString;
+    birthTime: z.ZodDefault<z.ZodString>;
+    gender: z.ZodEnum<["male", "female"]>;
+    timezone: z.ZodDefault<z.ZodString>;
+    language: z.ZodDefault<z.ZodEnum<["en", "zh"]>>;
+}, "strip", z.ZodTypeAny, {
+    birthDate: string;
+    birthTime: string;
+    gender: "male" | "female";
+    timezone: string;
+    language: "en" | "zh";
+}, {
+    birthDate: string;
+    gender: "male" | "female";
+    birthTime?: string | undefined;
+    timezone?: string | undefined;
+    language?: "en" | "zh" | undefined;
+}>;
+type BaziToolInput = z.infer<typeof baziToolSchema>;
+/**
+ * Creates a Vercel AI SDK tool definition.
+ *
+ * @example
+ * ```typescript
+ * import { createBaziVercelTool } from '@baziapi/ai-tools';
+ * import { BaziClient } from '@baziapi/sdk';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const client = new BaziClient({ apiKey: process.env.BAZI_API_KEY! });
+ *
+ * const { text } = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools: {
+ *     calculateBazi: createBaziVercelTool(client),
+ *   },
+ *   prompt: 'Calculate BaZi chart for a male born on August 12, 1998 at 10:30 AM in Dhaka.',
+ * });
+ * ```
+ */
+declare function createBaziVercelTool(client: BaziClient): {
+    description: string;
+    parameters: z.ZodObject<{
+        birthDate: z.ZodString;
+        birthTime: z.ZodDefault<z.ZodString>;
+        gender: z.ZodEnum<["male", "female"]>;
+        timezone: z.ZodDefault<z.ZodString>;
+        language: z.ZodDefault<z.ZodEnum<["en", "zh"]>>;
+    }, "strip", z.ZodTypeAny, {
+        birthDate: string;
+        birthTime: string;
+        gender: "male" | "female";
+        timezone: string;
+        language: "en" | "zh";
+    }, {
+        birthDate: string;
+        gender: "male" | "female";
+        birthTime?: string | undefined;
+        timezone?: string | undefined;
+        language?: "en" | "zh" | undefined;
+    }>;
+    execute: (args: BaziToolInput) => Promise<_baziapi_sdk.BaziCalculateResponse>;
+};
+
+interface LangChainToolConfig {
+    name?: string;
+    description?: string;
+}
+/**
+ * Creates a LangChain structured tool configuration for BaZi calculations.
+ *
+ * @example
+ * ```typescript
+ * import { DynamicStructuredTool } from '@langchain/core/tools';
+ * import { createBaziLangChainConfig } from '@baziapi/ai-tools';
+ * import { BaziClient } from '@baziapi/sdk';
+ *
+ * const client = new BaziClient({ apiKey: 'bazi_xxxx' });
+ * const config = createBaziLangChainConfig(client);
+ *
+ * const baziTool = new DynamicStructuredTool(config);
+ * ```
+ */
+declare function createBaziLangChainConfig(client: BaziClient, overrides?: LangChainToolConfig): {
+    name: string;
+    description: string;
+    schema: zod.ZodObject<{
+        birthDate: zod.ZodString;
+        birthTime: zod.ZodDefault<zod.ZodString>;
+        gender: zod.ZodEnum<["male", "female"]>;
+        timezone: zod.ZodDefault<zod.ZodString>;
+        language: zod.ZodDefault<zod.ZodEnum<["en", "zh"]>>;
+    }, "strip", zod.ZodTypeAny, {
+        birthDate: string;
+        birthTime: string;
+        gender: "male" | "female";
+        timezone: string;
+        language: "en" | "zh";
+    }, {
+        birthDate: string;
+        gender: "male" | "female";
+        birthTime?: string | undefined;
+        timezone?: string | undefined;
+        language?: "en" | "zh" | undefined;
+    }>;
+    func: (input: BaziToolInput) => Promise<string>;
+};
+
+export { baziOpenAITool, baziToolSchema, createBaziLangChainConfig, createBaziVercelTool, executeOpenAIBaziCall };
+export type { BaziToolInput, LangChainToolConfig };

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+import * as _baziapi_sdk from '@baziapi/sdk';
+import { BaziClient } from '@baziapi/sdk';
+import * as zod from 'zod';
+import { z } from 'zod';
+
+/**
+ * @file openai/toolDefinition.ts
+ * @description Official OpenAI Function / Tool Calling Schema for BaZi calculations.
+ */
+/**
+ * OpenAI Tool Definition for BaZi Four Pillars calculation.
+ * Compatible with OpenAI Chat Completions API, Assistant API, and Agents SDK.
+ */
+declare const baziOpenAITool: {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                birthDate: {
+                    type: string;
+                    description: string;
+                };
+                birthTime: {
+                    type: string;
+                    description: string;
+                };
+                gender: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                timezone: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                language: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};
+interface BaziClientLike {
+    calculate?: (input: {
+        birthDate: string;
+        birthTime?: string;
+        gender: 'male' | 'female';
+        timezone?: string;
+        language?: 'en' | 'zh';
+    }) => Promise<unknown>;
+    bazi?: {
+        calculate: (input: {
+            birthDate: string;
+            birthTime?: string;
+            gender: 'male' | 'female';
+            timezone?: string;
+            language?: 'en' | 'zh';
+        }) => Promise<unknown>;
+    };
+}
+/**
+ * Helper to execute an OpenAI tool call with a BaziClient instance.
+ */
+declare function executeOpenAIBaziCall(client: BaziClientLike, toolArgs: {
+    birthDate: string;
+    birthTime?: string;
+    gender: 'male' | 'female';
+    timezone?: string;
+    language?: 'en' | 'zh';
+}): Promise<unknown>;
+
+declare const baziToolSchema: z.ZodObject<{
+    birthDate: z.ZodString;
+    birthTime: z.ZodDefault<z.ZodString>;
+    gender: z.ZodEnum<["male", "female"]>;
+    timezone: z.ZodDefault<z.ZodString>;
+    language: z.ZodDefault<z.ZodEnum<["en", "zh"]>>;
+}, "strip", z.ZodTypeAny, {
+    birthDate: string;
+    birthTime: string;
+    gender: "male" | "female";
+    timezone: string;
+    language: "en" | "zh";
+}, {
+    birthDate: string;
+    gender: "male" | "female";
+    birthTime?: string | undefined;
+    timezone?: string | undefined;
+    language?: "en" | "zh" | undefined;
+}>;
+type BaziToolInput = z.infer<typeof baziToolSchema>;
+/**
+ * Creates a Vercel AI SDK tool definition.
+ *
+ * @example
+ * ```typescript
+ * import { createBaziVercelTool } from '@baziapi/ai-tools';
+ * import { BaziClient } from '@baziapi/sdk';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const client = new BaziClient({ apiKey: process.env.BAZI_API_KEY! });
+ *
+ * const { text } = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools: {
+ *     calculateBazi: createBaziVercelTool(client),
+ *   },
+ *   prompt: 'Calculate BaZi chart for a male born on August 12, 1998 at 10:30 AM in Dhaka.',
+ * });
+ * ```
+ */
+declare function createBaziVercelTool(client: BaziClient): {
+    description: string;
+    parameters: z.ZodObject<{
+        birthDate: z.ZodString;
+        birthTime: z.ZodDefault<z.ZodString>;
+        gender: z.ZodEnum<["male", "female"]>;
+        timezone: z.ZodDefault<z.ZodString>;
+        language: z.ZodDefault<z.ZodEnum<["en", "zh"]>>;
+    }, "strip", z.ZodTypeAny, {
+        birthDate: string;
+        birthTime: string;
+        gender: "male" | "female";
+        timezone: string;
+        language: "en" | "zh";
+    }, {
+        birthDate: string;
+        gender: "male" | "female";
+        birthTime?: string | undefined;
+        timezone?: string | undefined;
+        language?: "en" | "zh" | undefined;
+    }>;
+    execute: (args: BaziToolInput) => Promise<_baziapi_sdk.BaziCalculateResponse>;
+};
+
+interface LangChainToolConfig {
+    name?: string;
+    description?: string;
+}
+/**
+ * Creates a LangChain structured tool configuration for BaZi calculations.
+ *
+ * @example
+ * ```typescript
+ * import { DynamicStructuredTool } from '@langchain/core/tools';
+ * import { createBaziLangChainConfig } from '@baziapi/ai-tools';
+ * import { BaziClient } from '@baziapi/sdk';
+ *
+ * const client = new BaziClient({ apiKey: 'bazi_xxxx' });
+ * const config = createBaziLangChainConfig(client);
+ *
+ * const baziTool = new DynamicStructuredTool(config);
+ * ```
+ */
+declare function createBaziLangChainConfig(client: BaziClient, overrides?: LangChainToolConfig): {
+    name: string;
+    description: string;
+    schema: zod.ZodObject<{
+        birthDate: zod.ZodString;
+        birthTime: zod.ZodDefault<zod.ZodString>;
+        gender: zod.ZodEnum<["male", "female"]>;
+        timezone: zod.ZodDefault<zod.ZodString>;
+        language: zod.ZodDefault<zod.ZodEnum<["en", "zh"]>>;
+    }, "strip", zod.ZodTypeAny, {
+        birthDate: string;
+        birthTime: string;
+        gender: "male" | "female";
+        timezone: string;
+        language: "en" | "zh";
+    }, {
+        birthDate: string;
+        gender: "male" | "female";
+        birthTime?: string | undefined;
+        timezone?: string | undefined;
+        language?: "en" | "zh" | undefined;
+    }>;
+    func: (input: BaziToolInput) => Promise<string>;
+};
+
+export { baziOpenAITool, baziToolSchema, createBaziLangChainConfig, createBaziVercelTool, executeOpenAIBaziCall };
+export type { BaziToolInput, LangChainToolConfig };

package/dist/index.mjs

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+
+const baziOpenAITool = {
+  type: "function",
+  function: {
+    name: "calculate_bazi_chart",
+    description: "Calculates complete Chinese Four Pillars of Destiny (BaZi / \u516B\u5B57) astrological chart with Heavenly Stems, Earthly Branches, Five Elements, Ten Gods, Hidden Stems, and Luck Pillars from birth date and time.",
+    parameters: {
+      type: "object",
+      properties: {
+        birthDate: {
+          type: "string",
+          description: "Birth date in YYYY-MM-DD format (e.g. '1998-08-12')"
+        },
+        birthTime: {
+          type: "string",
+          description: "Birth time in 24-hour HH:mm format (e.g. '10:30'). Defaults to '12:00' if unknown."
+        },
+        gender: {
+          type: "string",
+          enum: ["male", "female"],
+          description: "Gender of the person. Determines Luck Pillar forward/backward progression direction."
+        },
+        timezone: {
+          type: "string",
+          default: "Asia/Shanghai",
+          description: "IANA Timezone string (e.g. 'Asia/Dhaka', 'America/New_York', 'Europe/London')"
+        },
+        language: {
+          type: "string",
+          enum: ["en", "zh"],
+          default: "en",
+          description: "Language for terminology and names ('en' for English pinyin/translations, 'zh' for Chinese)"
+        }
+      },
+      required: ["birthDate", "birthTime", "gender"]
+    }
+  }
+};
+async function executeOpenAIBaziCall(client, toolArgs) {
+  const calcFn = client.calculate ? client.calculate.bind(client) : client.bazi?.calculate.bind(client.bazi);
+  if (!calcFn) {
+    throw new Error("Invalid BaziClient instance provided.");
+  }
+  return calcFn({
+    birthDate: toolArgs.birthDate,
+    birthTime: toolArgs.birthTime || "12:00",
+    gender: toolArgs.gender,
+    timezone: toolArgs.timezone || "Asia/Shanghai",
+    language: toolArgs.language || "en"
+  });
+}
+
+const baziToolSchema = z.object({
+  birthDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Must be in YYYY-MM-DD format (e.g. 1998-08-12)").describe("Birth date in YYYY-MM-DD format"),
+  birthTime: z.string().regex(/^\d{2}:\d{2}$/, "Must be in HH:mm 24-hour format (e.g. 10:30)").default("12:00").describe("Birth time in 24-hour HH:mm format"),
+  gender: z.enum(["male", "female"]).describe("Gender of the individual (required for luck pillar calculation)"),
+  timezone: z.string().default("Asia/Shanghai").describe("IANA Timezone string (e.g. Asia/Dhaka, America/New_York)"),
+  language: z.enum(["en", "zh"]).default("en").describe("Language for chart output")
+});
+function createBaziVercelTool(client) {
+  return {
+    description: "Calculates Chinese Four Pillars of Destiny (BaZi) astrological chart with Heavenly Stems, Earthly Branches, Ten Gods, and Luck Pillars.",
+    parameters: baziToolSchema,
+    execute: async (args) => {
+      const result = await client.calculate({
+        birthDate: args.birthDate,
+        birthTime: args.birthTime,
+        gender: args.gender,
+        timezone: args.timezone,
+        language: args.language
+      });
+      return result;
+    }
+  };
+}
+
+function createBaziLangChainConfig(client, overrides = {}) {
+  return {
+    name: overrides.name || "calculate_bazi_chart",
+    description: overrides.description || "Calculates complete Chinese Four Pillars of Destiny (BaZi) astrological chart with Heavenly Stems, Earthly Branches, Five Elements, and Ten Gods.",
+    schema: baziToolSchema,
+    func: async (input) => {
+      const chart = await client.calculate({
+        birthDate: input.birthDate,
+        birthTime: input.birthTime,
+        gender: input.gender,
+        timezone: input.timezone,
+        language: input.language
+      });
+      return JSON.stringify(chart);
+    }
+  };
+}
+
+export { baziOpenAITool, baziToolSchema, createBaziLangChainConfig, createBaziVercelTool, executeOpenAIBaziCall };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@baziapi/ai-tools",
+  "version": "1.0.0",
+  "description": "Official AI Agent and LLM Function Calling Tools for BaZi API (OpenAI, LangChain, Vercel AI SDK)",
+  "author": "Md. Nasir Uddin Shoyas",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@baziapi/sdk": "1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "unbuild": "^3.0.0",
+    "zod": "^3.23.8"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "lint": "eslint src",
+    "type-check": "tsc --noEmit"
+  }
+}