Teacher English: AI Assistant for Grammar and Vocabulary

<p align="center"> <img src="https://img.shields.io/badge/Python-3.9+-yellow?style=for-the-badge&logo=python" alt="Python Version"> <img src="https://img.shields.io/badge/flask-3.1.*+-red?style=for-the-badge&logo=flask&logoColor=white" alt="Flask Version"> <img src="https://img.shields.io/badge/LM_Studio-Compatible-informational?style=for-the-badge&logo=ai" alt="LM Studio Compatible"> </p>

A RESTful Flask service that integrates with a local Large Language Model (LLM) (via LM Studio) to aid in English teaching and learning. It offers grammar checks, word translations with contextual examples, and LLM service status checks.

---

🎯 Project Objective

Teacher English aims to simplify and streamline the grammar assessment and vocabulary consultation process for English learners and teachers . By integrating a local LLM, the project offers a self-contained and efficient solution for instant grammar feedback and vocabulary enrichment with practical examples, making learning and teaching more interactive and accessible.

---

✨ Features

The Teacher English exposes the following API endpoints:

• Grammatical Evaluation (/api/grammar/evaluate):

  • Send a sentence in English via POST.
  • Receive a detailed grammar analysis, including corrections, identified errors, and an accuracy percentage.

• Word Translation and Context (/api/translate/word):

  • Provide an English word via POST.
  • Get your Portuguese translation, grammatical type, and example sentences with translation to demonstrate their contextual usage.

• LLM Status (/api/llm/status):

  • Check the availability and operational status of the underlying Large Language Model via GET.
  • Ensure the AI service is up and running.

---

🚀 How to Run

Follow the steps below to configure and run Teacher English on your machine.

Prerequisites

Make sure you have the following installed:

• Python 3.9+: Essential to run the Flask application.
• LM Studio: Software for downloading and running LLMs locally. Download at lmstudio.ai .
• A compatible LLM template: For example, bartowski/llama-3.2-1b-instruct or phi-3-mini-4k-instruct-GGUF. You can download them directly from LM Studio.

1. Environment Configuration

