@allem-sdk/agents 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Allem
+
+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

@@ -0,0 +1,117 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kingofmit/allem-sdk/main/.github/AllemSDK.png" alt="Allem SDK" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@allem-sdk/agents"><img src="https://img.shields.io/npm/v/@allem-sdk/agents.svg" alt="npm version" /></a>
+  <a href="https://github.com/kingofmit/allem-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  <img src="https://img.shields.io/badge/react-19-61dafb" alt="React 19" />
+  <img src="https://img.shields.io/badge/typescript-strict-blue" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/AI_SDK-v6-black" alt="AI SDK v6" />
+</p>
+
+# @allem-sdk/agents
+
+Agentic AI hooks for React. Multi-step tool calling, agent status tracking, and typed tool definitions built on [Vercel AI SDK v6](https://sdk.vercel.ai).
+
+## Installation
+
+```bash
+npm install @allem-sdk/agents @allem-sdk/ai ai @ai-sdk/react
+
+# Install at least one provider
+npm install @ai-sdk/google    # Google Gemini
+npm install @ai-sdk/anthropic # Anthropic Claude
+npm install @ai-sdk/openai    # OpenAI GPT
+
+# For defining tools with schemas
+npm install zod
+```
+
+## Client Usage
+
+```tsx
+import { AllemAIProvider } from "@allem-sdk/ai";
+import { useAllemAgent } from "@allem-sdk/agents";
+
+function App() {
+  return (
+    <AllemAIProvider api="/api/agent" provider="google">
+      <Agent />
+    </AllemAIProvider>
+  );
+}
+
+function Agent() {
+  const {
+    messages,
+    sendMessage,
+    agentStatus,
+    steps,
+    currentToolCalls,
+    isAgentRunning,
+  } = useAllemAgent();
+
+  return (
+    <div>
+      {agentStatus === "calling-tool" && (
+        <p>Using tool: {currentToolCalls[0]?.toolName}</p>
+      )}
+      {messages.map((m) => (
+        <div key={m.id}>
+          {m.parts?.filter((p) => p.type === "text").map((p) => p.text).join("")}
+        </div>
+      ))}
+      <p>Steps taken: {steps.length}</p>
+    </div>
+  );
+}
+```
+
+## Server Usage
+
+```ts
+// app/api/agent/route.ts (Next.js)
+import { createAllemAgentHandler, createAllemTool } from "@allem-sdk/agents";
+import { google } from "@ai-sdk/google";
+import { z } from "zod";
+
+const weatherTool = createAllemTool({
+  description: "Get the current weather for a location",
+  parameters: z.object({ city: z.string() }),
+  execute: async ({ city }) => {
+    return { city, temperature: 72, condition: "sunny" };
+  },
+});
+
+export const POST = createAllemAgentHandler({
+  providers: {
+    google: (model) => google(model ?? "gemini-2.0-flash"),
+  },
+  tools: { weather: weatherTool },
+});
+```
+
+## Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useAllemAgent` | Hook | Agent hook with status tracking, step history, and tool call awareness |
+| `AgentProvider` | Component | Optional context for registering tool metadata (names/descriptions) |
+| `useAgentTools` | Hook | Read registered tool metadata from AgentProvider |
+| `createAllemAgentHandler` | Server | Request handler with tool calling support for agentic workflows |
+| `createAllemTool` | Server | Typed tool definition helper with zod schema validation |
+
+## Part of [Allem SDK](https://github.com/kingofmit/allem-sdk)
+
+This package can be used standalone or as part of the full SDK. Install `allem-sdk` to get all packages in one install.
+
+## Support
+
+If you find Allem SDK useful, consider supporting its development:
+
+<a href="https://buymeacoffee.com/kingofmit" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50" /></a>
+
+## License
+
+[MIT](https://github.com/kingofmit/allem-sdk/blob/main/LICENSE) - [Ahmed Allem](https://kingallem.com)

package/dist/client.d.mts

@@ -0,0 +1,57 @@
+import { UseChatHelpers } from '@ai-sdk/react';
+import { ChatInit, UIMessage } from 'ai';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type AgentStatus = "idle" | "thinking" | "calling-tool" | "done";
+interface AgentToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+interface AgentStep {
+    stepIndex: number;
+    toolCalls: AgentToolCall[];
+    startedAt: number;
+}
+interface AgentToolRegistration {
+    name: string;
+    description?: string;
+}
+
+type AllemProvider = "google" | "anthropic" | "openai";
+interface UseAllemAgentOptions extends Omit<ChatInit<UIMessage>, "transport"> {
+    /** Override the API endpoint from AllemAIProvider. */
+    api?: string;
+    /** Model identifier sent in the request body. */
+    model?: string;
+    /** Provider name sent in the request body. */
+    provider?: AllemProvider;
+    /** System prompt sent in the request body. */
+    systemPrompt?: string;
+    /** Extra headers merged with AllemAIProvider headers. */
+    headers?: Record<string, string>;
+    /** Custom throttle wait in ms for updates. */
+    experimental_throttle?: number;
+}
+interface UseAllemAgentReturn extends UseChatHelpers<UIMessage> {
+    /** Current agent lifecycle status. */
+    agentStatus: AgentStatus;
+    /** Ordered list of steps taken in the current turn. */
+    steps: AgentStep[];
+    /** The tool calls from the most recent step, if any. */
+    currentToolCalls: AgentToolCall[];
+    /** Whether the agent is actively processing. */
+    isAgentRunning: boolean;
+}
+declare function useAllemAgent(options?: UseAllemAgentOptions): UseAllemAgentReturn;
+
+interface AgentProviderProps {
+    /** Tool metadata for client-side display (names and descriptions). */
+    tools?: AgentToolRegistration[];
+    children: ReactNode;
+}
+declare function AgentProvider({ tools, children }: AgentProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAgentTools(): AgentToolRegistration[];
+
+export { AgentProvider, type AgentProviderProps, type AgentStatus, type AgentStep, type AgentToolCall, type AgentToolRegistration, type AllemProvider, type UseAllemAgentOptions, type UseAllemAgentReturn, useAgentTools, useAllemAgent };

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+import { UseChatHelpers } from '@ai-sdk/react';
+import { ChatInit, UIMessage } from 'ai';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type AgentStatus = "idle" | "thinking" | "calling-tool" | "done";
+interface AgentToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+interface AgentStep {
+    stepIndex: number;
+    toolCalls: AgentToolCall[];
+    startedAt: number;
+}
+interface AgentToolRegistration {
+    name: string;
+    description?: string;
+}
+
+type AllemProvider = "google" | "anthropic" | "openai";
+interface UseAllemAgentOptions extends Omit<ChatInit<UIMessage>, "transport"> {
+    /** Override the API endpoint from AllemAIProvider. */
+    api?: string;
+    /** Model identifier sent in the request body. */
+    model?: string;
+    /** Provider name sent in the request body. */
+    provider?: AllemProvider;
+    /** System prompt sent in the request body. */
+    systemPrompt?: string;
+    /** Extra headers merged with AllemAIProvider headers. */
+    headers?: Record<string, string>;
+    /** Custom throttle wait in ms for updates. */
+    experimental_throttle?: number;
+}
+interface UseAllemAgentReturn extends UseChatHelpers<UIMessage> {
+    /** Current agent lifecycle status. */
+    agentStatus: AgentStatus;
+    /** Ordered list of steps taken in the current turn. */
+    steps: AgentStep[];
+    /** The tool calls from the most recent step, if any. */
+    currentToolCalls: AgentToolCall[];
+    /** Whether the agent is actively processing. */
+    isAgentRunning: boolean;
+}
+declare function useAllemAgent(options?: UseAllemAgentOptions): UseAllemAgentReturn;
+
+interface AgentProviderProps {
+    /** Tool metadata for client-side display (names and descriptions). */
+    tools?: AgentToolRegistration[];
+    children: ReactNode;
+}
+declare function AgentProvider({ tools, children }: AgentProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAgentTools(): AgentToolRegistration[];
+
+export { AgentProvider, type AgentProviderProps, type AgentStatus, type AgentStep, type AgentToolCall, type AgentToolRegistration, type AllemProvider, type UseAllemAgentOptions, type UseAllemAgentReturn, useAgentTools, useAllemAgent };

package/dist/client.js

@@ -0,0 +1,138 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  AgentProvider: () => AgentProvider,
+  useAgentTools: () => useAgentTools,
+  useAllemAgent: () => useAllemAgent
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/useAllemAgent.ts
+var import_react = require("react");
+var import_react2 = require("@ai-sdk/react");
+var import_ai = require("ai");
+var import_ai2 = require("@allem-sdk/ai");
+function deriveAgentState(messages, chatStatus) {
+  const steps = [];
+  const allToolCalls = [];
+  let stepIndex = 0;
+  const isActive = chatStatus === "submitted" || chatStatus === "streaming";
+  for (const msg of messages) {
+    if (msg.role !== "assistant" || !msg.parts) continue;
+    const stepToolCalls = [];
+    for (const part of msg.parts) {
+      if (part.type === "tool-invocation") {
+        const invocation = part;
+        stepToolCalls.push({
+          toolCallId: invocation.toolInvocationId,
+          toolName: invocation.toolName,
+          args: invocation.args
+        });
+      }
+    }
+    if (stepToolCalls.length > 0) {
+      steps.push({
+        stepIndex,
+        toolCalls: stepToolCalls,
+        startedAt: Date.now()
+      });
+      stepIndex++;
+      allToolCalls.push(...stepToolCalls);
+    }
+  }
+  const lastMsg = messages[messages.length - 1];
+  const hasToolCalls = allToolCalls.length > 0;
+  const lastIsAssistantText = lastMsg?.role === "assistant" && lastMsg.parts?.some((p) => p.type === "text");
+  let agentStatus;
+  if (!isActive && messages.length === 0) {
+    agentStatus = "idle";
+  } else if (isActive && hasToolCalls && !lastIsAssistantText) {
+    agentStatus = "calling-tool";
+  } else if (isActive) {
+    agentStatus = "thinking";
+  } else if (messages.length > 0) {
+    agentStatus = "done";
+  } else {
+    agentStatus = "idle";
+  }
+  const currentToolCalls = steps.length > 0 ? steps[steps.length - 1].toolCalls : [];
+  return { agentStatus, steps, currentToolCalls, isAgentRunning: isActive };
+}
+function useAllemAgent(options = {}) {
+  const config = (0, import_ai2.useAllemAIConfig)();
+  const {
+    api,
+    model,
+    provider,
+    systemPrompt,
+    headers,
+    experimental_throttle,
+    ...restOptions
+  } = options;
+  const resolvedApi = api ?? config.api;
+  const resolvedModel = model ?? config.model;
+  const resolvedProvider = provider ?? config.provider;
+  const resolvedHeaders = { ...config.headers, ...headers };
+  const transport = new import_ai.DefaultChatTransport({
+    api: resolvedApi,
+    headers: resolvedHeaders,
+    body: {
+      ...resolvedModel && { model: resolvedModel },
+      ...resolvedProvider && { provider: resolvedProvider },
+      ...systemPrompt && { systemPrompt }
+    }
+  });
+  const chatHelpers = (0, import_react2.useChat)({
+    transport,
+    experimental_throttle,
+    ...restOptions
+  });
+  const { agentStatus, steps, currentToolCalls, isAgentRunning } = (0, import_react.useMemo)(
+    () => deriveAgentState(chatHelpers.messages, chatHelpers.status),
+    [chatHelpers.messages, chatHelpers.status]
+  );
+  return {
+    ...chatHelpers,
+    agentStatus,
+    steps,
+    currentToolCalls,
+    isAgentRunning
+  };
+}
+
+// src/AgentProvider.tsx
+var import_react3 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var AgentContext = (0, import_react3.createContext)({ tools: [] });
+function AgentProvider({ tools = [], children }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AgentContext.Provider, { value: { tools }, children });
+}
+function useAgentTools() {
+  return (0, import_react3.useContext)(AgentContext).tools;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentProvider,
+  useAgentTools,
+  useAllemAgent
+});

package/dist/client.mjs

@@ -0,0 +1,110 @@
+"use client";
+
+// src/useAllemAgent.ts
+import { useMemo } from "react";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useAllemAIConfig } from "@allem-sdk/ai";
+function deriveAgentState(messages, chatStatus) {
+  const steps = [];
+  const allToolCalls = [];
+  let stepIndex = 0;
+  const isActive = chatStatus === "submitted" || chatStatus === "streaming";
+  for (const msg of messages) {
+    if (msg.role !== "assistant" || !msg.parts) continue;
+    const stepToolCalls = [];
+    for (const part of msg.parts) {
+      if (part.type === "tool-invocation") {
+        const invocation = part;
+        stepToolCalls.push({
+          toolCallId: invocation.toolInvocationId,
+          toolName: invocation.toolName,
+          args: invocation.args
+        });
+      }
+    }
+    if (stepToolCalls.length > 0) {
+      steps.push({
+        stepIndex,
+        toolCalls: stepToolCalls,
+        startedAt: Date.now()
+      });
+      stepIndex++;
+      allToolCalls.push(...stepToolCalls);
+    }
+  }
+  const lastMsg = messages[messages.length - 1];
+  const hasToolCalls = allToolCalls.length > 0;
+  const lastIsAssistantText = lastMsg?.role === "assistant" && lastMsg.parts?.some((p) => p.type === "text");
+  let agentStatus;
+  if (!isActive && messages.length === 0) {
+    agentStatus = "idle";
+  } else if (isActive && hasToolCalls && !lastIsAssistantText) {
+    agentStatus = "calling-tool";
+  } else if (isActive) {
+    agentStatus = "thinking";
+  } else if (messages.length > 0) {
+    agentStatus = "done";
+  } else {
+    agentStatus = "idle";
+  }
+  const currentToolCalls = steps.length > 0 ? steps[steps.length - 1].toolCalls : [];
+  return { agentStatus, steps, currentToolCalls, isAgentRunning: isActive };
+}
+function useAllemAgent(options = {}) {
+  const config = useAllemAIConfig();
+  const {
+    api,
+    model,
+    provider,
+    systemPrompt,
+    headers,
+    experimental_throttle,
+    ...restOptions
+  } = options;
+  const resolvedApi = api ?? config.api;
+  const resolvedModel = model ?? config.model;
+  const resolvedProvider = provider ?? config.provider;
+  const resolvedHeaders = { ...config.headers, ...headers };
+  const transport = new DefaultChatTransport({
+    api: resolvedApi,
+    headers: resolvedHeaders,
+    body: {
+      ...resolvedModel && { model: resolvedModel },
+      ...resolvedProvider && { provider: resolvedProvider },
+      ...systemPrompt && { systemPrompt }
+    }
+  });
+  const chatHelpers = useChat({
+    transport,
+    experimental_throttle,
+    ...restOptions
+  });
+  const { agentStatus, steps, currentToolCalls, isAgentRunning } = useMemo(
+    () => deriveAgentState(chatHelpers.messages, chatHelpers.status),
+    [chatHelpers.messages, chatHelpers.status]
+  );
+  return {
+    ...chatHelpers,
+    agentStatus,
+    steps,
+    currentToolCalls,
+    isAgentRunning
+  };
+}
+
+// src/AgentProvider.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var AgentContext = createContext({ tools: [] });
+function AgentProvider({ tools = [], children }) {
+  return /* @__PURE__ */ jsx(AgentContext.Provider, { value: { tools }, children });
+}
+function useAgentTools() {
+  return useContext(AgentContext).tools;
+}
+export {
+  AgentProvider,
+  useAgentTools,
+  useAllemAgent
+};

package/dist/index.d.mts

@@ -0,0 +1,98 @@
+import { UseChatHelpers } from '@ai-sdk/react';
+import { ChatInit, UIMessage, LanguageModel, ToolSet } from 'ai';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { z } from 'zod';
+
+type AgentStatus = "idle" | "thinking" | "calling-tool" | "done";
+interface AgentToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+interface AgentStep {
+    stepIndex: number;
+    toolCalls: AgentToolCall[];
+    startedAt: number;
+}
+interface AgentToolRegistration {
+    name: string;
+    description?: string;
+}
+
+type AllemProvider = "google" | "anthropic" | "openai";
+interface UseAllemAgentOptions extends Omit<ChatInit<UIMessage>, "transport"> {
+    /** Override the API endpoint from AllemAIProvider. */
+    api?: string;
+    /** Model identifier sent in the request body. */
+    model?: string;
+    /** Provider name sent in the request body. */
+    provider?: AllemProvider;
+    /** System prompt sent in the request body. */
+    systemPrompt?: string;
+    /** Extra headers merged with AllemAIProvider headers. */
+    headers?: Record<string, string>;
+    /** Custom throttle wait in ms for updates. */
+    experimental_throttle?: number;
+}
+interface UseAllemAgentReturn extends UseChatHelpers<UIMessage> {
+    /** Current agent lifecycle status. */
+    agentStatus: AgentStatus;
+    /** Ordered list of steps taken in the current turn. */
+    steps: AgentStep[];
+    /** The tool calls from the most recent step, if any. */
+    currentToolCalls: AgentToolCall[];
+    /** Whether the agent is actively processing. */
+    isAgentRunning: boolean;
+}
+declare function useAllemAgent(options?: UseAllemAgentOptions): UseAllemAgentReturn;
+
+interface AgentProviderProps {
+    /** Tool metadata for client-side display (names and descriptions). */
+    tools?: AgentToolRegistration[];
+    children: ReactNode;
+}
+declare function AgentProvider({ tools, children }: AgentProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAgentTools(): AgentToolRegistration[];
+
+type AllemProviderName = "google" | "anthropic" | "openai";
+interface AllemAgentHandlerConfig {
+    /** Map of provider name to a function that returns a LanguageModel for a given model ID. */
+    providers: Partial<Record<AllemProviderName, (modelId?: string) => LanguageModel>>;
+    /** Default provider when none is specified in the request. Default: "google". */
+    defaultProvider?: AllemProviderName;
+    /** Default model ID when none is specified in the request. */
+    defaultModel?: string;
+    /** Default system prompt. */
+    systemPrompt?: string;
+    /** Tools available to the agent. */
+    tools?: ToolSet;
+}
+declare function createAllemAgentHandler(config: AllemAgentHandlerConfig): (req: Request) => Promise<Response>;
+
+interface AllemToolConfig<TParams extends z.ZodType> {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.infer<TParams>) => Promise<unknown>;
+}
+/**
+ * Creates a tool definition compatible with Vercel AI SDK's streamText tools.
+ *
+ * @example
+ * ```ts
+ * const weather = createAllemTool({
+ *   description: "Get the weather for a city",
+ *   parameters: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => ({ temp: 72 }),
+ * });
+ *
+ * createAllemAgentHandler({ tools: { weather }, ... });
+ * ```
+ */
+declare function createAllemTool<TParams extends z.ZodType>(config: AllemToolConfig<TParams>): {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.core.output<TParams>) => Promise<unknown>;
+};
+
+export { AgentProvider, type AgentProviderProps, type AgentStatus, type AgentStep, type AgentToolCall, type AgentToolRegistration, type AllemAgentHandlerConfig, type AllemProvider, type AllemProviderName, type AllemToolConfig, type UseAllemAgentOptions, type UseAllemAgentReturn, createAllemAgentHandler, createAllemTool, useAgentTools, useAllemAgent };

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { UseChatHelpers } from '@ai-sdk/react';
+import { ChatInit, UIMessage, LanguageModel, ToolSet } from 'ai';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { z } from 'zod';
+
+type AgentStatus = "idle" | "thinking" | "calling-tool" | "done";
+interface AgentToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+interface AgentStep {
+    stepIndex: number;
+    toolCalls: AgentToolCall[];
+    startedAt: number;
+}
+interface AgentToolRegistration {
+    name: string;
+    description?: string;
+}
+
+type AllemProvider = "google" | "anthropic" | "openai";
+interface UseAllemAgentOptions extends Omit<ChatInit<UIMessage>, "transport"> {
+    /** Override the API endpoint from AllemAIProvider. */
+    api?: string;
+    /** Model identifier sent in the request body. */
+    model?: string;
+    /** Provider name sent in the request body. */
+    provider?: AllemProvider;
+    /** System prompt sent in the request body. */
+    systemPrompt?: string;
+    /** Extra headers merged with AllemAIProvider headers. */
+    headers?: Record<string, string>;
+    /** Custom throttle wait in ms for updates. */
+    experimental_throttle?: number;
+}
+interface UseAllemAgentReturn extends UseChatHelpers<UIMessage> {
+    /** Current agent lifecycle status. */
+    agentStatus: AgentStatus;
+    /** Ordered list of steps taken in the current turn. */
+    steps: AgentStep[];
+    /** The tool calls from the most recent step, if any. */
+    currentToolCalls: AgentToolCall[];
+    /** Whether the agent is actively processing. */
+    isAgentRunning: boolean;
+}
+declare function useAllemAgent(options?: UseAllemAgentOptions): UseAllemAgentReturn;
+
+interface AgentProviderProps {
+    /** Tool metadata for client-side display (names and descriptions). */
+    tools?: AgentToolRegistration[];
+    children: ReactNode;
+}
+declare function AgentProvider({ tools, children }: AgentProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAgentTools(): AgentToolRegistration[];
+
+type AllemProviderName = "google" | "anthropic" | "openai";
+interface AllemAgentHandlerConfig {
+    /** Map of provider name to a function that returns a LanguageModel for a given model ID. */
+    providers: Partial<Record<AllemProviderName, (modelId?: string) => LanguageModel>>;
+    /** Default provider when none is specified in the request. Default: "google". */
+    defaultProvider?: AllemProviderName;
+    /** Default model ID when none is specified in the request. */
+    defaultModel?: string;
+    /** Default system prompt. */
+    systemPrompt?: string;
+    /** Tools available to the agent. */
+    tools?: ToolSet;
+}
+declare function createAllemAgentHandler(config: AllemAgentHandlerConfig): (req: Request) => Promise<Response>;
+
+interface AllemToolConfig<TParams extends z.ZodType> {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.infer<TParams>) => Promise<unknown>;
+}
+/**
+ * Creates a tool definition compatible with Vercel AI SDK's streamText tools.
+ *
+ * @example
+ * ```ts
+ * const weather = createAllemTool({
+ *   description: "Get the weather for a city",
+ *   parameters: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => ({ temp: 72 }),
+ * });
+ *
+ * createAllemAgentHandler({ tools: { weather }, ... });
+ * ```
+ */
+declare function createAllemTool<TParams extends z.ZodType>(config: AllemToolConfig<TParams>): {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.core.output<TParams>) => Promise<unknown>;
+};
+
+export { AgentProvider, type AgentProviderProps, type AgentStatus, type AgentStep, type AgentToolCall, type AgentToolRegistration, type AllemAgentHandlerConfig, type AllemProvider, type AllemProviderName, type AllemToolConfig, type UseAllemAgentOptions, type UseAllemAgentReturn, createAllemAgentHandler, createAllemTool, useAgentTools, useAllemAgent };

