@antipopp/agno-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 antipopp
+
+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,340 @@
+# @antipopp/agno-react
+
+React hooks for Agno client with full TypeScript support.
+
+## Installation
+
+```bash
+npm install @antipopp/agno-react
+```
+
+This package includes `@antipopp/agno-client` and `@antipopp/agno-types` as dependencies.
+
+## Features
+
+- ✅ **Easy Integration** - Drop-in React hooks for Agno agents
+- ✅ **Context Provider** - Manages client lifecycle automatically
+- ✅ **Real-time Updates** - React state synced with streaming updates
+- ✅ **Type-Safe** - Full TypeScript support
+- ✅ **Familiar API** - Matches the original Agno React hooks design
+
+## Quick Start
+
+### 1. Wrap Your App with AgnoProvider
+
+```tsx
+import { AgnoProvider } from '@antipopp/agno-react';
+
+function App() {
+  return (
+    <AgnoProvider
+      config={{
+        endpoint: 'http://localhost:7777',
+        mode: 'agent',
+        agentId: 'your-agent-id',
+      }}
+    >
+      <YourComponents />
+    </AgnoProvider>
+  );
+}
+```
+
+### 2. Use Hooks in Your Components
+
+```tsx
+import { useAgnoChat, useAgnoActions } from '@antipopp/agno-react';
+
+function ChatComponent() {
+  const { messages, sendMessage, isStreaming, error } = useAgnoChat();
+  const { initialize } = useAgnoActions();
+
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  const handleSend = async () => {
+    await sendMessage('Hello, agent!');
+  };
+
+  return (
+    <div>
+      {messages.map((msg, i) => (
+        <div key={i}>
+          <strong>{msg.role}:</strong> {msg.content}
+        </div>
+      ))}
+      {error && <div>Error: {error}</div>}
+      <button onClick={handleSend} disabled={isStreaming}>
+        {isStreaming ? 'Sending...' : 'Send'}
+      </button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### AgnoProvider
+
+Provider component that creates and manages an `AgnoClient` instance.
+
+```tsx
+<AgnoProvider config={config}>
+  {children}
+</AgnoProvider>
+```
+
+**Props:**
+- `config` (AgnoClientConfig) - Client configuration
+- `children` (ReactNode) - Child components
+
+### useAgnoClient()
+
+Access the underlying `AgnoClient` instance.
+
+```tsx
+const client = useAgnoClient();
+
+// Use client methods directly
+await client.sendMessage('Hello!');
+```
+
+### useAgnoChat()
+
+Main hook for chat interactions.
+
+```tsx
+const {
+  messages,        // ChatMessage[] - Current messages
+  sendMessage,     // (message, options?) => Promise<void>
+  clearMessages,   // () => void
+  isStreaming,     // boolean - Is currently streaming
+  error,           // string | undefined - Current error
+  state,           // ClientState - Full client state
+} = useAgnoChat();
+```
+
+**Methods:**
+
+#### `sendMessage(message, options?)`
+
+```tsx
+// Send a text message
+await sendMessage('Hello!');
+
+// Send with FormData (for file uploads)
+const formData = new FormData();
+formData.append('message', 'Hello!');
+formData.append('file', file);
+await sendMessage(formData);
+
+// Send with custom headers
+await sendMessage('Hello!', {
+  headers: { 'X-Custom': 'value' }
+});
+```
+
+#### `clearMessages()`
+
+```tsx
+clearMessages(); // Clears all messages and resets session
+```
+
+### useAgnoSession()
+
+Hook for session management.
+
+```tsx
+const {
+  sessions,          // SessionEntry[] - Available sessions
+  currentSessionId,  // string | undefined - Current session ID
+  loadSession,       // (sessionId) => Promise<ChatMessage[]>
+  fetchSessions,     // () => Promise<SessionEntry[]>
+  isLoading,         // boolean - Is loading session
+  error,             // string | undefined - Current error
+} = useAgnoSession();
+```
+
+**Example:**
+
+```tsx
+function SessionList() {
+  const { sessions, loadSession, fetchSessions } = useAgnoSession();
+
+  useEffect(() => {
+    fetchSessions();
+  }, [fetchSessions]);
+
+  return (
+    <ul>
+      {sessions.map((session) => (
+        <li key={session.session_id}>
+          <button onClick={() => loadSession(session.session_id)}>
+            {session.session_name}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### useAgnoActions()
+
+Hook for common actions and initialization.
+
+```tsx
+const {
+  initialize,       // () => Promise<{ agents, teams }>
+  checkStatus,      // () => Promise<boolean>
+  fetchAgents,      // () => Promise<AgentDetails[]>
+  fetchTeams,       // () => Promise<TeamDetails[]>
+  updateConfig,     // (updates) => void
+  isInitializing,   // boolean
+  error,            // string | undefined
+} = useAgnoActions();
+```
+
+**Example:**
+
+```tsx
+function InitComponent() {
+  const { initialize, updateConfig, isInitializing } = useAgnoActions();
+  const { state } = useAgnoChat();
+
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  const switchAgent = (agentId: string) => {
+    updateConfig({ agentId, mode: 'agent' });
+  };
+
+  if (isInitializing) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h3>Agents</h3>
+      {state.agents.map((agent) => (
+        <button key={agent.id} onClick={() => switchAgent(agent.id)}>
+          {agent.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+## Complete Example
+
+```tsx
+import { useState, useEffect } from 'react';
+import {
+  AgnoProvider,
+  useAgnoChat,
+  useAgnoSession,
+  useAgnoActions,
+} from '@antipopp/agno-react';
+
+function App() {
+  return (
+    <AgnoProvider
+      config={{
+        endpoint: 'http://localhost:7777',
+        mode: 'agent',
+        agentId: 'my-agent',
+      }}
+    >
+      <ChatApp />
+    </AgnoProvider>
+  );
+}
+
+function ChatApp() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage, isStreaming, error, clearMessages } = useAgnoChat();
+  const { sessions, loadSession, fetchSessions } = useAgnoSession();
+  const { initialize, state } = useAgnoActions();
+
+  useEffect(() => {
+    initialize().then(() => fetchSessions());
+  }, [initialize, fetchSessions]);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!input.trim() || isStreaming) return;
+
+    await sendMessage(input);
+    setInput('');
+  };
+
+  return (
+    <div>
+      <aside>
+        <h2>Sessions</h2>
+        <button onClick={() => clearMessages()}>New Chat</button>
+        <ul>
+          {sessions.map((session) => (
+            <li key={session.session_id}>
+              <button onClick={() => loadSession(session.session_id)}>
+                {session.session_name}
+              </button>
+            </li>
+          ))}
+        </ul>
+      </aside>
+
+      <main>
+        <div className="messages">
+          {messages.map((msg, i) => (
+            <div key={i} className={`message ${msg.role}`}>
+              <strong>{msg.role}:</strong>
+              <p>{msg.content}</p>
+              {msg.tool_calls && (
+                <details>
+                  <summary>Tool Calls</summary>
+                  <pre>{JSON.stringify(msg.tool_calls, null, 2)}</pre>
+                </details>
+              )}
+            </div>
+          ))}
+          {error && <div className="error">Error: {error}</div>}
+        </div>
+
+        <form onSubmit={handleSubmit}>
+          <input
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder="Type a message..."
+            disabled={isStreaming}
+          />
+          <button type="submit" disabled={isStreaming}>
+            {isStreaming ? 'Sending...' : 'Send'}
+          </button>
+        </form>
+      </main>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## TypeScript
+
+All hooks and components are fully typed. Import types as needed:
+
+```typescript
+import type {
+  AgnoClientConfig,
+  ChatMessage,
+  SessionEntry,
+  AgentDetails,
+  TeamDetails,
+} from '@antipopp/agno-react';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { AgnoClient } from '@antipopp/agno-client';
+import * as _antipopp_agno_types from '@antipopp/agno-types';
+import { AgnoClientConfig, ChatMessage, ClientState, SessionEntry, AgentDetails, TeamDetails, ToolCall } from '@antipopp/agno-types';
+export { AgentDetails, AgnoClientConfig, ChatMessage, ClientState, RunEvent, SessionEntry, TeamDetails, ToolCall } from '@antipopp/agno-types';
+
+interface AgnoProviderProps {
+    config: AgnoClientConfig;
+    children: React.ReactNode;
+}
+/**
+ * Provider component that creates and manages an AgnoClient instance
+ */
+declare function AgnoProvider({ config, children }: AgnoProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the AgnoClient instance
+ */
+declare function useAgnoClient(): AgnoClient;
+
+/**
+ * Main hook for chat interactions
+ * Provides messages, state, and methods to interact with the agent
+ */
+declare function useAgnoChat(): {
+    messages: ChatMessage[];
+    sendMessage: (message: string | FormData, options?: {
+        headers?: Record<string, string>;
+    }) => Promise<void>;
+    clearMessages: () => void;
+    isStreaming: boolean;
+    isPaused: boolean;
+    error: string | undefined;
+    state: ClientState;
+};
+
+/**
+ * Hook for session management
+ */
+declare function useAgnoSession(): {
+    sessions: SessionEntry[];
+    currentSessionId: string | undefined;
+    loadSession: (sessionId: string) => Promise<ChatMessage[]>;
+    fetchSessions: () => Promise<SessionEntry[]>;
+    isLoading: boolean;
+    error: string | undefined;
+};
+
+/**
+ * Hook for common actions like initialization, fetching agents/teams
+ */
+declare function useAgnoActions(): {
+    initialize: () => Promise<{
+        agents: AgentDetails[];
+        teams: TeamDetails[];
+    }>;
+    checkStatus: () => Promise<boolean>;
+    fetchAgents: () => Promise<AgentDetails[]>;
+    fetchTeams: () => Promise<TeamDetails[]>;
+    updateConfig: (updates: Partial<Parameters<(updates: Partial<_antipopp_agno_types.AgnoClientConfig>) => void>[0]>) => void;
+    isInitializing: boolean;
+    error: string | undefined;
+};
+
+/**
+ * Tool handler function type
+ */
+type ToolHandler = (args: Record<string, any>) => Promise<any>;
+/**
+ * Tool execution event payload
+ */
+interface ToolExecutionEvent {
+    runId?: string;
+    sessionId?: string;
+    tools: ToolCall[];
+}
+/**
+ * Hook for handling frontend tool execution (HITL)
+ *
+ * @param handlers - Map of tool names to handler functions
+ * @param autoExecute - Whether to automatically execute tools when paused (default: true)
+ *
+ * @example
+ * ```tsx
+ * const toolHandlers = {
+ *   navigate_to_page: async (args) => {
+ *     window.location.href = args.url;
+ *     return { success: true };
+ *   },
+ *   fill_form: async (args) => {
+ *     document.querySelector(args.selector).value = args.value;
+ *     return { filled: true };
+ *   }
+ * };
+ *
+ * const { isPaused, isExecuting, pendingTools } = useAgnoToolExecution(toolHandlers);
+ * ```
+ */
+declare function useAgnoToolExecution(handlers: Record<string, ToolHandler>, autoExecute?: boolean): {
+    /** Whether the run is currently paused awaiting tool execution */
+    isPaused: boolean;
+    /** Whether tools are currently being executed */
+    isExecuting: boolean;
+    /** Tools awaiting execution */
+    pendingTools: ToolCall[];
+    /** Execute all pending tools and continue the run */
+    executeAndContinue: () => Promise<void>;
+    /** Execute specific tools and return results without continuing */
+    executeTools: (tools: ToolCall[]) => Promise<ToolCall[]>;
+    /** Continue the run with manually provided tool results */
+    continueWithResults: (tools: ToolCall[]) => Promise<void>;
+    /** Error from tool execution, if any */
+    executionError: string | undefined;
+};
+
+export { AgnoProvider, type AgnoProviderProps, type ToolExecutionEvent, type ToolHandler, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { AgnoClient } from '@antipopp/agno-client';
+import * as _antipopp_agno_types from '@antipopp/agno-types';
+import { AgnoClientConfig, ChatMessage, ClientState, SessionEntry, AgentDetails, TeamDetails, ToolCall } from '@antipopp/agno-types';
+export { AgentDetails, AgnoClientConfig, ChatMessage, ClientState, RunEvent, SessionEntry, TeamDetails, ToolCall } from '@antipopp/agno-types';
+
+interface AgnoProviderProps {
+    config: AgnoClientConfig;
+    children: React.ReactNode;
+}
+/**
+ * Provider component that creates and manages an AgnoClient instance
+ */
+declare function AgnoProvider({ config, children }: AgnoProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the AgnoClient instance
+ */
+declare function useAgnoClient(): AgnoClient;
+
+/**
+ * Main hook for chat interactions
+ * Provides messages, state, and methods to interact with the agent
+ */
+declare function useAgnoChat(): {
+    messages: ChatMessage[];
+    sendMessage: (message: string | FormData, options?: {
+        headers?: Record<string, string>;
+    }) => Promise<void>;
+    clearMessages: () => void;
+    isStreaming: boolean;
+    isPaused: boolean;
+    error: string | undefined;
+    state: ClientState;
+};
+
+/**
+ * Hook for session management
+ */
+declare function useAgnoSession(): {
+    sessions: SessionEntry[];
+    currentSessionId: string | undefined;
+    loadSession: (sessionId: string) => Promise<ChatMessage[]>;
+    fetchSessions: () => Promise<SessionEntry[]>;
+    isLoading: boolean;
+    error: string | undefined;
+};
+
+/**
+ * Hook for common actions like initialization, fetching agents/teams
+ */
+declare function useAgnoActions(): {
+    initialize: () => Promise<{
+        agents: AgentDetails[];
+        teams: TeamDetails[];
+    }>;
+    checkStatus: () => Promise<boolean>;
+    fetchAgents: () => Promise<AgentDetails[]>;
+    fetchTeams: () => Promise<TeamDetails[]>;
+    updateConfig: (updates: Partial<Parameters<(updates: Partial<_antipopp_agno_types.AgnoClientConfig>) => void>[0]>) => void;
+    isInitializing: boolean;
+    error: string | undefined;
+};
+
+/**
+ * Tool handler function type
+ */
+type ToolHandler = (args: Record<string, any>) => Promise<any>;
+/**
+ * Tool execution event payload
+ */
+interface ToolExecutionEvent {
+    runId?: string;
+    sessionId?: string;
+    tools: ToolCall[];
+}
+/**
+ * Hook for handling frontend tool execution (HITL)
+ *
+ * @param handlers - Map of tool names to handler functions
+ * @param autoExecute - Whether to automatically execute tools when paused (default: true)
+ *
+ * @example
+ * ```tsx
+ * const toolHandlers = {
+ *   navigate_to_page: async (args) => {
+ *     window.location.href = args.url;
+ *     return { success: true };
+ *   },
+ *   fill_form: async (args) => {
+ *     document.querySelector(args.selector).value = args.value;
+ *     return { filled: true };
+ *   }
+ * };
+ *
+ * const { isPaused, isExecuting, pendingTools } = useAgnoToolExecution(toolHandlers);
+ * ```
+ */
+declare function useAgnoToolExecution(handlers: Record<string, ToolHandler>, autoExecute?: boolean): {
+    /** Whether the run is currently paused awaiting tool execution */
+    isPaused: boolean;
+    /** Whether tools are currently being executed */
+    isExecuting: boolean;
+    /** Tools awaiting execution */
+    pendingTools: ToolCall[];
+    /** Execute all pending tools and continue the run */
+    executeAndContinue: () => Promise<void>;
+    /** Execute specific tools and return results without continuing */
+    executeTools: (tools: ToolCall[]) => Promise<ToolCall[]>;
+    /** Continue the run with manually provided tool results */
+    continueWithResults: (tools: ToolCall[]) => Promise<void>;
+    /** Error from tool execution, if any */
+    executionError: string | undefined;
+};
+
+export { AgnoProvider, type AgnoProviderProps, type ToolExecutionEvent, type ToolHandler, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution };