openapi: 3.0.0
info:
  title: Ananya - Indic Language Processing API
  description: |
    A comprehensive REST API for processing Indic languages (currently optimized for Telugu), providing advanced linguistic analysis and manipulation capabilities.
    
    ## Features
    - **Text Operations**: Length calculation, reversal, replacement, randomization
    - **Character Analysis**: Unicode processing, logical characters, code points
    - **String Validation**: Character validation, content checking
    - **String Comparison**: Equality, ordering, pattern matching
    - **Word Analysis**: Anagram detection, palindromes, word strength
    - **Advanced Operations**: Language detection, intersection analysis
    
  version: 2.0.0

servers:
  - url: ../api.php
    description: Current Environment Server (auto-detect host and base path)
  - url: http://localhost/ananya/api.php
    description: Local Development Server
  - url: https://jasthi.com/ananya/api.php
    description: Production Server
  - url: https://ananya.telugupuzzles.com/api.php
    description: Production Server (root deployment)

tags:
  - name: Character Analysis
    description: Character-level analysis and Unicode processing (requires language)
  - name: Text Operations
    description: Basic text manipulation and processing
  - name: Word Analysis
    description: Word-level analysis and linguistic metrics
  - name: String Comparison
    description: String comparison and matching operations (requires language)
  - name: Character Validation
    description: Character validation and content checking
  - name: Utility
    description: General-purpose utility endpoints for language detection and length calculations with Required character filtering.
  - name: Authentication
    description: User authentication and management

components:
  schemas:
    ApiResponse:
      type: object
      properties:
        response_code:
          type: integer
          description: HTTP response code
        message:
          type: string
          description: Descriptive message about the operation
        string:
          type: string
          description: The input string that was processed
        language:
          type: string
          nullable: true
          description: The language used for processing
        data:
          description: The result data of the operation
        success:
          type: boolean
          description: Whether the operation was successful
        result:
          description: The result of the operation (same as data)
        error:
          type: string
          nullable: true
          description: Error message if operation failed

    ErrorResponse:
      type: object
      properties:
        response_code:
          type: integer
          example: 400
        message:
          type: string
          example: "Missing required parameters: string and language"
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "Missing required parameters: string and language"

  parameters:
    stringRequired:
      name: string
      in: query
      required: true
      description: Input string
      schema:
        type: string
        example: "అనన్య"
    languageRequired:
      name: language
      in: query
      required: true
      description: "Language of the input string (e.g., telugu, hindi, gujarati, malayalam)"
      schema:
        type: string
        enum: [telugu, english]
        default: telugu
        example: "telugu"
    languageOptional:
      name: language
      in: query
      required: false
      description: Language of the input text
      schema:
        type: string
        enum: [telugu, english]
        default: telugu
    utilityLanguageOverride:
      name: language
      in: query
      required: false
      description: Required language override. If omitted, language is auto-detected (english/telugu only).
      schema:
        type: string
        enum: [english, telugu]
    input2Required:
      name: input2
      in: query
      required: true
      description: Secondary input string for comparison or manipulation
      schema:
        type: string
        example: "అన్న"
    input3Required:
      name: input3
      in: query
      required: true
      description: Tertiary input string for comparison or manipulation
      schema:
        type: string
        example: "ఆన్న"
    secondStringRequired:
      name: second_string
      in: query
      required: true
      description: "Second input string for comparison or manipulation"
      schema:
        type: string
        enum: [english, telugu]
        example: "english"

    countRequired:
      name: count
      in: query
      required: true
      description: Number of characters to generate (must be > 0)
      schema:
        type: integer
        minimum: 1
        maximum: 10
        example: 5
    typeRequired:
      name: type
      in: query
      required: true
      description: Type of characters (consonant or vowel)
      schema:
        type: string
        enum: [consonant, vowel]
        example: "consonant"
    containsRequired:
      name: contains
      in: query
      required: true
      description: Comma-separated logical characters to check
      schema:
        type: string
        example: "అ,న్య"
    usernameRequired:
      name: username
      in: query
      required: true
      description: Username for authentication
      schema:
        type: string
    passwordRequired:
      name: password
      in: query
      required: true
      description: Password for authentication
      schema:
        type: string
    emailRequired:
      name: email
      in: query
      required: true
      description: Email address for authentication
      schema:
        type: string
        format: email

