API_FORMAT_DOCUMENTATION.md

# Essay Analysis API - Exact JSON Format

## API Endpoints Overview

This API provides comprehensive essay analysis with the exact JSON format required by the web development team.

### Available Endpoints

1. **`/api/essay-analysis`** - Comprehensive essay analysis (supports optional question parameter)
2. **`/api/essay-analysis-with-question`** - **NEW** Comprehensive essay analysis based on a specific question
3. **`/api/feedback`** - Feedback generation (supports optional question parameter)
4. **`/api/feedback-with-question`** - **NEW** Feedback generation based on a specific question

## Updated API Endpoint: `/api/essay-analysis`

This endpoint now supports an optional question parameter for question-specific analysis.

### Request
- **Method**: POST
- **Content-Type**: application/x-www-form-urlencoded
- **Body**: 
  - `essay_text=<your_essay_text>` (required)
  - `question=<your_specific_question>` (optional)

### Response Format

The API returns a JSON object with the following exact structure:

**When no question is provided (general analysis):**
```json
{
  "originalEssayWordCount": 300,
  "reWrittenEssayWordCount": 300,
  "originalEssay": "Your original essay text here...",
  "reWrittenEssay": "Your rewritten essay text here...",
  "overallEssayEvaluationScore": 70,
  "analysisType": "general",
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 70,
      "analysis": "Detailed analysis of grammar and punctuation",
      "issuesCount": 2,
      "issuesList": [
        {
          "before": "Original text with error",
          "after": "Corrected text",
          "explanation": "Why this change is needed"
        }
      ],
      "positivePoints": ["Specific examples of good grammar usage"]
    }
  ],
  "essayStructure": [
    {
      "label": "Introduction & Thesis",
      "features": [
        {
          "label": "Clear Thesis Statement",
          "isCorrect": true
        },
        {
          "label": "Engaging Introduction",
          "isCorrect": false,
          "errorMessage": "Introduction should be more engaging and capture reader's attention."
        }
      ]
    }
  ],
  "topicSpecificFeedback": {
    "topicCoverage": "Detailed analysis of how well the topic is addressed",
    "missingAspects": ["Aspects that could be better covered"],
    "strengths": ["Specific strengths in topic handling"],
    "improvementSuggestions": ["Specific suggestions for better topic coverage"]
  }
}
```

**When a question is provided (question-specific analysis):**
```json
{
  "originalEssayWordCount": 300,
  "reWrittenEssayWordCount": 300,
  "originalEssay": "Your original essay text here...",
  "reWrittenEssay": "Your rewritten essay text here...",
  "overallEssayEvaluationScore": 70,
  "analysisType": "question_specific",
  "question": "Your specific question here...",
  "questionSpecificFeedback": {
    "question": "Your specific question here...",
    "question_relevance_score": 85,
    "question_coverage": "Detailed analysis of how well the question is addressed",
    "covered_aspects": ["Specific aspects of the question that are well covered"],
    "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
    "strengths": ["Specific strengths in addressing the question"],
    "improvement_suggestions": ["Specific suggestions for better question coverage"]
  },
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 70,
      "analysis": "Detailed analysis of grammar and punctuation",
      "issuesCount": 2,
      "issuesList": [
        {
          "before": "Original text with error",
          "after": "Corrected text",
          "explanation": "Why this change is needed"
        }
      ],
      "positivePoints": ["Specific examples of good grammar usage"]
    }
  ],
  "essayStructure": [
    {
      "label": "Introduction & Thesis",
      "features": [
        {
          "label": "Clear Thesis Statement",
          "isCorrect": true
        },
        {
          "label": "Engaging Introduction",
          "isCorrect": false,
          "errorMessage": "Introduction should be more engaging and capture reader's attention."
        }
      ]
    }
  ]
}
```

## Updated API Endpoint: `/api/feedback`

This endpoint now supports an optional question parameter for question-specific feedback.

### Request
- **Method**: POST
- **Content-Type**: application/x-www-form-urlencoded
- **Body**: 
  - `essay_text=<your_essay_text>` (required)
  - `question=<your_specific_question>` (optional)

### Response Format