1. Clone the Repository:

   git clone [https://github.com/seu-usuario/teacher_english.git](https://github.com/seu-usuario/teacher_english.git) # Substitua pelo seu usuário/repositório
   cd teacher_english

2. Create and Activate the Virtual Environment:

   python -m venv .venv
   # No Windows (PowerShell):
   .venv\Scripts\Activate.ps1
   # No Windows (CMD):
   .venv\Scripts\activate.bat
   # No macOS / Linux:
   source .venv/bin/activate

3. Install Dependencies:

   pip install Flask python-dotenv pydantic openai

   Or, if you have already generated a requirements.txt:

   pip install -r requirements.txt

4. Create the Environment Variables File (.env):
   In the project root (teacher_english/), create a file named .env with the following content. Adjust LLM_MODEL_NAME to the exact name of the model you loaded into your LM Studio.

   # .env
   # Variáveis de Ambiente para a aplicação teacher_english
   
   # --- Configurações do LLM ---
   # URL base do servidor de inferência do LM Studio.
   # Geralmente é localhost na porta 1234.
   LLM_BASE_URL=http://localhost:1234/v1
   
   # Chave de API para o LM Studio. Para uso local, qualquer string serve.
   LLM_API_KEY=lm-studio_api_key_local
   
   # Nome do modelo LLM carregado no LM Studio.
   # AJUSTE ESTE VALOR para o nome EXATO do modelo que você carregou.
   # Ex: gemma-2-2b-it, lmstudio-community/bartowski/llama-3.2-1b-instruct, etc.
   # Você pode encontrar este nome na aba 'Local Inference Server' do LM Studio.
   LLM_MODEL_NAME=bartowski/llama-3.2-1b-instruct 

5. Create the __init__.py Files:
   Make sure that the files __init__.py (which may be empty) exist in each subdirectory of src/ so that Python recognizes the structure as a package. The structure should be as follows:

   teacher_english/
   ├── .venv/
   ├── src/
   │   ├── __init__.py         <-- Adicione aqui
   │   ├── core/
   │   │   ├── __init__.py     <-- Adicione aqui
   │   │   ├── entities.py
   │   │   └── use_cases.py
   │   ├── adapters/
   │   │   ├── __init__.py     <-- Adicione aqui
   │   │   └── llm_adapter.py
   │   ├── infrastructure/
   │   │   ├── __init__.py     <-- Adicione aqui
   │   │   └── llm_api_client.py
   │   ├── web/
   │   │   ├── __init__.py     <-- Adicione aqui
   │   │   └── controllers.py
   │   └── main.py
   ├── .env
   ├── requirements.txt
   └── README.md
   

   You can create these empty files using touch __init__.py (Linux/macOS) or type nul > __init__.py (Windows CMD) in each corresponding directory.

2. Configuring LLM in LM Studio

1. Open LM Studio.
2. Download the Desired Model: In the "Search" tab, search for and download a compatible model (e.g., bartowski/llama-3.2-1b-instruct). Save it to an SSD for better performance.
3. Load the Model: In the "My Models" tab, select the downloaded model to load it into memory.
4. Start the Local Inference Server: Go to the "Local Inference Server" tab and click "Start Server". Make sure the server is running on port 1234 (or adjust the LLM_BASE_URL variable in your .env if it is different).

3. Launch the Flask Application

With your virtual environment activated and LM Studio running the local inference server, run the Flask application from the project root :

(.venv) python -m src.main

The application will be accessible at http://127.0.0.1:5000/

💻 API Endpoints

All endpoints are prefixed with /api.

1. Evaluate Grammar

• Endpoint: POST /api/grammar/evaluate
• Description: Evaluates the grammar of an English sentence and provides feedback.
• Request Body (JSON):

{
    "phrase": "I has a new car and very happy."
}

• Example Response (JSON):

{
    "comentarios": "A frase foi corrigida para garantir concordância verbal e uso correto do adjetivo. 'Has' foi corrigido para 'have' e 'very happy' para 'very happy'.",
    "erros_encontrados": [
        "Concordância verbal (has -> have)",
        "Uso incorreto de advérbio/adjetivo (very happy -> very happy)"
    ],
    "frase_corrigida": "I have a new car and I am very happy.",
    "frase_original": "I has a new car and very happy.",
    "percentual_assertividade": 75.0
}

2. Translate Word and Suggest Context

• Endpoint: POST /api/translate/word
• Description: Translates a word from English to Portuguese, indicates its grammatical type and provides example sentences with context.
• Request Body (JSON):

{
    "word": "apple"
}

• Example Response (JSON):

{
    "palavra_original": "apple",
    "sugestoes_frases": [
        "She loves to eat an apple every morning. (Ela adora comer uma maçã todas as manhãs.)",
        "The new store sells only the best apples. (A nova loja vende apenas as melhores maçãs.)",
        "An apple a day keeps the doctor away. (Uma maçã por dia mantém o médico afastado.)"
    ],
    "tipo_gramatical": "substantivo",
    "traducao_pt": "maçã"
}

3. LLM Status

• Endpoint: GET /api/llm/status
• Description: Checks the operational status of LLM in LM Studio.
• Response Example (JSON - Active):

{
    "mensagem": "LLM está ativo e respondendo.",
    "modelo_carregado": "gemma-2-2b-it",
    "status": "ativo",
    "tempo_resposta_ms": 65.21
}

• Example Response (JSON - Inactive):

{
    "mensagem": "Não foi possível conectar ao servidor do LLM. Detalhes: [Detalhes do erro de conexão]",
    "modelo_carregado": null,
    "status": "inativo",
    "tempo_resposta_ms": null
}