ha-text-ai/custom_components/ha_text_ai/services.yaml

ask_question:
  name: Ask Question
  description: >-
    Send a question to the AI model and receive a detailed response.
    The response will be stored in the conversation history and can be retrieved later.
    This service now returns response data directly, eliminating the need to read from sensors.
  fields:
    instance:
      name: Instance
      description: Name of the HA Text AI instance to use
      required: true
      selector:
        entity:
          integration: ha_text_ai
          domain: sensor

    question:
      name: Question
      description: Your question or prompt for the AI assistant
      required: true
      selector:
        text:
          multiline: true
          type: text

    system_prompt:
      name: System Prompt
      description: Optional system prompt to set context for this specific question
      required: false
      selector:
        text:
          multiline: true

    context_messages:
      name: Context Messages
      description: Number of previous messages to include in context (1-20)
      required: false
      default: 5
      selector:
        number:
          min: 1
          max: 20
          step: 1
          mode: slider

    model:
      name: Model
      description: "Select AI model to use (optional, overrides default setting)"
      required: false
      selector:
        text: {}

    temperature:
      name: Temperature
      description: Controls response creativity (0.0-2.0)
      required: false
      default: 0.7
      selector:
        number:
          min: 0.0
          max: 2.0
          step: 0.1
          mode: slider

    max_tokens:
      name: Max Tokens
      description: Maximum length of the response (tokens)
      required: false
      default: 1000
      selector:
        number:
          min: 1
          max: 100000
          step: 1
          mode: box
  response:
    response_text:
      description: "Full AI response text (unlimited length)"
      example: "The answer to your question is..."
    tokens_used:
      description: "Total number of tokens consumed for this request"
      example: 150
    prompt_tokens:
      description: "Number of tokens used for the input prompt"
      example: 50
    completion_tokens:
      description: "Number of tokens used for the AI response"
      example: 100
    model_used:
      description: "AI model that generated the response"
      example: "gpt-4o-mini"
    instance:
      description: "Instance name that processed the request"
      example: "my_assistant"
    question:
      description: "The original question that was asked"
      example: "What is the weather like?"
    timestamp:
      description: "ISO timestamp when the response was generated"
      example: "2025-01-09T16:57:00.000Z"
    success:
      description: "Whether the request was successful"
      example: true
    error:
      description: "Error message if the request failed (only present when success is false)"
      example: "API rate limit exceeded"

clear_history:
  name: Clear History
  description: >-
    Delete all stored questions and responses from the conversation history
  fields:
    instance:
      name: Instance
      description: Name of the HA Text AI instance to clear history for
      required: true
      selector:
        entity:
          integration: ha_text_ai
          domain: sensor

get_history:
  name: Get History
  description: Retrieve conversation history with optional filtering and sorting
  fields:
    instance:
      name: Instance
      description: Name of the HA Text AI instance to get history from
      required: true
      selector:
        entity:
          integration: ha_text_ai
          domain: sensor

    limit:
      name: Limit
      description: Number of conversations to return (1-100)
      required: false
      default: 10
      selector:
        number:
          min: 1
          max: 100
          step: 1
          mode: box

    filter_model:
      name: Filter Model
      description: Filter conversations by specific AI model
      required: false
      selector:
        text:
          multiline: false

    start_date:
      name: Start Date
      description: Filter conversations starting from this date/time
      required: false
      selector:
        text:
          multiline: false

    include_metadata:
      name: Include Metadata
      description: Include additional information like tokens used, response time, etc.
      required: false
      default: false
      selector:
        boolean:

    sort_order:
      name: Sort Order
      description: Sort order for results (newest or oldest first)
      required: false
      default: newest
      selector:
        select:
          options:
            - newest
            - oldest

set_system_prompt:
  name: Set System Prompt
  description: Set default system behavior instructions for all future conversations
  fields:
    instance:
      name: Instance
      description: Name of the HA Text AI instance to set system prompt for
      required: true
      selector:
        entity:
          integration: ha_text_ai
          domain: sensor

    prompt:
      name: System Prompt
      description: Instructions that define how the AI should behave and respond
      required: true
      selector:
        text:
          multiline: true