Hydra AI

V 0.1.0 Coming Soon

These are draft docs for the upcoming 0.1.0 release. Read more about the upcoming release here. Have a question about anything in the docs? Send us a message.

Message Threads

Understanding message threads as the foundation of Hydra AI applications.

Message threads are the core building block for creating interactive AI experiences with Hydra. They provide a structured way to manage conversations between users and AI, complete with status tracking, streaming responses, and interactive components.

Core Concepts

A message thread consists of:

  • Messages from both user and AI
  • Status indicators for ongoing operations
  • Streaming state management
  • Interactive components
  • Suggestions for next actions
  • User profiles and context

Available Hooks

Core Thread Management

Thread Core Hooks
// Access thread state and operations
const { messages, operations, suggestions, components } = useHydraThread(threadId);
 
// Access global thread state and operations
const { threads, messages, components, suggestions } = useHydraContext();
 
// Thread lifecycle operations
const {
  create,    // Create new thread with optional title/context
  delete,    // Remove thread
  update,    // Update thread properties
  updateMessageComponent    // Update component state
} = useHydraContext().threads.operations;

Message Management

Message Management Hooks
// Main hook for message generation
const { generate } = useHydraContext().messages;
 
// Access message status
const {
  isThinking,
  thinkingStatus,
  isLoading,
  isStreaming,
  error,
  validationState,
} = useHydraContext().messages.status;
 
// Message streaming status
const { isStreaming, activePaths, validation, partialData, abort } =
  useMessageStreaming();

Thread Operations

Specialized Thread Operations
// Thread filtering and access
const threadsByContext = useHydraContext().threads.getByContext(contextId);
const allThreads = useHydraContext().threads.all;
const threadStates = useHydraContext().threads.state;
 
// Create thread with options
const newThreadId = await threads.operations.create({
  title: "My Thread",
  contextId: "feature-x",
  isAutoTitle: true,
});

Implementation Examples

Basic Message Thread

Basic Message Thread Component
import { useHydraThread, useHydraContext } from "hydra-ai-react";
import { type FormEvent, useState } from "react";
 
function BasicMessageThread({ threadId }) {
  const { messages, suggestions } = useHydraThread(threadId);
  const { generate } = useHydraContext().messages;
  const { isThinking, isLoading, error } = useHydraContext().messages.status;
  const [inputValue, setInputValue] = useState("");
 
  const handleSubmit = async (e) => {
    e.preventDefault();
    if (!inputValue.trim() || isLoading) return;
 
    try {
      await generate(threadId, inputValue);
      setInputValue("");
    } catch (error) {
      console.error("Failed to send message:", error);
    }
  };
 
  return (
    <div className="message-thread">
      {/* Message List */}
      <div className="flex flex-col gap-4">
        {messages.map((message, index) => (
          <div
            key={`${message.type}-${index}`}
            className={`${message.type === "user" ? "ml-auto" : "mr-auto"}`}
          >
            <div>{message.content}</div>
            {message.component && (
              <div className="mt-2">
                {(() => {
                  const Component = message.component.Component;
                  return <Component {...message.component.props} />;
                })()}
              </div>
            )}
            {message.suggestions && message.suggestions.length > 0 && (
              <div className="mt-2">
                {message.suggestions.map((suggestion) => (
                  <button
                    key={suggestion.title}
                    onClick={() => suggestions.accept(suggestion)}
                  >
                    {suggestion.title}
                  </button>
                ))}
              </div>
            )}
          </div>
        ))}
      </div>
 
      {/* Input Form */}
      <form onSubmit={handleSubmit}>
        <input
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          placeholder="Type your message..."
          disabled={isLoading || isThinking}
          className="w-full p-2 border rounded"
        />
        <button
          type="submit"
          disabled={isLoading || isThinking}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          {isThinking ? "Thinking..." : isLoading ? "Sending..." : "Send"}
        </button>
      </form>
    </div>
  );
}

Advanced Features

Message Streaming

Message streaming allows for real-time updates as the AI generates responses:

Streaming Example
function StreamingMessage({ messageId }) {
  const { isStreaming, partialData, abort } = useMessageStreaming();
 
  return (
    <div>
      {isStreaming && <div>Streaming...</div>}
      <div>{partialData?.content}</div>
      <button onClick={abort}>Cancel</button>
    </div>
  );
}

On this page