Add API Documentation tab with examples and usage guide

app.py

@@ -421,7 +421,7 @@ with gr.Blocks(css=custom_css, title="Pro-TeVA Tone Recognition") as demo:
                 show_label=True
             )
 
-    # Hidden JSON API interface
+    # JSON API interface
     json_api = gr.Interface(
         fn=predict_tone_json,
         inputs=gr.Audio(type="filepath", label="Audio File"),
@@ -431,10 +431,253 @@ with gr.Blocks(css=custom_css, title="Pro-TeVA Tone Recognition") as demo:
         description="Returns pure JSON response for programmatic access"
     )
 
-# Combine both interfaces
+# API Documentation tab
+with gr.Blocks() as api_docs:
+    gr.Markdown(
+        """
+        # API Documentation
+
+        Pro-TeVA provides two API endpoints for programmatic access to tone recognition.
+
+        ---
+
+        ## Available Endpoints
+
+        | Endpoint | Description | Output Type |
+        |----------|-------------|-------------|
+        | `/predict` | UI endpoint with visualizations | Text + Plots |
+        | `/predict_json` | Pure JSON for APIs | Structured JSON |
+
+        ---
+
+        ## JSON API Endpoint (Recommended)
+
+        **Endpoint:** `/predict_json`
+
+        This is the recommended endpoint for programmatic access as it returns pure JSON data.
+
+        ### Input
+
+        - **audio_file**: Audio file (WAV, MP3, FLAC)
+        - Recommended: 16kHz sample rate, mono
+        - Max duration: ~10 seconds
+
+        ### Output Schema
+
+        ```json
+        {
+          "success": true,
+          "tone_sequence": [
+            {
+              "index": 1,
+              "label": "H",
+              "name": "High Tone",
+              "symbol": "◌́"
+            }
+          ],
+          "tone_string": "H → B → M",
+          "statistics": {
+            "total_tones": 3,
+            "word_boundaries": 1,
+            "sequence_length": 4,
+            "high_tones": 1,
+            "low_tones": 1,
+            "mid_tones": 1
+          },
+          "f0_data": {
+            "extracted": [120.5, 125.3, ...],
+            "predicted": [118.2, 123.8, ...],
+            "length": 100
+          },
+          "settings": {
+            "space_detection_enabled": true,
+            "space_detection_method": "combined"
+          }
+        }
+        ```
+
+        ---
+
+        ## Python Examples
+
+        ### Installation
+
+        ```bash
+        pip install gradio_client
+        ```
+
+        ### Basic Usage
+
+        ```python
+        from gradio_client import Client
+
+        # Connect to Pro-TeVA
+        client = Client("https://huggingface.co/spaces/Obiang/Pro-TeVA")
+
+        # Get JSON response
+        result = client.predict(
+            audio_file="path/to/audio.wav",
+            api_name="/predict_json"
+        )
+
+        # Parse results
+        print(f"Success: {result['success']}")
+        print(f"Tones: {result['tone_string']}")
+        print(f"Statistics: {result['statistics']}")
+        ```
+
+        ### Batch Processing
+
+        ```python
+        from gradio_client import Client
+
+        client = Client("https://huggingface.co/spaces/Obiang/Pro-TeVA")
+
+        audio_files = ["audio1.wav", "audio2.wav", "audio3.wav"]
+
+        for audio_path in audio_files:
+            result = client.predict(
+                audio_file=audio_path,
+                api_name="/predict_json"
+            )
+
+            if result['success']:
+                print(f"{audio_path}: {result['tone_string']}")
+            else:
+                print(f"{audio_path}: Error - {result['error']}")
+        ```
+
+        ---
+
+        ## cURL Examples
+
+        ### Step 1: Submit Request
+
+        ```bash
+        curl -X POST "https://Obiang-Pro-TeVA.hf.space/call/predict_json" \\
+          -H "Content-Type: application/json" \\
+          -d '{
+            "data": ["https://example.com/audio.wav"]
+          }'
+        ```
+
+        **Response:**
+        ```json
+        {"event_id": "abc123def456"}
+        ```
+
+        ### Step 2: Get Results
+
+        ```bash
+        curl -N "https://Obiang-Pro-TeVA.hf.space/call/predict_json/abc123def456"
+        ```
+
+        **Response (Server-Sent Events):**
+        ```
+        event: complete
+        data: {"success": true, "tone_sequence": [...], ...}
+        ```
+
+        ### One-liner with jq
+
+        ```bash
+        # Submit and get event_id
+        EVENT_ID=$(curl -s -X POST "https://Obiang-Pro-TeVA.hf.space/call/predict_json" \\
+          -H "Content-Type: application/json" \\
+          -d '{"data": ["audio.wav"]}' | jq -r '.event_id')
+
+        # Get results
+        curl -N "https://Obiang-Pro-TeVA.hf.space/call/predict_json/$EVENT_ID"
+        ```
+
+        ---
+
+        ## JavaScript Example
+
+        ```javascript
+        import { client } from "@gradio/client";
+
+        async function predictTones(audioBlob) {
+          const app = await client("https://huggingface.co/spaces/Obiang/Pro-TeVA");
+
+          const result = await app.predict("/predict_json", {
+            audio_file: audioBlob
+          });
+
+          console.log("Tones:", result.data.tone_string);
+          console.log("Statistics:", result.data.statistics);
+
+          return result.data;
+        }
+        ```
+
+        ---
+
+        ## Error Handling
+
+        ### Error Response Schema
+
+        ```json
+        {
+          "success": false,
+          "error": "Error message here",
+          "traceback": "Full error traceback..."
+        }
+        ```
+
+        ### Python Error Handling
+
+        ```python
+        from gradio_client import Client
+
+        try:
+            client = Client("https://huggingface.co/spaces/Obiang/Pro-TeVA")
+            result = client.predict(
+                audio_file="audio.wav",
+                api_name="/predict_json"
+            )
+
+            if result['success']:
+                print(f"Tones: {result['tone_string']}")
+            else:
+                print(f"Error: {result['error']}")
+
+        except Exception as e:
+            print(f"Connection error: {str(e)}")
+        ```
+
+        ---
+
+        ## Rate Limits
+
+        - Hugging Face Spaces: Standard rate limits apply
+        - Free tier: Suitable for development and testing
+        - For high-volume usage: Consider deploying your own instance
+
+        ---
+
+        ## Tone Labels Reference
+
+        | Index | Label | Name | Symbol |
+        |-------|-------|------|--------|
+        | 0 | BLANK | CTC Blank | - |
+        | 1 | H | High Tone | ◌́ |
+        | 2 | B | Low Tone | ◌̀ |
+        | 3 | M | Mid Tone | ◌ |
+        | 4 | SPACE | Word Boundary | \\| |
+
+        ---
+
+        ## Support
+
+        For questions or issues, please open an issue on the repository or check the README for more details.
+        """
+    )
+
+# Combine all interfaces
 app = gr.TabbedInterface(
-    [demo, json_api],
-    ["Tone Recognition", "JSON API"],
+    [demo, json_api, api_docs],
+    ["Tone Recognition", "JSON API", "API Documentation"],
     title="Pro-TeVA: Prototype-based Explainable Tone Recognition for Yoruba"
 )