From d618feffffc29a3edcca00f95b246cc57f30aa69 Mon Sep 17 00:00:00 2001
From: SMKRV <smkrv@github.com>
Date: Tue, 26 Nov 2024 15:01:40 +0300
Subject: [PATCH] docs(readme): Enhance attribute descriptions with detailed
 English comments

- Add comprehensive explanations for HA Text AI sensor attributes
- Improve readability of README.md documentation
- Provide context and usage details for each sensor attribute
- Translate comments to English with technical clarity

Changes include:
* Detailed descriptions for Model and Provider Information
* Expanded System Status attribute explanations
* Clarified Performance Metrics comments
* Added context for Conversation and Token Usage
* Improved Last Interaction Details descriptions
* Enhanced System Health attribute documentation
---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 51 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index a0df18f..fa11657 100644
--- a/README.md
+++ b/README.md
@@ -242,52 +242,82 @@ automation:
 
 #### Model and Provider Information
 ```yaml
-# Model details
-{{ state_attr('sensor.ha_text_ai_gpt', 'Model') }}           # gpt-4o
-{{ state_attr('sensor.ha_text_ai_gpt', 'Api provider') }}    # openai
+# Name of the AI model currently in use (e.g., latest version of GPT)  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Model') }}           # gpt-4o  
+
+# Service provider for the AI model (determines API endpoint and authentication)  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Api provider') }}    # openai  
+
+# Previous or alternative model configuration  
 {{ state_attr('sensor.ha_text_ai_gpt', 'Last model') }}      # gpt-4o
 ```
 
 #### System Status
 ```yaml
-# Operational status
-{{ state_attr('sensor.ha_text_ai_gpt', 'Api status') }}      # ready
-{{ state_attr('sensor.ha_text_ai_gpt', 'Is processing') }}   # false
-{{ state_attr('sensor.ha_text_ai_gpt', 'Is rate limited') }} # false
+# Current operational readiness of the AI service API  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Api status') }}      # ready  
+
+# Indicates if a request is currently being processed  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Is processing') }}   # false  
+
+# Shows if the API has hit its request rate limit  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Is rate limited') }} # false  
+
+# Status of the specific API endpoint being used  
 {{ state_attr('sensor.ha_text_ai_gpt', 'Endpoint status') }} # ready
 ```
 
 #### Performance Metrics
 ```yaml
-# Request and performance statistics
-{{ state_attr('sensor.ha_text_ai_gpt', 'Successful requests') }}   # 0
-{{ state_attr('sensor.ha_text_ai_gpt', 'Failed requests') }}       # 0
-{{ state_attr('sensor.ha_text_ai_gpt', 'Average latency') }}       # 0
+# Total number of successfully completed API requests  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Successful requests') }}   # 0  
+
+# Number of API requests that encountered errors  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Failed requests') }}       # 0  
+
+# Mean time taken to receive a response from the AI service  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Average latency') }}       # 0  
+
+# Maximum time taken for a single request-response cycle  
 {{ state_attr('sensor.ha_text_ai_gpt', 'Max latency') }}           # 0
 ```
 
 #### Conversation and Token Usage
 ```yaml
-# Conversation and token details
-{{ state_attr('sensor.ha_text_ai_gpt', 'History size') }}          # 0
-{{ state_attr('sensor.ha_text_ai_gpt', 'Total tokens') }}          # 0
-{{ state_attr('sensor.ha_text_ai_gpt', 'Prompt tokens') }}         # 0
+# Number of previous interactions stored in conversation context  
+{{ state_attr('sensor.ha_text_ai_gpt', 'History size') }}          # 0  
+
+# Total number of tokens used across all interactions  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Total tokens') }}          # 0  
+
+# Tokens used in the input prompts  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Prompt tokens') }}         # 0  
+
+# Tokens used in the AI's generated responses  
 {{ state_attr('sensor.ha_text_ai_gpt', 'Completion tokens') }}     # 0
 ```
 
 #### Last Interaction Details
 ```yaml
-# Last interaction information
-{{ state_attr('sensor.ha_text_ai_gpt', 'Response') }}        # Last AI response
-{{ state_attr('sensor.ha_text_ai_gpt', 'Question') }}        # Last asked question
+# Most recent complete response generated by the AI service  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Response') }}        # Last AI response  
+
+# The most recently processed user query or prompt  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Question') }}        # Last asked question  
+
+# Precise moment when the last interaction occurred (useful for tracking and logging)  
 {{ state_attr('sensor.ha_text_ai_gpt', 'Last timestamp') }}  # Timestamp
 ```
 
 #### System Health
 ```yaml
-# System health and maintenance
-{{ state_attr('sensor.ha_text_ai_gpt', 'Total errors') }}    # 0
-{{ state_attr('sensor.ha_text_ai_gpt', 'Is maintenance') }}  # false
+# Cumulative count of all errors encountered during AI service interactions  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Total errors') }}    # 0  
+
+# Indicates if the AI service is currently undergoing scheduled or emergency maintenance  
+{{ state_attr('sensor.ha_text_ai_gpt', 'Is maintenance') }}  # false  
+
+# Total continuous operational time of the AI service (in hours or days)  
 {{ state_attr('sensor.ha_text_ai_gpt', 'Uptime') }}          # 547,58
 ```