**When no question is provided (general feedback):**
```json
{
  "feedback": {
    "sections": [
      {
        "name": "Grammar & Punctuation",
        "score": 85,
        "analysis": "Detailed analysis of grammar and punctuation",
        "issues": [
          {
            "before": "Original text with error",
            "after": "Corrected text",
            "explanation": "Why this change is needed"
          }
        ],
        "positive_points": ["Specific examples of good grammar usage"],
        "issues_count": 1
      }
    ],
    "overall_score": 82,
    "essay_structure": {
      "Introduction & Thesis": {
        "Clear Thesis Statement": {
          "value": true,
          "explanation": "Thesis is clearly stated",
          "suggestions": "Consider strengthening the thesis"
        }
      }
    }
  },
  "feedback_type": "general",
  "question": null,
  "pdf_path": "/path/to/generated/pdf"
}
```

**When a question is provided (question-specific feedback):**
```json
{
  "feedback": {
    "sections": [
      {
        "name": "Grammar & Punctuation",
        "score": 85,
        "analysis": "Detailed analysis of grammar and punctuation",
        "issues": [
          {
            "before": "Original text with error",
            "after": "Corrected text",
            "explanation": "Why this change is needed"
          }
        ],
        "positive_points": ["Specific examples of good grammar usage"],
        "issues_count": 1
      }
    ],
    "overall_score": 82,
    "essay_structure": {
      "Introduction & Thesis": {
        "Clear Thesis Statement": {
          "value": true,
          "explanation": "Thesis is clearly stated",
          "suggestions": "Consider strengthening the thesis"
        }
      }
    },
    "question_specific_feedback": {
      "question": "Your specific question here...",
      "question_relevance_score": 85,
      "question_coverage": "Detailed analysis of how well the question is addressed",
      "covered_aspects": ["Specific aspects of the question that are well covered"],
      "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
      "strengths": ["Specific strengths in addressing the question"],
      "improvement_suggestions": ["Specific suggestions for better question coverage"]
    }
  },
  "feedback_type": "question_specific",
  "question": "Your specific question here...",
  "pdf_path": "/path/to/generated/pdf"
}
```

## New API Endpoint: `/api/essay-analysis-with-question`

This endpoint provides comprehensive essay analysis with the exact JSON format required by the web development team, but now includes question-specific evaluation.

### Request
- **Method**: POST
- **Content-Type**: application/x-www-form-urlencoded
- **Body**: 
  - `essay_text=<your_essay_text>`
  - `question=<your_specific_question>`

### Response Format

The API returns a JSON object with the following exact structure:

```json
{
  "originalEssayWordCount": 300,
  "reWrittenEssayWordCount": 300,
  "originalEssay": "Your original essay text here...",
  "reWrittenEssay": "Your rewritten essay text here...",
  "overallEssayEvaluationScore": 70,
  "question": "Your specific question here...",
  "questionSpecificFeedback": {
    "question": "Your specific question here...",
    "question_relevance_score": 85,
    "question_coverage": "Detailed analysis of how well the question is addressed",
    "covered_aspects": ["Specific aspects of the question that are well covered"],
    "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
    "strengths": ["Specific strengths in addressing the question"],
    "improvement_suggestions": ["Specific suggestions for better question coverage"]
  },
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 70,
      "analysis": "Detailed analysis of grammar and punctuation",
      "issuesCount": 2,
      "issuesList": [
        {
          "before": "Original text with error",
          "after": "Corrected text",
          "explanation": "Why this change is needed"
        }
      ],
      "positivePoints": ["Specific examples of good grammar usage"]
    },
    {
      "label": "Vocabulary Usage",
      "score": 75,
      "analysis": "Detailed analysis of vocabulary usage",
      "issuesCount": 1,
      "issuesList": [
        {
          "before": "Original word/phrase",
          "after": "Improved word/phrase",
          "explanation": "Why this improvement is suggested"
        }
      ],
      "positivePoints": ["Specific examples of good vocabulary usage"]
    },
    {
      "label": "Sentence Structure",
      "score": 100,
      "analysis": "Detailed analysis of sentence structure",
      "issuesCount": 0,
      "issuesList": [],
      "positivePoints": ["Specific examples of good sentence structure"]
    }
  ],
  "essayStructure": [
    {
      "label": "Introduction & Thesis",
      "features": [
        {
          "label": "Clear Thesis Statement",
          "isCorrect": true
        },
        {
          "label": "Engaging Introduction",
          "isCorrect": false,
          "errorMessage": "Introduction should be more engaging and capture reader's attention."
        },
        {
          "label": "Background Context",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Body Development",
      "features": [
        {
          "label": "Topic Sentences",
          "isCorrect": true
        },
        {
          "label": "Supporting Evidence",
          "isCorrect": true
        },
        {
          "label": "Logical Flow",
          "isCorrect": true
        },
        {
          "label": "Paragraph Coherence",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Content Quality",
      "features": [
        {
          "label": "Relevance to Topic",
          "isCorrect": true
        },
        {
          "label": "Depth of Analysis",
          "isCorrect": false,
          "errorMessage": "Analysis could be deeper with more critical examination of the topic."
        },
        {
          "label": "Use of Examples",
          "isCorrect": true
        },
        {
          "label": "Critical Thinking",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Evidence & Citations",
      "features": [
        {
          "label": "Factual Accuracy",
          "isCorrect": true
        },
        {
          "label": "Source Credibility",
          "isCorrect": true
        },
        {
          "label": "Proper Citations",
          "isCorrect": false,
          "errorMessage": "Citations should follow proper academic format."
        },
        {
          "label": "Statistical Data",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Conclusion",
      "features": [
        {
          "label": "Summary of Arguments",
          "isCorrect": true
        },
        {
          "label": "Policy Recommendations",
          "isCorrect": true
        },
        {
          "label": "Future Implications",
          "isCorrect": true
        },
        {
          "label": "Strong Closing",
          "isCorrect": true
        }
      ]
    }
  ]
}
```