paths:

  # ============================================================
  # WORD ANALYSIS (requires string; language defaults to telugu)
  # ============================================================

  /analysis/can-make-all-words:
    get:
      tags:
        - Word Analysis
      summary: Check if all words can be formed
      description: Check if all words in the second parameter can be formed from the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Comma-separated words to check
          schema:
            type: string
            example: "అన,న్య"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "All words formation check completed"
                string: "hello"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/can-make-word:
    get:
      tags:
        - Word Analysis
      summary: Check if word can be formed
      description: Check if the second word can be formed using characters from the first word
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Word to check if it can be formed from the input string
          schema:
            type: string
            example: "అన"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Word formation check completed"
                string: "hello"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/detect-language:
    get:
      tags:
        - Word Analysis
      summary: Detect language (legacy alias)
      deprecated: true
      description: Legacy alias for language detection. Prefer `/utility/language` for new integrations.
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Language detected"
                string: "hello"
                language: null
                data: "English"
                success: true
                result: "English"
                error: null

  /analysis/get-match-id-string:
    get:
      tags:
        - Word Analysis
      summary: Get match ID string
      description: Generate a match ID string between two words for comparison analysis
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string for match ID generation
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Match ID string generated"
                string: "abc"
                language: "english"
                data: "115"
                success: true
                result: "115"
                error: null

  /analysis/head-tail-words:
    get:
      tags:
        - Word Analysis
      summary: Check if head-tail words
      description: Check if the last logical character of the first word matches the first logical character of the second word
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second word for head-tail check
          schema:
            type: string
            example: "న్యాయం"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Head and tail words check completed"
                string: "hello"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/intersecting-rank:
    get:
      tags:
        - Word Analysis
      summary: Get intersecting rank
      description: Calculate the intersecting rank between two strings (number of shared characters)
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string for intersection ranking
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Intersecting rank calculated"
                string: "hello"
                language: "english"
                data: 3
                success: true
                result: 3
                error: null

  /analysis/is-anagram:
    get:
      tags:
        - Word Analysis
      summary: Check if anagram
      description: Determine if the two input strings are anagrams of each other
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string to compare for anagram check
          schema:
            type: string
            example: "న్యఅన"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Anagram check completed"
                string: "listen"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/is-consonant:
    get:
      tags:
        - Word Analysis
      summary: Check if character is consonant
      description: Determine if the given character is a consonant (uses the first logical character of the input)
      parameters:
        - name: string
          in: query
          required: true
          description: Character to check (first logical character is used)
          schema:
            type: string
            example: "క"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Consonant check completed"
                string: "b"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/is-palindrome:
    get:
      tags:
        - Word Analysis
      summary: Check if palindrome
      description: Determine if the input string is a palindrome using logical character comparison
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Palindrome check completed"
                string: "racecar"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/ladder-words:
    get:
      tags:
        - Word Analysis
      summary: Check if ladder words
      description: Check if two words are ladder words (differ by one logical character)
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second word for ladder word check
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Ladder words check completed"
                string: "cat"
                language: "english"
                data: true
                success: true
                result: true
                error: null

  /analysis/word-level:
    get:
      tags:
        - Word Analysis
      summary: Calculate word level
      description: Calculate the linguistic level metric of the input word
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Word level calculated"
                string: "hello"
                language: "english"
                data: 2
                success: true
                result: 2
                error: null

  /analysis/word-strength:
    get:
      tags:
        - Word Analysis
      summary: Calculate word strength
      description: Calculate the linguistic strength metric of the input word
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Word strength calculated"
                string: "America"
                language: "english"
                data: 42
                success: true
                result: 42
                error: null

  /analysis/word-weight:
    get:
      tags:
        - Word Analysis
      summary: Calculate word weight
      description: Calculate the linguistic weight metric of the input word
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Word weight calculated"
                string: "computer"
                language: "english"
                data: 98
                success: true
                result: 98
                error: null

  /analysis/parse-to-logical-characters:
    get:
      tags:
        - Word Analysis
      summary: Parse to logical characters (alternative)
      description: Alternative method to parse the input string into logical character components
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Text parsed to logical characters (alternative)"
                string: "hello"
                language: "english"
                data:
                  - "h"
                  - "e"
                  - "l"
                  - "l"
                  - "o"
                success: true
                result:
                  - "h"
                  - "e"
                  - "l"
                  - "l"
                  - "o"
                error: null

  /analysis/role:
    get:
      tags:
        - Word Analysis
      summary: Determine character role
      description: Determines the linguistic role of a character (consonant, vowel, etc.).
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Character role analyzed"
                string: "a"
                language: "english"
                data: "vowel"
                success: true
                result: "vowel"
                error: null

  /analysis/split-into-chunks:
    get:
      tags:
        - Word Analysis
      summary: Split into chunks
      description: Split the input string into 15 chunks based on logical characters
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Text split into chunks"
                string: "hello"
                language: "english"
                data:
                  - "h"
                  - "e"
                  - "l"
                  - "l"
                  - "o"
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                success: true
                result:
                  - "h"
                  - "e"
                  - "l"
                  - "l"
                  - "o"
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                  - ""
                error: null

  /analysis/unique-intersecting-chars:
    get:
      tags:
        - Word Analysis
      summary: Get unique intersecting logical characters
      description: Get the unique intersecting logical characters between two strings
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string for unique intersection
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Unique intersecting logical characters calculated"
                string: "hello"
                language: "english"
                data:
                  - "l"
                  - "o"
                success: true
                result:
                  - "l"
                  - "o"
                error: null

  /analysis/unique-intersecting-rank:
    get:
      tags:
        - Word Analysis
      summary: Get unique intersecting rank
      description: Calculate the unique intersecting rank between two strings
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string for unique intersection ranking
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Unique intersecting rank calculated"
                string: "hello"
                language: "english"
                data: 2
                success: true
                result: 2
                error: null

  /validation/is-vowel:
    get:
      tags:
        - Character Validation
      summary: Check if character is vowel
      description: Determine if the given character is a vowel (uses the first logical character of the input)
      parameters:
        - name: string
          in: query
          required: true
          description: Character to check (first logical character is used)
          schema:
            type: string
            example: "అ"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  # ==============
  # AUTHENTICATION
  # ==============

  /auth/login:
    get:
      tags:
        - Authentication
      summary: User login
      description: |
        Authenticate a user with email and password.

        **Test Mode:** Use email ending in `@example.com` or `@test.com` for testing without a database.
        - `test@example.com` with `password123` -> successful login
        - Any other `@example.com`/`@test.com` email -> authentication failed
      parameters:
        - $ref: '#/components/parameters/emailRequired'
        - $ref: '#/components/parameters/passwordRequired'
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Login successful"
                data:
                  authenticated: true
                  user_id: 999
                success: true
                error: null
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response_code: 401
                message: "Authentication failed"
                data: null
                success: false
                error: "Invalid email or password"
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/user-exists:
    get:
      tags:
        - Authentication
      summary: Check if user exists
      description: |
        Check if an email address already exists in the system.

        **Test Mode:** Use email ending in `@example.com` or `@test.com` for testing without a database.
        - `test@example.com` -> returns `true`
        - Other `@example.com`/`@test.com` emails -> returns `false`
      parameters:
        - $ref: '#/components/parameters/emailRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "User exists"
                data: true
                success: true
                error: null
        '400':
          description: Missing required parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


  # =================================================
  # CHARACTER ANALYSIS (requires string AND language)
  # =================================================

  /characters/add-at:
    get:
      tags:
        - Character Analysis
      summary: Add character at position
      description: Insert a character at a specific position in the string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Zero-based position index to insert at
          schema:
            type: integer
            example: 1
        - name: input3
          in: query
          required: true
          description: Character to insert
          schema:
            type: string
            example: "క"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Character added at position"
                string: "hello"
                language: "english"
                data: "heXllo"
                success: true
                result: "heXllo"
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/add-end:
    get:
      tags:
        - Character Analysis
      summary: Add character at end
      description: Append a character to the end of the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Character to add at the end
          schema:
            type: string
            example: "క"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Character added at end"
                string: "hello"
                language: "english"
                data: "hello!"
                success: true
                result: "hello!"
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/base:
    get:
      tags:
        - Character Analysis
      summary: Get base characters
      description: Extract base characters from the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Base characters processed"
                string: "hello"
                language: "english"
                data: ["h", "e", "l", "l", "o"]
                success: true
                result: ["h", "e", "l", "l", "o"]
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/base-consonants:
    get:
      tags:
        - Character Analysis
      summary: Get base consonants
      description: Calculate base consonants for the input strings
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Secondary string for consonant comparison
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Base consonants calculated"
                string: "hello"
                language: "english"
                data: ["l"]
                success: true
                result: ["l"]
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/codepoints:
    get:
      tags:
        - Character Analysis
      summary: Get Unicode code points
      description: Get Unicode code points for each character in the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Code points processed"
                string: "hello"
                language: "english"
                data: [[104], [101], [108], [108], [111]]
                success: true
                result: [[104], [101], [108], [108], [111]]
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/codepoint-length:
    get:
      tags:
        - Character Analysis
      summary: Get code point length
      description: Calculate the number of Unicode code points in the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Code point length calculated"
                string: "hello"
                language: "english"
                data: 5
                success: true
                result: 5
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/filler:
    get:
      tags:
        - Character Analysis
      summary: Get filler characters
      description: Generate filler characters for the specified language (does not require a string input)
      parameters:
        - name: count
          in: query
          required: false
          description: Number of filler characters to generate (default 3)
          schema:
            type: integer
            default: 3
            example: 3
        - name: type
          in: query
          required: false
          description: Type of filler characters to generate
          schema:
            type: string
            default: "consonant"
            enum:
              - consonant
              - vowel
            example: "consonant"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Filler characters generated"
                string: "5 consonant"
                language: "english"
                data: ["b", "c", "d", "f", "g"]
                success: true
                result: ["b", "c", "d", "f", "g"]
                error: null
        '400':
          description: Missing required parameter (language)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/logical:
    get:
      tags:
        - Character Analysis
      summary: Get logical characters
      description: Split the input string into logical character components
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Logical characters processed"
                string: "hello"
                language: "english"
                data: ["h", "e", "l", "l", "o"]
                success: true
                result: ["h", "e", "l", "l", "o"]
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/logical-at:
    get:
      tags:
        - Character Analysis
      summary: Get logical character at position
      description: Retrieve the logical character at a specific position in the string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: false
          description: Zero-based position index (default 0)
          schema:
            type: integer
            default: 0
            example: 0
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Logical character at position retrieved"
                string: "hello"
                language: "english"
                data: "e"
                success: true
                result: "e"
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /characters/random-logical:
    get:
      tags:
        - Character Analysis
      summary: Get random logical characters
      description: Get a random selection of logical characters from the corpus for the selected language
      parameters:
        - name: count
          in: query
          required: false
          description: Number of random characters to return (default 5)
          schema:
            type: integer
            default: 5
            example: 5
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Random logical characters generated"
                string: null
                language: "english"
                data: ["h", "e", "l"]
                success: true
                result: ["h", "e", "l"]
                error: null
        '400':
          description: Missing required parameter (language)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ================================================
  # STRING COMPARISON (requires string AND language)
  # ================================================

  /comparison/compare-ignore-case:
    get:
      tags:
        - String Comparison
      summary: Compare strings (case-insensitive)
      description: Compare two strings in dictionary order while ignoring uppercase/lowercase differences. Returns 0 if equal, a negative value if the first string comes before the second, or a positive value if it comes after.
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string to compare
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /comparison/compare-to:
    get:
      tags:
        - String Comparison
      summary: Compare strings
      description: Compare two strings in dictionary order and return an ordering result. Returns 0 if equal, a negative value if the first string comes before the second, or a positive value if it comes after.
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string to compare
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /comparison/equals:
    get:
      tags:
        - String Comparison
      summary: Check string equality
      description: Check if two strings are equal
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string to compare for equality
          schema:
            type: string
            example: "అనన్య"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /comparison/is-intersecting:
    get:
      tags:
        - String Comparison
      summary: Check if strings intersect
      description: Check if the two input strings share any common logical characters
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Second string to check for intersection
          schema:
            type: string
            example: "అన్న"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /comparison/reverse-equals:
    get:
      tags:
        - String Comparison
      summary: Check reverse equality
      description: Check if reversing the first string equals the second string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: String to compare against the reversed input
          schema:
            type: string
            example: "న్యనఅ"
        - $ref: '#/components/parameters/languageRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ==============================================================
  # TEXT OPERATIONS (requires string; language defaults to telugu)
  # ==============================================================

  /text/length:
    get:
      tags:
        - Text Operations
      summary: Get text length
      description: Calculate the length of the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Length calculated"
                string: "hello"
                language: "english"
                data: 5
                success: true
                result: 5
                error: null
  /text/randomize:
    get:
      tags:
        - Text Operations
      summary: Randomize text
      description: Randomly shuffle the logical characters in the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Text randomized"
                string: "hello"
                language: "english"
                data: ["l", "o", "e", "l", "h"]
                success: true
                result: ["l", "o", "e", "l", "h"]
                error: null
  /text/replace:
    get:
      tags:
        - Text Operations
      summary: Replace text
      description: Replace occurrences of a search string with a replacement string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Text to find
          schema:
            type: string
            example: "అ"
        - name: input3
          in: query
          required: false
          description: Replacement text
          schema:
            type: string
            example: "ఆ"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Text replaced"
                string: "hello"
                language: "english"
                data: "hio"
                success: true
                result: "hio"
                error: null
        '400':
          description: Missing required parameter (search)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /text/reverse:
    get:
      tags:
        - Text Operations
      summary: Reverse text
      description: Reverse the input string while preserving logical character boundaries
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Text reversed"
                string: "hello"
                language: "english"
                data: "olleh"
                success: true
                result: "olleh"
                error: null
  /text/split:
    get:
      tags:
        - Text Operations
      summary: Split text by delimiter
      description: Split the input string by a delimiter and return the parts separated by " | "
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: delimiter
          in: query
          required: false
          description: "Delimiter to split on (default: -). Preferred parameter for new integrations."
          schema:
            type: string
            default: "-"
            example: "-"
        - name: input2
          in: query
          required: false
          description: "Legacy alias for delimiter. If both delimiter and input2 are provided, delimiter takes precedence."
          schema:
            type: string
            example: "-"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Text split"
                string: "hello-world"
                language: "english"
                data: "hello | world"
                success: true
                result: "hello | world"
                error: null

  # ===================================================================
  # CHARACTER VALIDATION (requires string; language optional, defaults to telugu)
  # ===================================================================

  /validation/contains-all-logical-chars:
    get:
      tags:
        - Character Validation
      summary: Check if contains all logical characters
      description: Check if the input string contains all of the specified logical characters
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Comma-separated logical characters that must all be present
          schema:
            type: string
            example: "అ,న"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /validation/contains-char:
    get:
      tags:
        - Character Validation
      summary: Check if contains character
      description: Check if the input string contains a specific character
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Character to search for
          schema:
            type: string
            example: "న"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /validation/contains-logical-chars:
    get:
      tags:
        - Character Validation
      summary: Check if contains logical characters
      description: Check if the input string contains any of the specified logical characters
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Comma-separated logical characters; returns true if any listed character is present
          schema:
            type: string
            example: "అ,న"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /validation/contains-logical-sequence:
    get:
      tags:
        - Character Validation
      summary: Check if contains logical character sequence
      description: Check if the input string contains a specific sequence of logical characters
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Exact sequence to check for (not a comma-separated list)
          schema:
            type: string
            example: "అన"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /validation/contains-space:
    get:
      tags:
        - Character Validation
      summary: Check if contains spaces
      description: Check if the input string contains any spaces
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /validation/contains-string:
    get:
      tags:
        - Character Validation
      summary: Check if contains substring
      description: Check if the input string contains a specific substring
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Substring to search for
          schema:
            type: string
            example: "అన"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /validation/starts-with:
    get:
      tags:
        - Character Validation
      summary: Check if starts with
      description: Check if the string starts with the specified prefix
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Prefix to check
          schema:
            type: string
            example: "అన"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /validation/ends-with:
    get:
      tags:
        - Character Validation
      summary: Check if ends with
      description: Check if the string ends with the specified suffix
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Suffix to check
          schema:
            type: string
            example: "న్య"
        - $ref: '#/components/parameters/languageOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ===================================================================
  # UTILITY (requires string; language auto-detected unless overridden)
  # ===================================================================

  /utility/index-of:
    get:
      tags:
        - Utility
      summary: Find index of substring
      description: Find the index position of a substring within the input string
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - name: input2
          in: query
          required: true
          description: Substring to search for
          schema:
            type: string
            example: "న్య"
        - $ref: '#/components/parameters/utilityLanguageOverride'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Index found"
                string: "అమెరికాఆస్ట్రేలియా"
                language: "telugu"
                data: 6
                success: true
                result: 6
                error: null
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /utility/language:
    get:
      tags:
        - Utility
      summary: Determine language
      description: |
        Detect the script/language profile of the input text using Unicode character ranges.

        **Return values (`data`):**
        - `English`
        - `Telugu`
        - `Mixed languages`
        - `Unknown`

      parameters:
        - $ref: '#/components/parameters/stringRequired'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Language detected"
                string: "అనన్య"
                language: null
                data: "Telugu"
                success: true
                result: "Telugu"
                error: null
  /utility/length-alternative:
    get:
      tags:
        - Utility
      summary: Alternative length calculation (excluding special characters)
      
      description: |
        Calculates the length of text excluding spaces and special characters (punctuation and symbols).
        If `language` is omitted, the API auto-detects language (`english` or `telugu`).
        
        **Filtered Characters:**
        - Spaces
        - Special symbols: `! @ # $ % ^ & * ( ) _ - + = { } [ ] : ; " ' < , > . ? / | \`
                      
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/utilityLanguageOverride'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Alternative length calculated"
                string: "Hello, World!"
                language: "telugu"
                data: 10
                success: true
                result: 10
                error: null
        '400':
          description: Unsupported override or unable to auto-detect english/telugu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /utility/length-no-spaces-commas:
    get:
      tags:
        - Utility
      summary: Length calculation without spaces or commas
      description: Calculate the length of a string excluding spaces and commas
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/utilityLanguageOverride'
        
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Length without spaces and commas calculated"
                string: "hello, world"
                language: "english"
                data: 10
                success: true
                result: 10
                error: null
        '400':
          description: Unsupported override or unable to auto-detect english/telugu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /utility/length-no-spaces:
    get:
      tags:
        - Utility
      summary: Length calculation without spaces
      description: Calculate the length of a string excluding spaces
      parameters:
        - $ref: '#/components/parameters/stringRequired'
        - $ref: '#/components/parameters/utilityLanguageOverride'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                response_code: 200
                message: "Length without spaces calculated"
                string: "hello world"
                language: "english"
                data: 10
                success: true
                result: 10
                error: null
        '400':
          description: Unsupported override or unable to auto-detect english/telugu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