package/dist/index.js

@@ -0,0 +1,184 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AgentProvider: () => AgentProvider,
+  createAllemAgentHandler: () => createAllemAgentHandler,
+  createAllemTool: () => createAllemTool,
+  useAgentTools: () => useAgentTools,
+  useAllemAgent: () => useAllemAgent
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/useAllemAgent.ts
+var import_react = require("react");
+var import_react2 = require("@ai-sdk/react");
+var import_ai = require("ai");
+var import_ai2 = require("@allem-sdk/ai");
+function deriveAgentState(messages, chatStatus) {
+  const steps = [];
+  const allToolCalls = [];
+  let stepIndex = 0;
+  const isActive = chatStatus === "submitted" || chatStatus === "streaming";
+  for (const msg of messages) {
+    if (msg.role !== "assistant" || !msg.parts) continue;
+    const stepToolCalls = [];
+    for (const part of msg.parts) {
+      if (part.type === "tool-invocation") {
+        const invocation = part;
+        stepToolCalls.push({
+          toolCallId: invocation.toolInvocationId,
+          toolName: invocation.toolName,
+          args: invocation.args
+        });
+      }
+    }
+    if (stepToolCalls.length > 0) {
+      steps.push({
+        stepIndex,
+        toolCalls: stepToolCalls,
+        startedAt: Date.now()
+      });
+      stepIndex++;
+      allToolCalls.push(...stepToolCalls);
+    }
+  }
+  const lastMsg = messages[messages.length - 1];
+  const hasToolCalls = allToolCalls.length > 0;
+  const lastIsAssistantText = lastMsg?.role === "assistant" && lastMsg.parts?.some((p) => p.type === "text");
+  let agentStatus;
+  if (!isActive && messages.length === 0) {
+    agentStatus = "idle";
+  } else if (isActive && hasToolCalls && !lastIsAssistantText) {
+    agentStatus = "calling-tool";
+  } else if (isActive) {
+    agentStatus = "thinking";
+  } else if (messages.length > 0) {
+    agentStatus = "done";
+  } else {
+    agentStatus = "idle";
+  }
+  const currentToolCalls = steps.length > 0 ? steps[steps.length - 1].toolCalls : [];
+  return { agentStatus, steps, currentToolCalls, isAgentRunning: isActive };
+}
+function useAllemAgent(options = {}) {
+  const config = (0, import_ai2.useAllemAIConfig)();
+  const {
+    api,
+    model,
+    provider,
+    systemPrompt,
+    headers,
+    experimental_throttle,
+    ...restOptions
+  } = options;
+  const resolvedApi = api ?? config.api;
+  const resolvedModel = model ?? config.model;
+  const resolvedProvider = provider ?? config.provider;
+  const resolvedHeaders = { ...config.headers, ...headers };
+  const transport = new import_ai.DefaultChatTransport({
+    api: resolvedApi,
+    headers: resolvedHeaders,
+    body: {
+      ...resolvedModel && { model: resolvedModel },
+      ...resolvedProvider && { provider: resolvedProvider },
+      ...systemPrompt && { systemPrompt }
+    }
+  });
+  const chatHelpers = (0, import_react2.useChat)({
+    transport,
+    experimental_throttle,
+    ...restOptions
+  });
+  const { agentStatus, steps, currentToolCalls, isAgentRunning } = (0, import_react.useMemo)(
+    () => deriveAgentState(chatHelpers.messages, chatHelpers.status),
+    [chatHelpers.messages, chatHelpers.status]
+  );
+  return {
+    ...chatHelpers,
+    agentStatus,
+    steps,
+    currentToolCalls,
+    isAgentRunning
+  };
+}
+
+// src/AgentProvider.tsx
+var import_react3 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var AgentContext = (0, import_react3.createContext)({ tools: [] });
+function AgentProvider({ tools = [], children }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AgentContext.Provider, { value: { tools }, children });
+}
+function useAgentTools() {
+  return (0, import_react3.useContext)(AgentContext).tools;
+}
+
+// src/createAllemAgentHandler.ts
+var import_ai3 = require("ai");
+function createAllemAgentHandler(config) {
+  const {
+    providers,
+    defaultProvider = "google",
+    defaultModel,
+    systemPrompt: defaultSystemPrompt,
+    tools
+  } = config;
+  return async function handler(req) {
+    const body = await req.json();
+    const providerName = body.provider ?? defaultProvider;
+    const modelId = body.model ?? defaultModel;
+    const system = body.systemPrompt ?? defaultSystemPrompt;
+    const providerFactory = providers[providerName];
+    if (!providerFactory) {
+      return new Response(
+        JSON.stringify({ error: `Provider "${providerName}" is not configured.` }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    const model = providerFactory(modelId);
+    const modelMessages = await (0, import_ai3.convertToModelMessages)(body.messages);
+    const result = (0, import_ai3.streamText)({
+      model,
+      system,
+      messages: modelMessages,
+      tools
+    });
+    return result.toUIMessageStreamResponse();
+  };
+}
+
+// src/createAllemTool.ts
+function createAllemTool(config) {
+  return {
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentProvider,
+  createAllemAgentHandler,
+  createAllemTool,
+  useAgentTools,
+  useAllemAgent
+});

package/dist/index.mjs

@@ -0,0 +1,156 @@
+// src/useAllemAgent.ts
+import { useMemo } from "react";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useAllemAIConfig } from "@allem-sdk/ai";
+function deriveAgentState(messages, chatStatus) {
+  const steps = [];
+  const allToolCalls = [];
+  let stepIndex = 0;
+  const isActive = chatStatus === "submitted" || chatStatus === "streaming";
+  for (const msg of messages) {
+    if (msg.role !== "assistant" || !msg.parts) continue;
+    const stepToolCalls = [];
+    for (const part of msg.parts) {
+      if (part.type === "tool-invocation") {
+        const invocation = part;
+        stepToolCalls.push({
+          toolCallId: invocation.toolInvocationId,
+          toolName: invocation.toolName,
+          args: invocation.args
+        });
+      }
+    }
+    if (stepToolCalls.length > 0) {
+      steps.push({
+        stepIndex,
+        toolCalls: stepToolCalls,
+        startedAt: Date.now()
+      });
+      stepIndex++;
+      allToolCalls.push(...stepToolCalls);
+    }
+  }
+  const lastMsg = messages[messages.length - 1];
+  const hasToolCalls = allToolCalls.length > 0;
+  const lastIsAssistantText = lastMsg?.role === "assistant" && lastMsg.parts?.some((p) => p.type === "text");
+  let agentStatus;
+  if (!isActive && messages.length === 0) {
+    agentStatus = "idle";
+  } else if (isActive && hasToolCalls && !lastIsAssistantText) {
+    agentStatus = "calling-tool";
+  } else if (isActive) {
+    agentStatus = "thinking";
+  } else if (messages.length > 0) {
+    agentStatus = "done";
+  } else {
+    agentStatus = "idle";
+  }
+  const currentToolCalls = steps.length > 0 ? steps[steps.length - 1].toolCalls : [];
+  return { agentStatus, steps, currentToolCalls, isAgentRunning: isActive };
+}
+function useAllemAgent(options = {}) {
+  const config = useAllemAIConfig();
+  const {
+    api,
+    model,
+    provider,
+    systemPrompt,
+    headers,
+    experimental_throttle,
+    ...restOptions
+  } = options;
+  const resolvedApi = api ?? config.api;
+  const resolvedModel = model ?? config.model;
+  const resolvedProvider = provider ?? config.provider;
+  const resolvedHeaders = { ...config.headers, ...headers };
+  const transport = new DefaultChatTransport({
+    api: resolvedApi,
+    headers: resolvedHeaders,
+    body: {
+      ...resolvedModel && { model: resolvedModel },
+      ...resolvedProvider && { provider: resolvedProvider },
+      ...systemPrompt && { systemPrompt }
+    }
+  });
+  const chatHelpers = useChat({
+    transport,
+    experimental_throttle,
+    ...restOptions
+  });
+  const { agentStatus, steps, currentToolCalls, isAgentRunning } = useMemo(
+    () => deriveAgentState(chatHelpers.messages, chatHelpers.status),
+    [chatHelpers.messages, chatHelpers.status]
+  );
+  return {
+    ...chatHelpers,
+    agentStatus,
+    steps,
+    currentToolCalls,
+    isAgentRunning
+  };
+}
+
+// src/AgentProvider.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var AgentContext = createContext({ tools: [] });
+function AgentProvider({ tools = [], children }) {
+  return /* @__PURE__ */ jsx(AgentContext.Provider, { value: { tools }, children });
+}
+function useAgentTools() {
+  return useContext(AgentContext).tools;
+}
+
+// src/createAllemAgentHandler.ts
+import {
+  streamText,
+  convertToModelMessages
+} from "ai";
+function createAllemAgentHandler(config) {
+  const {
+    providers,
+    defaultProvider = "google",
+    defaultModel,
+    systemPrompt: defaultSystemPrompt,
+    tools
+  } = config;
+  return async function handler(req) {
+    const body = await req.json();
+    const providerName = body.provider ?? defaultProvider;
+    const modelId = body.model ?? defaultModel;
+    const system = body.systemPrompt ?? defaultSystemPrompt;
+    const providerFactory = providers[providerName];
+    if (!providerFactory) {
+      return new Response(
+        JSON.stringify({ error: `Provider "${providerName}" is not configured.` }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    const model = providerFactory(modelId);
+    const modelMessages = await convertToModelMessages(body.messages);
+    const result = streamText({
+      model,
+      system,
+      messages: modelMessages,
+      tools
+    });
+    return result.toUIMessageStreamResponse();
+  };
+}
+
+// src/createAllemTool.ts
+function createAllemTool(config) {
+  return {
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute
+  };
+}
+export {
+  AgentProvider,
+  createAllemAgentHandler,
+  createAllemTool,
+  useAgentTools,
+  useAllemAgent
+};

package/dist/server.d.mts

@@ -0,0 +1,44 @@
+import { LanguageModel, ToolSet } from 'ai';
+import { z } from 'zod';
+
+type AllemProviderName = "google" | "anthropic" | "openai";
+interface AllemAgentHandlerConfig {
+    /** Map of provider name to a function that returns a LanguageModel for a given model ID. */
+    providers: Partial<Record<AllemProviderName, (modelId?: string) => LanguageModel>>;
+    /** Default provider when none is specified in the request. Default: "google". */
+    defaultProvider?: AllemProviderName;
+    /** Default model ID when none is specified in the request. */
+    defaultModel?: string;
+    /** Default system prompt. */
+    systemPrompt?: string;
+    /** Tools available to the agent. */
+    tools?: ToolSet;
+}
+declare function createAllemAgentHandler(config: AllemAgentHandlerConfig): (req: Request) => Promise<Response>;
+
+interface AllemToolConfig<TParams extends z.ZodType> {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.infer<TParams>) => Promise<unknown>;
+}
+/**
+ * Creates a tool definition compatible with Vercel AI SDK's streamText tools.
+ *
+ * @example
+ * ```ts
+ * const weather = createAllemTool({
+ *   description: "Get the weather for a city",
+ *   parameters: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => ({ temp: 72 }),
+ * });
+ *
+ * createAllemAgentHandler({ tools: { weather }, ... });
+ * ```
+ */
+declare function createAllemTool<TParams extends z.ZodType>(config: AllemToolConfig<TParams>): {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.core.output<TParams>) => Promise<unknown>;
+};
+
+export { type AllemAgentHandlerConfig, type AllemProviderName, type AllemToolConfig, createAllemAgentHandler, createAllemTool };

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+import { LanguageModel, ToolSet } from 'ai';
+import { z } from 'zod';
+
+type AllemProviderName = "google" | "anthropic" | "openai";
+interface AllemAgentHandlerConfig {
+    /** Map of provider name to a function that returns a LanguageModel for a given model ID. */
+    providers: Partial<Record<AllemProviderName, (modelId?: string) => LanguageModel>>;
+    /** Default provider when none is specified in the request. Default: "google". */
+    defaultProvider?: AllemProviderName;
+    /** Default model ID when none is specified in the request. */
+    defaultModel?: string;
+    /** Default system prompt. */
+    systemPrompt?: string;
+    /** Tools available to the agent. */
+    tools?: ToolSet;
+}
+declare function createAllemAgentHandler(config: AllemAgentHandlerConfig): (req: Request) => Promise<Response>;
+
+interface AllemToolConfig<TParams extends z.ZodType> {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.infer<TParams>) => Promise<unknown>;
+}
+/**
+ * Creates a tool definition compatible with Vercel AI SDK's streamText tools.
+ *
+ * @example
+ * ```ts
+ * const weather = createAllemTool({
+ *   description: "Get the weather for a city",
+ *   parameters: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => ({ temp: 72 }),
+ * });
+ *
+ * createAllemAgentHandler({ tools: { weather }, ... });
+ * ```
+ */
+declare function createAllemTool<TParams extends z.ZodType>(config: AllemToolConfig<TParams>): {
+    description: string;
+    parameters: TParams;
+    execute: (params: z.core.output<TParams>) => Promise<unknown>;
+};
+
+export { type AllemAgentHandlerConfig, type AllemProviderName, type AllemToolConfig, createAllemAgentHandler, createAllemTool };

package/dist/server.js

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  createAllemAgentHandler: () => createAllemAgentHandler,
+  createAllemTool: () => createAllemTool
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/createAllemAgentHandler.ts
+var import_ai = require("ai");
+function createAllemAgentHandler(config) {
+  const {
+    providers,
+    defaultProvider = "google",
+    defaultModel,
+    systemPrompt: defaultSystemPrompt,
+    tools
+  } = config;
+  return async function handler(req) {
+    const body = await req.json();
+    const providerName = body.provider ?? defaultProvider;
+    const modelId = body.model ?? defaultModel;
+    const system = body.systemPrompt ?? defaultSystemPrompt;
+    const providerFactory = providers[providerName];
+    if (!providerFactory) {
+      return new Response(
+        JSON.stringify({ error: `Provider "${providerName}" is not configured.` }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    const model = providerFactory(modelId);
+    const modelMessages = await (0, import_ai.convertToModelMessages)(body.messages);
+    const result = (0, import_ai.streamText)({
+      model,
+      system,
+      messages: modelMessages,
+      tools
+    });
+    return result.toUIMessageStreamResponse();
+  };
+}
+
+// src/createAllemTool.ts
+function createAllemTool(config) {
+  return {
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAllemAgentHandler,
+  createAllemTool
+});

package/dist/server.mjs

@@ -0,0 +1,49 @@
+// src/createAllemAgentHandler.ts
+import {
+  streamText,
+  convertToModelMessages
+} from "ai";
+function createAllemAgentHandler(config) {
+  const {
+    providers,
+    defaultProvider = "google",
+    defaultModel,
+    systemPrompt: defaultSystemPrompt,
+    tools
+  } = config;
+  return async function handler(req) {
+    const body = await req.json();
+    const providerName = body.provider ?? defaultProvider;
+    const modelId = body.model ?? defaultModel;
+    const system = body.systemPrompt ?? defaultSystemPrompt;
+    const providerFactory = providers[providerName];
+    if (!providerFactory) {
+      return new Response(
+        JSON.stringify({ error: `Provider "${providerName}" is not configured.` }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    const model = providerFactory(modelId);
+    const modelMessages = await convertToModelMessages(body.messages);
+    const result = streamText({
+      model,
+      system,
+      messages: modelMessages,
+      tools
+    });
+    return result.toUIMessageStreamResponse();
+  };
+}
+
+// src/createAllemTool.ts
+function createAllemTool(config) {
+  return {
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute
+  };
+}
+export {
+  createAllemAgentHandler,
+  createAllemTool
+};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@allem-sdk/agents",
+  "version": "0.2.0",
+  "description": "Agentic AI hooks for React with multi-step tool calling, status tracking, and typed tool definitions. Built on Vercel AI SDK.",
+  "license": "MIT",
+  "author": "Ahmed Allem",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@ai-sdk/react": "^3.0.187",
+    "@types/react": "^19.0.0",
+    "ai": "^6.0.185",
+    "react": "^19.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "@allem-sdk/ai": "0.1.1"
+  },
+  "peerDependencies": {
+    "@allem-sdk/ai": ">=0.1.0",
+    "@ai-sdk/react": ">=3.0.0",
+    "ai": ">=6.0.0",
+    "react": ">=18.0.0",
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kingofmit/allem-sdk.git",
+    "directory": "packages/agents"
+  },
+  "keywords": [
+    "allem-sdk",
+    "agents",
+    "ai",
+    "react",
+    "hooks",
+    "tools",
+    "multi-step",
+    "vercel-ai-sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}