# Axiom Lattice React SDK

React hooks for interacting with the Axiom Lattice Agent Service API.

## Overview

This package provides React hooks that wrap the Axiom Lattice Client SDK, making it easy to integrate agent capabilities into your React applications. It includes hooks for managing threads, sending and receiving messages, monitoring agent state, and more.

## Architecture

```mermaid
flowchart TD
    subgraph "Client SDK"
        ClientSDK["@axiom-lattice/client-sdk"]
        Client["Client Class"]
        ClientTypes["Types"]

        ClientSDK --> Client
        ClientSDK --> ClientTypes
    end

    subgraph "React SDK"
        ReactSDK["@axiom-lattice/react-sdk"]

        subgraph "Context"
            Provider["AxiomLatticeProvider"]
            useAxiomLattice["useAxiomLattice()"]
        end

        subgraph "Hooks"
            useThread["useThread()"]
            useChat["useChat()"]
            useAgentState["useAgentState()"]
            useAgentGraph["useAgentGraph()"]
        end

        ReactTypes["Types"]
        Examples["Example Components"]

        ReactSDK --> Provider
        ReactSDK --> useAxiomLattice
        ReactSDK --> useThread
        ReactSDK --> useChat
        ReactSDK --> useAgentState
        ReactSDK --> useAgentGraph
        ReactSDK --> ReactTypes
        ReactSDK --> Examples
    end

    Client --> useAxiomLattice
    useAxiomLattice --> useThread
    useAxiomLattice --> useChat
    useAxiomLattice --> useAgentState
    useAxiomLattice --> useAgentGraph

    subgraph "React Application"
        AppComponent["App Component"]
        ChatComponent["Chat Component"]
        ThreadList["Thread List"]
        StateMonitor["State Monitor"]
    end

    Provider --> AppComponent
    useThread --> ThreadList
    useChat --> ChatComponent
    useAgentState --> StateMonitor
```

## Installation

```bash
npm install @axiom-lattice/react-sdk
# or
yarn add @axiom-lattice/react-sdk
# or
pnpm add @axiom-lattice/react-sdk
```

## Features

- React hooks for all client SDK functionality
- React context provider for configuration
- TypeScript support
- Simplified state management for threads and messages
- Streaming support with React state updates

## Usage

### Provider Setup

First, wrap your application with the `AxiomLatticeProvider` to provide the client configuration:

```tsx
import { AxiomLatticeProvider } from "@axiom-lattice/react-sdk";

function App() {
  return (
    <AxiomLatticeProvider
      config={{
        baseURL: "https://api.example.com",
        apiKey: "your-api-key",
        assistantId: "your-assistant-id",
        transport: "sse",
      }}
    >
      <YourApp />
    </AxiomLatticeProvider>
  );
}
```

### Thread Management

Use the `useThread` hook to manage threads:

```tsx
import { useThread } from "@axiom-lattice/react-sdk";

function ThreadManager() {
  const {
    threads,
    currentThread,
    isLoading,
    error,
    createThread,
    getThread,
    listThreads,
    deleteThread,
    selectThread,
  } = useThread();

  useEffect(() => {
    // Load all threads on component mount
    listThreads();
  }, [listThreads]);

  const handleCreateThread = async () => {
    try {
      const threadId = await createThread();
      console.log(`Created thread: ${threadId}`);
    } catch (error) {
      console.error("Failed to create thread:", error);
    }
  };

  return (
    <div>
      <h2>Threads</h2>
      <button onClick={handleCreateThread} disabled={isLoading}>
        Create New Thread
      </button>

      {error && <div className="error">{error.message}</div>}

      <ul>
        {threads.map((thread) => (
          <li key={thread.id}>
            Thread #{thread.id.substring(0, 8)}
            <button onClick={() => selectThread(thread.id)}>Select</button>
            <button onClick={() => deleteThread(thread.id)}>Delete</button>
          </li>
        ))}
      </ul>

      {currentThread && (
        <div>
          <h3>Current Thread: {currentThread.id.substring(0, 8)}</h3>
        </div>
      )}
    </div>
  );
}
```

### Chat Functionality

Use the `useChat` hook to send and receive messages:

