Suggestions

Hydra AI automatically analyzes user interactions and generates contextual suggestions after each assistant message.

Using Suggestions

The useHydraSuggestions Hook

The main way to interact with suggestions is through the useHydraSuggestions hook:

function ThreadWithSuggestions() {
  const {
    suggestions, // Array of current suggestions
    isLoading, // Whether suggestions are being generated or loading
    isAccepting, // Whether a suggestion is being applied
    error, // Current error message, if any
    accept, // Function to apply a suggestion
  } = useHydraSuggestions({
    maxSuggestions: 3, // Optional: Number of suggestions to generate (1-10)
  });
 
  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage>{error}</ErrorMessage>;
 
  return (
    <div>
      {suggestions.map((suggestion) => (
        <button
          key={suggestion.id}
          onClick={() => accept(suggestion)}
          disabled={isAccepting}
          title={suggestion.title}
        >
          {suggestion.title}
        </button>
      ))}
    </div>
  );
}

Hook Configuration

The useHydraSuggestions hook accepts an optional configuration object:

interface UseHydraSuggestionsOptions {
  /** Maximum number of suggestions to generate (1-10, default 3) */
  maxSuggestions?: number;
}

When Suggestions Appear

Suggestions are automatically generated after each assistant (Hydra) message in the thread. The hook manages:

Loading states while generating suggestions
Error handling for failed generations
Automatic cleanup when messages change

Accepting Suggestions

The accept function provides two modes:

// Just set the suggestion text in the input
accept(suggestion);
 
// Set text and automatically submit
accept(suggestion, true);

Suggestion Types

Basic Suggestion Structure

interface Suggestion {
  /** Unique identifier for the suggestion */
  id: string;
  /** Short title or summary of the suggestion */
  title: string;
  /** Detailed explanation of the suggestion */
  detailedSuggestion: string;
  /** ID of the message this suggestion is for */
  messageId: string;
  /** Additional metadata for the suggestion */
  metadata?: Record<string, string>;
}

State Management Types

The hook uses additional types for state management:

type SuggestionState = {
  /** List of current suggestions */
  items: Suggestion[];
  /** Whether suggestions are currently being loaded */
  loading: boolean;
  /** Current error message, if any */
  error: string | null;
};

Error Handling

The hook provides built-in error handling for common scenarios:

const ERROR_MESSAGES = {
  GENERATION: "Unable to generate suggestions right now",
  EMPTY: "No suggestions available for this message",
  ACCEPT: "Unable to apply suggestion, please try again",
  API_ERROR: "Failed to communicate with Hydra AI",
};

Integration Example

Here's a complete example showing how to integrate suggestions with a message thread:

function MessageThread() {
  const { thread } = useHydraThread();
  const { suggestions, isLoading, isAccepting, error, accept } =
    useHydraSuggestions();
 
  // Get the latest message
  const latestMessage = thread.messages[thread.messages.length - 1];
  const isLatestFromHydra = latestMessage?.role === "assistant";
 
  return (
    <div>
      {/* Messages */}
      {thread.messages.map((message) => (
        <div key={message.id}>{message.content}</div>
      ))}
 
      {/* Suggestions (only shown after Hydra messages) */}
      {isLatestFromHydra && (
        <div className="suggestions">
          {isLoading && <LoadingSpinner />}
          {error && <ErrorMessage>{error}</ErrorMessage>}
          {suggestions.map((suggestion) => (
            <button
              key={suggestion.id}
              onClick={() => accept(suggestion)}
              disabled={isAccepting}
            >
              {suggestion.title}
            </button>
          ))}
        </div>
      )}
    </div>
  );
}

Suggestions are automatically generated for each Hydra message when the useHydraSuggestions hook is used. You don't need to manually trigger suggestion generation.

Suggestions

On this page