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:
    type: object
    properties:
      response_text:
        type: string
        description: The AI response text
      tokens_used:
        type: integer
        description: Total number of tokens used
      prompt_tokens:
        type: integer
        description: Number of tokens in the prompt
      completion_tokens:
        type: integer
        description: Number of tokens in the completion
      model_used:
        type: string
        description: The AI model that was used for the response
      instance:
        type: string
        description: The instance name that was used
      question:
        type: string
        description: The original question that was asked
      timestamp:
        type: string
        description: ISO timestamp when the response was generated
      success:
        type: boolean
        description: Whether the request was successful
      error:
        type: string
        description: Error message if the request failed

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