```tsx
import { useChat } from "@axiom-lattice/react-sdk";

function ChatInterface({ threadId }) {
  const {
    messages,
    streamingMessage,
    isLoading,
    error,
    sendMessage,
    stopStreaming,
    loadMessages,
  } = useChat(threadId, { streaming: true });

  const [inputValue, setInputValue] = useState("");

  const handleSend = async () => {
    if (!inputValue.trim()) return;

    try {
      await sendMessage(inputValue);
      setInputValue("");
    } catch (error) {
      console.error("Failed to send message:", error);
    }
  };

  return (
    <div>
      <div className="messages">
        {messages.map((message) => (
          <div key={message.id} className={`message ${message.role}`}>
            <div className="role">{message.role}</div>
            <div className="content">{message.content}</div>
          </div>
        ))}

        {streamingMessage && (
          <div className="message assistant streaming">
            <div className="role">assistant</div>
            <div className="content">{streamingMessage.content}</div>
          </div>
        )}
      </div>

      {error && <div className="error">{error.message}</div>}

      <div className="input-area">
        <input
          type="text"
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          disabled={isLoading}
          placeholder="Type your message..."
          onKeyDown={(e) => {
            if (e.key === "Enter") {
              handleSend();
            }
          }}
        />
        <button onClick={handleSend} disabled={isLoading}>
          Send
        </button>
        {isLoading && <button onClick={stopStreaming}>Stop</button>}
      </div>
    </div>
  );
}
```

### Agent State Monitoring

Use the `useAgentState` hook to monitor agent state:

```tsx
import { useAgentState } from "@axiom-lattice/react-sdk";

function AgentStateMonitor({ threadId }) {
  const { agentState, isLoading, error, startPolling, stopPolling, refresh } =
    useAgentState(threadId, {
      pollingInterval: 3000,
      autoStart: true,
    });

  if (isLoading && !agentState) {
    return <div>Loading agent state...</div>;
  }

  if (error) {
    return <div className="error">Error: {error.message}</div>;
  }

  if (!agentState) {
    return <div>No agent state available</div>;
  }

  return (
    <div>
      <h3>Agent State</h3>
      <button onClick={refresh}>Refresh</button>
      <button onClick={startPolling}>Start Polling</button>
      <button onClick={stopPolling}>Stop Polling</button>

      <div>
        <h4>Messages</h4>
        <pre>{JSON.stringify(agentState.values.messages, null, 2)}</pre>
      </div>

      <div>
        <h4>Tasks</h4>
        <pre>{JSON.stringify(agentState.tasks, null, 2)}</pre>
      </div>
    </div>
  );
}
```

### Agent Graph Visualization

Use the `useAgentGraph` hook to fetch and display the agent graph:

```tsx
import { useAgentGraph } from "@axiom-lattice/react-sdk";

function AgentGraph() {
  const { graphImage, isLoading, error, fetchGraph } = useAgentGraph();

  useEffect(() => {
    fetchGraph();
  }, [fetchGraph]);

  if (isLoading && !graphImage) {
    return <div>Loading graph...</div>;
  }

  if (error) {
    return <div className="error">Error: {error.message}</div>;
  }

  return (
    <div>
      <h3>Agent Graph</h3>
      <button onClick={fetchGraph}>Refresh Graph</button>

      {graphImage && (
        <div className="graph-container">
          <img
            src={`data:image/svg+xml;base64,${graphImage}`}
            alt="Agent Graph"
          />
        </div>
      )}
    </div>
  );
}
```

### File Explorer Component

Use the `FileExplorer` component to display and explore files from the agent state:

```tsx
import { FileExplorer, useChat } from "@axiom-lattice/react-sdk";

function AgentFiles({ threadId }) {
  // Ensure enableReturnStateWhenStreamCompleted is true to get the agent state
  const { agentState } = useChat(threadId, {
    streaming: true,
    enableReturnStateWhenStreamCompleted: true,
  });

  // Extract files from agent state values
  // Assuming agent returns files in agentState.values.files
  const files = agentState?.values?.files || [];

  return (
    <div style={{ height: "500px" }}>
      <h3>Agent Files</h3>
      <FileExplorer files={files} />
    </div>
  );
}
```

## Complete Example

See the `examples` directory for a complete example of a chat application using the React SDK.

## API Reference

### Hooks

- `useThread`: Thread management
- `useChat`: Chat functionality
- `useAgentState`: Agent state monitoring
- `useAgentGraph`: Agent graph visualization

### Context

- `AxiomLatticeProvider`: Provider component for the client
- `useAxiomLattice`: Hook to access the client instance

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