## New API Endpoint: `/api/feedback-with-question`

This endpoint provides detailed feedback based on a specific question.

### Request
- **Method**: POST
- **Content-Type**: application/x-www-form-urlencoded
- **Body**: 
  - `essay_text=<your_essay_text>`
  - `question=<your_specific_question>`

### Response Format

```json
{
  "feedback": {
    "sections": [
      {
        "name": "Grammar & Punctuation",
        "score": 85,
        "analysis": "Detailed analysis of grammar and punctuation",
        "issues": [
          {
            "before": "Original text with error",
            "after": "Corrected text",
            "explanation": "Why this change is needed"
          }
        ],
        "positive_points": ["Specific examples of good grammar usage"],
        "issues_count": 1
      }
    ],
    "overall_score": 82,
    "essay_structure": {
      "Introduction & Thesis": {
        "Clear Thesis Statement": {
          "value": true,
          "explanation": "Thesis is clearly stated",
          "suggestions": "Consider strengthening the thesis"
        }
      }
    },
    "question_specific_feedback": {
      "question": "Your specific question here...",
      "question_relevance_score": 85,
      "question_coverage": "Detailed analysis of how well the question is addressed",
      "covered_aspects": ["Specific aspects of the question that are well covered"],
      "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
      "strengths": ["Specific strengths in addressing the question"],
      "improvement_suggestions": ["Specific suggestions for better question coverage"]
    }
  },
  "question": "Your specific question here...",
  "pdf_path": "/path/to/generated/pdf"
}
```

## Field Descriptions

### Top-level Fields (for essay-analysis-with-question)
- `originalEssayWordCount` (integer): Number of words in the original essay
- `reWrittenEssayWordCount` (integer): Number of words in the rewritten essay
- `originalEssay` (string): The original essay text submitted by the user
- `reWrittenEssay` (string): The AI-improved version of the essay
- `overallEssayEvaluationScore` (integer): Overall score from 0-100
- `question` (string): The specific question that was evaluated (only when question is provided)
- `questionSpecificFeedback` (object): Detailed feedback on how well the essay addresses the question (only when question is provided)
- `evaluationAndScoring` (array): Detailed evaluation in multiple categories
- `essayStructure` (array): Essay structure analysis
- `analysisType` (string): Either "general" or "question_specific"

### questionSpecificFeedback Object
- `question` (string): The specific question being evaluated
- `question_relevance_score` (integer): Score from 0-100 indicating how well the essay addresses the question
- `question_coverage` (string): Detailed analysis of question coverage
- `covered_aspects` (array): List of question aspects that are well covered
- `missing_aspects` (array): List of question aspects that are missing or poorly addressed
- `strengths` (array): List of strengths in addressing the question
- `improvement_suggestions` (array): List of suggestions for better question coverage

