chore: add code comment, remove unused

core/src/main/java/ai/z/openapi/api/agents/AgentsApi.java

@@ -10,15 +10,49 @@
 import retrofit2.http.POST;
 import retrofit2.http.Streaming;
 
+/**
+ * Agents API for intelligent agent capabilities based on GLM-4 All Tools Provides AI
+ * agents with automatic tool calling, function execution, and complex task automation
+ * Features include web browsing, code interpreter, image generation, and multi-tool
+ * coordination Supports streaming and synchronous agent interactions with real-time task
+ * planning
+ */
 public interface AgentsApi {
 
+	/**
+	 * Create a streaming agent completion with GLM-4 All Tools Returns agent responses in
+	 * real-time through Server-Sent Events (SSE) Automatically selects and calls
+	 * appropriate tools (web search, code execution, image generation)
+	 * @param request Agent completion parameters including tools, functions, and
+	 * execution context
+	 * @return Streaming response body with incremental agent outputs and tool execution
+	 * results
+	 */
 	@Streaming
 	@POST("v1/agents")
 	Call<ResponseBody> agentsCompletionStream(@Body AgentsCompletionRequest request);
 
+	/**
+	 * Create a synchronous agent completion with GLM-4 All Tools Waits for the agent to
+	 * complete complex task execution and returns the final result Supports automatic
+	 * tool selection including CogView3 image generation, Python code interpreter, and
+	 * web browsing
+	 * @param request Agent completion parameters including tools, functions, and
+	 * execution context
+	 * @return Complete agent execution response with results and comprehensive tool
+	 * outputs
+	 */
 	@POST("v1/agents")
 	Single<ModelData> agentsCompletionSync(@Body AgentsCompletionRequest request);
 
+	/**
+	 * Query the result of an asynchronous agent execution Retrieves the agent execution
+	 * result using the task parameters for long-running tasks Useful for complex
+	 * multi-tool operations that require extended processing time
+	 * @param request Parameters for retrieving asynchronous agent execution results
+	 * @return Agent execution result with tool outputs, status information, and task
+	 * completion details
+	 */
 	@POST("v1/agents/async-result")
 	Single<ModelData> queryAgentsAsyncResult(@Body AgentAsyncResultRetrieveParams request);
 

core/src/main/java/ai/z/openapi/api/assistant/AssistantApi.java

@@ -13,18 +13,47 @@
 import retrofit2.http.POST;
 import retrofit2.http.Streaming;
 
+/**
+ * Assistant API for intelligent conversational AI Provides advanced assistant
+ * capabilities with streaming and synchronous responses Supports conversation management
+ * and usage tracking for AI assistants
+ */
 public interface AssistantApi {
 
+	/**
+	 * Generate assistant response with streaming output Creates real-time conversational
+	 * responses with streaming delivery
+	 * @param request Assistant parameters including messages, model settings, and context
+	 * @return Streaming response body with assistant's reply
+	 */
 	@Streaming
 	@POST("assistant")
 	Call<ResponseBody> assistantCompletionStream(@Body AssistantParameters request);
 
+	/**
+	 * Generate assistant response with complete output Creates conversational responses
+	 * and returns the complete assistant reply
+	 * @param request Assistant parameters including conversation context and settings
+	 * @return Complete assistant response with message content and metadata
+	 */
 	@POST("assistant")
 	Single<AssistantCompletion> assistantCompletion(@Body AssistantParameters request);
 
+	/**
+	 * Query assistant support capabilities Retrieves information about available
+	 * assistant features and supported operations
+	 * @param request Query parameters for support information
+	 * @return Assistant support status and available capabilities
+	 */
 	@POST("assistant/list")
 	Single<AssistantSupportStatus> querySupport(@Body QuerySupportParams request);
 
+	/**
+	 * Query conversation usage statistics Retrieves usage metrics and conversation
+	 * history for assistant interactions
+	 * @param request Conversation query parameters including filters and pagination
+	 * @return Conversation usage statistics and history information
+	 */
 	@POST("assistant/conversation/list")
 	Single<ConversationUsageListStatus> queryConversationUsage(@Body ConversationParameters request);
 

core/src/main/java/ai/z/openapi/api/audio/AudioApi.java

@@ -17,32 +17,74 @@
 
 import java.util.Map;
 
+/**
+ * Audio API for advanced speech processing capabilities Powered by GLM-4-Voice for
+ * end-to-end speech understanding and generation Provides text-to-speech, speech-to-text,
+ * voice customization, and real-time conversation Supports emotion control, tone
+ * adjustment, speed variation, and dialect generation Features real-time audio
+ * processing, voice cloning, and multilingual ASR capabilities
+ */
 public interface AudioApi {
 
 	/**
-	 * TTS interface (Text to speech)
-	 * @param request
-	 * @return
+	 * Text-to-Speech (TTS) conversion using GLM-4-Voice Converts text input into
+	 * natural-sounding speech audio with emotion and tone control Supports multiple
+	 * voices, languages, speed adjustment, and various audio formats Features advanced
+	 * voice synthesis with customizable emotional expressions and dialects
+	 * @param request TTS parameters including text, voice selection, emotion, speed,
+	 * tone, and output format
+	 * @return Generated high-quality audio content in specified format with natural
+	 * prosody
 	 */
 	@POST("audio/speech")
 	Single<ResponseBody> audioSpeech(@Body AudioSpeechRequest request);
 
 	/**
-	 * Voice cloning interface
-	 * @param request
-	 * @return
+	 * Voice cloning and customization using advanced neural models Creates custom voice
+	 * models from provided audio samples with high fidelity Enables personalized speech
+	 * synthesis preserving unique voice characteristics and speaking style Supports
+	 * fine-tuning of voice parameters including pitch, timbre, and speaking patterns
+	 * @param request Voice customization parameters including model settings and training
+	 * options
+	 * @param voiceData High-quality audio file containing voice samples for cloning
+	 * (recommended: clear, diverse samples)
+	 * @return Voice model creation result with customization status and model performance
+	 * metrics
 	 */
 	@Multipart
 	@POST("audio/customization")
 	Single<ResponseBody> audioCustomization(@PartMap Map<String, RequestBody> request,
 			@Part MultipartBody.Part voiceData);
 
+	/**
+	 * Streaming speech-to-text transcription using GLM ASR Converts audio files to text
+	 * with real-time streaming results and low latency Returns transcription results
+	 * incrementally as they become available for immediate processing Optimized for
+	 * real-time applications requiring immediate text feedback
+	 * @param request Transcription parameters including language detection, model
+	 * selection, and streaming settings
+	 * @param file Audio file to be transcribed (supports various formats: wav, mp3, m4a,
+	 * etc.)
+	 * @return Streaming transcription results with timestamps and confidence scores
+	 */
 	@Streaming
 	@POST("audio/transcriptions")
 	@Multipart
 	Call<ResponseBody> audioTranscriptionsStream(@PartMap Map<String, RequestBody> request,
 			@Part MultipartBody.Part file);
 
+	/**
+	 * Speech-to-text transcription using GLM ASR models Converts audio files to text with
+	 * high accuracy and multilingual support Features advanced noise reduction, speaker
+	 * recognition, and punctuation restoration Supports multiple languages with automatic
+	 * language detection capabilities
+	 * @param request Transcription parameters including language preference, model
+	 * selection, and output format options
+	 * @param file Audio file to be transcribed (supports wav, mp3, m4a, flac, and other
+	 * common formats)
+	 * @return Complete transcription result with text, timestamps, confidence scores, and
+	 * speaker information
+	 */
 	@POST("audio/transcriptions")
 	@Multipart
 	Single<ModelData> audioTranscriptions(@PartMap Map<String, RequestBody> request, @Part MultipartBody.Part file);

core/src/main/java/ai/z/openapi/api/batches/BatchesApi.java

@@ -10,17 +10,55 @@
 import retrofit2.http.Path;
 import retrofit2.http.Query;
 
+/**
+ * Batch Processing API for large-scale data operations Enables efficient processing of
+ * millions of requests with cost-effective batch execution Provides up to 50% discount
+ * compared to individual API calls with 24-hour completion guarantee Supports up to
+ * 50,000 requests per batch with maximum 200MB input file size Ideal for evaluation,
+ * classification, and embedding tasks that don't require immediate responses
+ */
 public interface BatchesApi {
 
+	/**
+	 * Create a new batch processing job Submits a large number of requests for efficient
+	 * batch processing with JSONL format Each request must include a unique custom_id for
+	 * result mapping Supports /v1/chat/completions and /v1/embeddings endpoints
+	 * @param batchCreateParams Batch configuration including input file, endpoint, and
+	 * processing options
+	 * @return Batch job information with ID, status, and processing details
+	 */
 	@POST("batches")
 	Single<Batch> batchesCreate(@Body BatchCreateParams batchCreateParams);
 
+	/**
+	 * Retrieve details of a specific batch job Gets comprehensive information about batch
+	 * processing status and results Status can be: validating, failed, in_progress,
+	 * finalizing, completed, expired, cancelling, cancelled
+	 * @param batchId Unique identifier of the batch job to retrieve
+	 * @return Batch job details including progress, completion status, output_file_id,
+	 * and error_file_id
+	 */
 	@GET("batches/{batch_id}")
 	Single<Batch> batchesRetrieve(@Path("batch_id") String batchId);
 
+	/**
+	 * List all batch jobs with pagination Retrieves a paginated list of all batch
+	 * processing jobs with filtering options Useful for monitoring multiple batch
+	 * operations and their completion status
+	 * @param after Cursor for pagination to get batches after this point
+	 * @param limit Maximum number of batch jobs to return per page (default: 20)
+	 * @return Paginated list of batch jobs with status, request counts, and metadata
+	 */
 	@GET("batches")
 	Single<BatchPage> batchesList(@Query("after") String after, @Query("limit") Integer limit);
 
+	/**
+	 * Cancel a running batch job Stops the batch processing and marks the job as
+	 * cancelled (may take up to 10 minutes) Only works for batches in 'validating' or
+	 * 'in_progress' status
+	 * @param batchId Unique identifier of the batch job to cancel
+	 * @return Updated batch job status after cancellation with final request counts
+	 */
 	@POST("batches/{batch_id}/cancel")
 	Single<Batch> batchesCancel(@Path("batch_id") String batchId);
 

core/src/main/java/ai/z/openapi/api/chat/ChatApi.java

@@ -11,18 +11,68 @@
 import retrofit2.http.Path;
 import retrofit2.http.Streaming;
 
+/**
+ * Chat Completions API for advanced GLM-4 series models Provides synchronous,
+ * asynchronous, and streaming chat completion capabilities Supports complex reasoning,
+ * long context processing (up to 128K tokens), and ultra-fast inference Features
+ * GLM-4-Plus, GLM-4-Air, GLM-4-Flash, and GLM-4-AllTools with specialized capabilities
+ * Optimized for Chinese and multilingual conversations with superior performance
+ */
 public interface ChatApi {
 
+	/**
+	 * Create a streaming chat completion with real-time response Returns response content
+	 * incrementally through Server-Sent Events (SSE) for immediate user feedback
+	 * Optimized for interactive applications requiring low latency and progressive
+	 * content delivery Supports all GLM-4 models with configurable streaming parameters
+	 * and token-by-token generation
+	 * @param request Chat completion parameters including model selection (glm-4-plus,
+	 * glm-4-air, glm-4-flash), messages, temperature, top_p, max_tokens, and streaming
+	 * settings
+	 * @return Streaming response body with incremental content, usage statistics, and
+	 * completion indicators
+	 */
 	@Streaming
 	@POST("chat/completions")
 	Call<ResponseBody> createChatCompletionStream(@Body ChatCompletionCreateParams request);
 
+	/**
+	 * Create an asynchronous chat completion for long-running tasks Submits the request
+	 * and returns immediately with a task ID for later result retrieval Ideal for complex
+	 * reasoning tasks, long document processing, or batch operations Supports advanced
+	 * GLM-4 models with extended context and computational requirements
+	 * @param request Chat completion parameters including model selection, messages,
+	 * advanced reasoning settings, tools configuration, and processing options
+	 * @return Task information with unique ID, estimated completion time, and processing
+	 * status for asynchronous tracking
+	 */
 	@POST("async/chat/completions")
 	Single<ModelData> createChatCompletionAsync(@Body ChatCompletionCreateParams request);
 
+	/**
+	 * Create a synchronous chat completion with immediate response Waits for the GLM-4
+	 * model to complete execution and returns the final result Supports complex
+	 * reasoning, tool calling, function execution, and multi-modal understanding Features
+	 * advanced capabilities like web search integration, code interpretation, and image
+	 * analysis
+	 * @param request Chat completion parameters including model selection, conversation
+	 * messages, generation settings (temperature, top_p, max_tokens), tools
+	 * configuration, and response format
+	 * @return Complete chat completion response with generated content, usage statistics,
+	 * tool call results, and reasoning traces
+	 */
 	@POST("chat/completions")
 	Single<ModelData> createChatCompletion(@Body ChatCompletionCreateParams request);
 
+	/**
+	 * Query the result of an asynchronous chat completion task Retrieves the completion
+	 * result or current status using the task ID from async request Provides detailed
+	 * progress information for long-running tasks and complex reasoning operations
+	 * Supports polling-based result retrieval with comprehensive status reporting
+	 * @param id Unique task ID returned from asynchronous chat completion request
+	 * @return Chat completion result with generated content, processing status,
+	 * completion percentage, and any intermediate results or error information
+	 */
 	@GET("async-result/{id}")
 	Single<ModelData> queryAsyncResult(@Path("id") String id);
 

core/src/main/java/ai/z/openapi/api/embedding/EmbeddingApi.java

@@ -6,8 +6,25 @@
 import retrofit2.http.Body;
 import retrofit2.http.POST;
 
+/**
+ * Embeddings API for text vectorization using GLM models Converts text into
+ * high-dimensional vector representations for semantic similarity and search Supports
+ * batch processing of multiple text inputs with configurable dimensions Ideal for RAG
+ * applications, semantic search, text classification, and similarity matching Features
+ * optimized performance for Chinese and multilingual text processing
+ */
 public interface EmbeddingApi {
 
+	/**
+	 * Create embeddings for input text using GLM embedding models Converts text strings
+	 * into numerical vector representations that capture semantic meaning Supports
+	 * customizable vector dimensions for different use cases and performance requirements
+	 * Optimized for both single text and batch processing scenarios
+	 * @param request Embedding parameters including input text, model selection,
+	 * dimensions, and encoding format
+	 * @return High-quality embedding vectors with usage statistics and token consumption
+	 * details
+	 */
 	@POST("embeddings")
 	Single<EmbeddingResult> createEmbeddings(@Body EmbeddingCreateParams request);
 

core/src/main/java/ai/z/openapi/api/file/FileApi.java

@@ -15,21 +15,58 @@
 import retrofit2.http.Query;
 import retrofit2.http.Streaming;
 
+/**
+ * File Management API for document and data handling Provides file upload, retrieval,
+ * deletion, and content access capabilities Supports various file formats for
+ * fine-tuning, knowledge base, and other AI tasks
+ */
 public interface FileApi {
 
+	/**
+	 * Upload a file to the platform Stores files for use in fine-tuning, knowledge base,
+	 * or other AI operations
+	 * @param multipartBody File data with metadata including purpose and format
+	 * @return File information including ID, name, size, and upload status
+	 */
 	@POST("files")
 	Single<File> uploadFile(@Body MultipartBody multipartBody);
 
+	/**
+	 * Retrieve file metadata and information Gets detailed information about a previously
+	 * uploaded file
+	 * @param fileId Unique identifier of the file to retrieve
+	 * @return File metadata including name, size, purpose, and creation time
+	 */
 	@GET("files/{file_id}")
 	Single<File> retrieveFile(@Path("file_id") String fileId);
 
+	/**
+	 * Delete a file from the platform Permanently removes the file and all associated
+	 * data
+	 * @param fileId Unique identifier of the file to delete
+	 * @return Confirmation of file deletion with status information
+	 */
 	@DELETE("files/{file_id}")
 	Single<FileDeleted> deletedFile(@Path("file_id") String fileId);
 
+	/**
+	 * Query and list files with filtering options Retrieves a paginated list of files
+	 * with optional filtering by purpose and ordering
+	 * @param after Cursor for pagination to get files after this point
+	 * @param purpose Filter files by their intended purpose (e.g., fine-tune, assistants)
+	 * @param order Sort order for the file list (e.g., created_at)
+	 * @param limit Maximum number of files to return per page
+	 * @return Paginated list of files with metadata
+	 */
 	@GET("files")
 	Single<QueryFileResult> queryFileList(@Query("after") String after, @Query("purpose") String purpose,
 			@Query("order") String order, @Query("limit") Integer limit);
 
+	/**
+	 * Download file content Streams the actual file content for download or processing
+	 * @param fileId Unique identifier of the file to download
+	 * @return Streaming file content in original format
+	 */
 	@Streaming
 	@GET("files/{file_id}/content")
 	Call<ResponseBody> fileContent(@Path("file_id") String fileId);