### evaluationAndScoring Array
Each item contains:
- `label` (string): Category name
- `score` (integer): Score from 0-100 for this category
- `analysis` (string): Detailed analysis of the category
- `issuesCount` (integer): Number of issues found
- `issuesList` (array): List of specific issues with before/after corrections and explanations
- `positivePoints` (array): List of positive aspects in this category

### essayStructure Array
Each item contains:
- `label` (string): Structure category name
- `features` (array): List of features evaluated in this category
  - `label` (string): Feature name
  - `isCorrect` (boolean): Whether the feature is correct
  - `errorMessage` (string, optional): Error message if `isCorrect` is false

## Example Usage

### Testing the Updated Endpoints

```python
import requests

# Test the updated essay analysis endpoint without question
response = requests.post(
    "http://localhost:8000/api/essay-analysis",
    data={"essay_text": "Your essay text here..."},
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Overall Score: {result['overallEssayEvaluationScore']}")
    print(f"Analysis Type: {result['analysisType']}")

# Test the updated essay analysis endpoint with question
response = requests.post(
    "http://localhost:8000/api/essay-analysis",
    data={
        "essay_text": "Your essay text here...",
        "question": "Discuss the impact of climate change on global economies."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Overall Score: {result['overallEssayEvaluationScore']}")
    print(f"Question: {result['question']}")
    print(f"Question Relevance Score: {result['questionSpecificFeedback']['question_relevance_score']}")
    print(f"Analysis Type: {result['analysisType']}")

# Test the updated feedback endpoint without question
response = requests.post(
    "http://localhost:8000/api/feedback",
    data={"essay_text": "Your essay text here..."},
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Feedback Type: {result['feedback_type']}")
    print(f"Overall Score: {result['feedback']['overall_score']}")

# Test the updated feedback endpoint with question
response = requests.post(
    "http://localhost:8000/api/feedback",
    data={
        "essay_text": "Your essay text here...",
        "question": "Analyze the role of technology in modern education."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Feedback Type: {result['feedback_type']}")
    print(f"Question: {result['question']}")
    print(f"Question Relevance Score: {result['feedback']['question_specific_feedback']['question_relevance_score']}")
```

### Testing the New Question-Specific Endpoint

```python
import requests

# Test the new question-specific API
response = requests.post(
    "http://localhost:8000/api/essay-analysis-with-question",
    data={
        "essay_text": "Your essay text here...",
        "question": "Discuss the impact of climate change on global economies."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Overall Score: {result['overallEssayEvaluationScore']}")
    print(f"Question: {result['question']}")
    print(f"Question Relevance Score: {result['questionSpecificFeedback']['question_relevance_score']}")
    print(f"Original Word Count: {result['originalEssayWordCount']}")
    print(f"Rewritten Word Count: {result['reWrittenEssayWordCount']}")
```

### Testing the Feedback with Question Endpoint

```python
import requests

# Test the feedback with question API
response = requests.post(
    "http://localhost:8000/api/feedback-with-question",
    data={
        "essay_text": "Your essay text here...",
        "question": "Analyze the role of technology in modern education."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Question: {result['question']}")
    print(f"Overall Score: {result['feedback']['overall_score']}")
    print(f"Question Relevance Score: {result['feedback']['question_specific_feedback']['question_relevance_score']}")
```

## Testing

Run the test script to verify the API format:
```bash
python test_api_format.py
```

This will test all endpoints including the updated existing endpoints and new question-specific ones and save the full responses to JSON files for inspection.

## Key Differences Between Endpoints

1. **Updated Existing Endpoints** (`/api/essay-analysis`, `/api/feedback`):
   - Accept optional `question` parameter
   - Provide general analysis/feedback when no question is provided
   - Provide question-specific analysis/feedback when question is provided
   - Include `analysisType` or `feedback_type` field to indicate the type of analysis
   - Backward compatible with existing implementations

2. **New Question-Specific Endpoints** (`/api/essay-analysis-with-question`, `/api/feedback-with-question`):
   - Require both `essay_text` and `question` parameters
   - Always provide question-specific analysis and feedback
   - Include question relevance scoring
   - Focus on how well the essay addresses the specific question
   - Provide detailed feedback on question coverage and missing aspects