Hugging Face's logo

Spaces:
kaeizen
/
grammo
Sleeping

App Files Community
grammo / README.md
kaeizen's picture
kaeizen
add readme
0d8c6f8
preview code
|
raw
history blame
21 kB
metadata
title: Grammo
emoji: 👀
colorFrom: purple
colorTo: yellow
sdk: docker
pinned: false
license: gpl-3.0
short_description: AI Translation and Grammar Correction

Grammo Backend

Django REST API backend for Grammo, an AI-powered translation and grammar correction service.

Overview

The Grammo backend provides a RESTful API for translation and grammar correction services. It leverages LangChain and HuggingFace models to process language requests, with LangGraph managing conversation state across sessions.

Features

  • 🌐 Translation Service - Natural, contextually appropriate translations between languages
  • ✏️ Grammar Correction - Fixes grammar, spelling, and punctuation errors
  • 💬 Session Management - Maintains conversation context using Django sessions and LangGraph checkpoints
  • 🎭 Customizable Modes - Supports Default and Grammar modes
  • 🎨 Tone Control - Configurable tone (Default, Formal, Casual) for responses
  • 🔒 Security - CORS support, CSRF protection, secure session management
  • 📦 HuggingFace Integration - Uses GPT-OSS-Safeguard-20B model via HuggingFace API

Tech Stack

  • Django 5.2.7 - Web framework
  • Django REST Framework - API development
  • LangChain - AI agent orchestration
  • LangGraph - Conversation state management
  • HuggingFace - Language model integration (GPT-OSS-Safeguard-20B)
  • Python 3.14+ - Programming language
  • SQLite - Database (development)
  • Uvicorn - ASGI server

Prerequisites

  • Python 3.14 or higher
  • pip (Python package manager)
  • HuggingFace API Token (Get one here)

Installation

1. Navigate to the backend directory 

cd backend

2. Create and activate a virtual environment 

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

3. Install dependencies 

pip install -r requirements.txt

4. Set up environment variables

Create a .env file in the backend directory:

touch .env

Add the following environment variables (see Environment Variables section for details):

SECRET_KEY=your-secret-key-here
HUGGINGFACEHUB_API_TOKEN=your-huggingface-api-token
DEBUG=True

To generate a Django secret key:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

5. Run database migrations 

python manage.py migrate

Environment Variables

Create a .env file in the backend directory with the following variables:

Required Variables 

# Django Secret Key (generate one using the command above)
SECRET_KEY=your-secret-key-here

# HuggingFace API Token
HUGGINGFACEHUB_API_TOKEN=your-huggingface-api-token

Optional Development Variables 

# Debug mode (default: True)
DEBUG=True

# Session security (default: False for development)
SESSION_COOKIE_SECURE=False  # Set to True in production (requires HTTPS)
CSRF_COOKIE_SECURE=False     # Set to True in production (requires HTTPS)

# CORS settings
CORS_ALLOW_ALL_ORIGINS=True  # Set to False in production and specify origins

Optional Production Variables 

# Allowed hosts (comma-separated)
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

# CSRF trusted origins (comma-separated)
CSRF_TRUSTED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

# Security settings
SECURE_SSL_REDIRECT=True
SECURE_CONTENT_TYPE_NOSNIFF=True
SECURE_HSTS_SECONDS=31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS=True
SECURE_HSTS_PRELOAD=True

Running the Application

Development Mode

Option 1: Django Development Server (with warnings)

python manage.py runserver

The server will run on http://localhost:8000

Option 2: Uvicorn ASGI Server (production-like, no warnings)

uvicorn backend.asgi:application --host 0.0.0.0 --port 8000 --reload

Production Mode 

# Set DEBUG=False in .env
uvicorn backend.asgi:application --host 0.0.0.0 --port 8000

# With multiple workers:
uvicorn backend.asgi:application --host 0.0.0.0 --port 8000 --workers 4

Standalone Script (for HuggingFace Spaces)

The backend can also be run as a standalone script:

python app.py

This uses the PORT environment variable (defaults to 7860) and is configured for HuggingFace Spaces deployment.

API Endpoints

Base URL

All endpoints are prefixed with /api/v1/

GET /api/v1/hello/

Health check endpoint.

Response:

{
  "message": "Hello from Grammo!"
}

POST /api/v1/chat/

Send a message to start or continue a chat session.

Request Body:

{
  "message": "Translate this text to French",
  "chatSession": 0,
  "mode": "default",
  "tone": "default"
}

Parameters:

  • message (required): The user's message
  • chatSession (optional): Session identifier to maintain conversation context
  • mode (optional): "default" or "grammar" - Determines how the message is processed
  • tone (optional): "default", "formal", or "casual" - Sets the tone of the response

Response (Success):

{
  "status": "success",
  "response": "**Original**: \nTranslate this text to French\n**Output**: \nTraduisez ce texte en français\n___\n**Explanation**: \n> Direct translation maintaining the original meaning"
}

Response (Error):

{
  "status": "error",
  "response": "Invalid message."
}

POST /api/v1/end/

End the current chat session and clear conversation history.

Request Body:

{}

Response (Success):

{
  "status": "success",
  "message": "Session ended successfully"
}

Response (Error):

{
  "status": "error",
  "response": "No active session."
}

Project Structure 

backend/
├── agent_manager/           # AI agent management module
│   └── __init__.py         # LangChain agent setup, session management
├── api/                    # Django REST API application
│   ├── views.py            # API view handlers (chat, hello, end)
│   ├── urls.py             # URL routing
│   └── apps.py             # App configuration
├── backend/                # Django project settings
│   ├── settings.py         # Django configuration
│   ├── urls.py             # Main URL configuration
│   ├── asgi.py             # ASGI application
│   └── wsgi.py             # WSGI application
├── app.py                  # Standalone entry point (HuggingFace Spaces)
├── manage.py               # Django management script
├── requirements.txt        # Python dependencies
├── Dockerfile              # Docker configuration for deployment
└── README.md               # This file

Development

Session Management

  • Sessions are managed using Django's session framework
  • Session data is stored in the cache backend (in-memory for development)
  • Each session maintains its own LangGraph agent with conversation checkpointing
  • Sessions expire after 24 hours of inactivity or when explicitly ended

Agent Architecture

  • Uses LangChain's create_agent with a structured output wrapper
  • Structured output ensures consistent JSON responses for translation/correction tasks
  • Agents are cached per session key for efficient memory usage
  • Supports task types: translation, correction, follow-up, invalid

Database

  • Uses SQLite by default (suitable for development)
  • No models are currently defined, but Django is configured for future database needs
  • Run python manage.py migrate to set up the database schema

Caching

  • In-memory cache is used for sessions (development)
  • Note: For production, consider switching to Redis or another persistent cache backend

CORS Configuration

  • CORS is configured to allow cross-origin requests
  • In production, configure CORS_ALLOW_ALL_ORIGINS and ALLOWED_HOSTS appropriately

Deployment

Docker Deployment (HuggingFace Spaces)

The backend includes a Dockerfile configured for HuggingFace Spaces deployment.

  1. Set environment variables in your Space settings:

    • SECRET_KEY
    • HUGGINGFACEHUB_API_TOKEN
    • DEBUG=False
    • ALLOWED_HOSTS=your-space-name.hf.space
    • CORS_ALLOW_ALL_ORIGINS=False
    • CSRF_TRUSTED_ORIGINS=https://your-space-name.hf.space
    • SESSION_COOKIE_SECURE=True
    • CSRF_COOKIE_SECURE=True

  2. Push your code to the Space repository

  3. The API will be available at https://your-space-name.hf.space/api/v1/

General Production Deployment

  1. Set production environment variables (see Environment Variables)
  2. Set DEBUG=False
  3. Configure a proper database (PostgreSQL recommended)
  4. Set up Redis or another cache backend for sessions
  5. Use a production ASGI server (Uvicorn with multiple workers or Gunicorn with Uvicorn workers)
  6. Configure reverse proxy (Nginx, Apache) with SSL/TLS
  7. Set up static file serving or use a CDN

Testing

To test the API endpoints:

# Health check
curl http://localhost:8000/api/v1/hello/

# Send a chat message
curl -X POST http://localhost:8000/api/v1/chat/ \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, translate this to Spanish", "mode": "default", "tone": "default"}'

# End session
curl -X POST http://localhost:8000/api/v1/end/

Troubleshooting

Common Issues

  1. Module not found errors: Ensure your virtual environment is activated and dependencies are installed
  2. Secret key errors: Make sure SECRET_KEY is set in your .env file
  3. HuggingFace API errors: Verify your HUGGINGFACEHUB_API_TOKEN is valid
  4. CORS errors: Check CORS_ALLOW_ALL_ORIGINS and ALLOWED_HOSTS settings
  5. Session not persisting: Ensure cache backend is configured correctly

Notes

  • The application uses in-memory session storage for development. For production, consider using Redis.
  • The HuggingFace model (openai/gpt-oss-safeguard-20b) is used for all language processing tasks.
  • Conversation state is managed per Django session using LangGraph's checkpoint system.
  • The structured output wrapper ensures responses follow a consistent JSON schema.

License

See the LICENSE file for details.

title: Grammo emoji: 👀 colorFrom: purple colorTo: yellow sdk: docker pinned: false license: gpl-3.0 short_description: AI Translation and Grammar Correction

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Grammo Backend

Django REST API backend for Grammo, an AI-powered translation and grammar correction service.

Overview

The Grammo backend provides a RESTful API for translation and grammar correction services. It leverages LangChain and HuggingFace models to process language requests, with LangGraph managing conversation state across sessions.

Features

  • 🌐 Translation Service - Natural, contextually appropriate translations between languages
  • ✏️ Grammar Correction - Fixes grammar, spelling, and punctuation errors
  • 💬 Session Management - Maintains conversation context using Django sessions and LangGraph checkpoints
  • 🎭 Customizable Modes - Supports Default and Grammar modes
  • 🎨 Tone Control - Configurable tone (Default, Formal, Casual) for responses
  • 🔒 Security - CORS support, CSRF protection, secure session management
  • 📦 HuggingFace Integration - Uses GPT-OSS-Safeguard-20B model via HuggingFace API

Tech Stack

  • Django 5.2.7 - Web framework
  • Django REST Framework - API development
  • LangChain - AI agent orchestration
  • LangGraph - Conversation state management
  • HuggingFace - Language model integration (GPT-OSS-Safeguard-20B)
  • Python 3.14+ - Programming language
  • SQLite - Database (development)
  • Uvicorn - ASGI server

Prerequisites

  • Python 3.14 or higher
  • pip (Python package manager)
  • HuggingFace API Token (Get one here)

Installation

1. Navigate to the backend directory 

cd backend

2. Create and activate a virtual environment 

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

3. Install dependencies 

pip install -r requirements.txt

4. Set up environment variables

Create a .env file in the backend directory:

touch .env

Add the following environment variables (see Environment Variables section for details):

SECRET_KEY=your-secret-key-here
HUGGINGFACEHUB_API_TOKEN=your-huggingface-api-token
DEBUG=True

To generate a Django secret key:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

5. Run database migrations 

python manage.py migrate

Environment Variables

Create a .env file in the backend directory with the following variables:

Required Variables 

# Django Secret Key (generate one using the command above)
SECRET_KEY=your-secret-key-here

# HuggingFace API Token
HUGGINGFACEHUB_API_TOKEN=your-huggingface-api-token

Optional Development Variables 

# Debug mode (default: True)
DEBUG=True

# Session security (default: False for development)
SESSION_COOKIE_SECURE=False  # Set to True in production (requires HTTPS)
CSRF_COOKIE_SECURE=False     # Set to True in production (requires HTTPS)

# CORS settings
CORS_ALLOW_ALL_ORIGINS=True  # Set to False in production and specify origins

Optional Production Variables 

# Allowed hosts (comma-separated)
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

# CSRF trusted origins (comma-separated)
CSRF_TRUSTED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

# Security settings
SECURE_SSL_REDIRECT=True
SECURE_CONTENT_TYPE_NOSNIFF=True
SECURE_HSTS_SECONDS=31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS=True
SECURE_HSTS_PRELOAD=True

Running the Application

Development Mode

Option 1: Django Development Server (with warnings)

python manage.py runserver

The server will run on http://localhost:8000

Option 2: Uvicorn ASGI Server (production-like, no warnings)

uvicorn backend.asgi:application --host 0.0.0.0 --port 8000 --reload

Production Mode 

# Set DEBUG=False in .env
uvicorn backend.asgi:application --host 0.0.0.0 --port 8000

# With multiple workers:
uvicorn backend.asgi:application --host 0.0.0.0 --port 8000 --workers 4

Standalone Script (for HuggingFace Spaces)

The backend can also be run as a standalone script:

python app.py

This uses the PORT environment variable (defaults to 7860) and is configured for HuggingFace Spaces deployment.

API Endpoints

Base URL

All endpoints are prefixed with /api/v1/

GET /api/v1/hello/

Health check endpoint.

Response:

{
  "message": "Hello from Grammo!"
}

POST /api/v1/chat/

Send a message to start or continue a chat session.

Request Body:

{
  "message": "Translate this text to French",
  "chatSession": 0,
  "mode": "default",
  "tone": "default"
}

Parameters:

  • message (required): The user's message
  • chatSession (optional): Session identifier to maintain conversation context
  • mode (optional): "default" or "grammar" - Determines how the message is processed
  • tone (optional): "default", "formal", or "casual" - Sets the tone of the response

Response (Success):

{
  "status": "success",
  "response": "**Original**: \nTranslate this text to French\n**Output**: \nTraduisez ce texte en français\n___\n**Explanation**: \n> Direct translation maintaining the original meaning"
}

Response (Error):

{
  "status": "error",
  "response": "Invalid message."
}

POST /api/v1/end/

End the current chat session and clear conversation history.

Request Body:

{}

Response (Success):

{
  "status": "success",
  "message": "Session ended successfully"
}

Response (Error):

{
  "status": "error",
  "response": "No active session."
}

Project Structure 

backend/
├── agent_manager/           # AI agent management module
│   └── __init__.py         # LangChain agent setup, session management
├── api/                    # Django REST API application
│   ├── views.py            # API view handlers (chat, hello, end)
│   ├── urls.py             # URL routing
│   └── apps.py             # App configuration
├── backend/                # Django project settings
│   ├── settings.py         # Django configuration
│   ├── urls.py             # Main URL configuration
│   ├── asgi.py             # ASGI application
│   └── wsgi.py             # WSGI application
├── app.py                  # Standalone entry point (HuggingFace Spaces)
├── manage.py               # Django management script
├── requirements.txt        # Python dependencies
├── Dockerfile              # Docker configuration for deployment
└── README.md               # This file

Development

Session Management

  • Sessions are managed using Django's session framework
  • Session data is stored in the cache backend (in-memory for development)
  • Each session maintains its own LangGraph agent with conversation checkpointing
  • Sessions expire after 24 hours of inactivity or when explicitly ended

Agent Architecture

  • Uses LangChain's create_agent with a structured output wrapper
  • Structured output ensures consistent JSON responses for translation/correction tasks
  • Agents are cached per session key for efficient memory usage
  • Supports task types: translation, correction, follow-up, invalid

Database

  • Uses SQLite by default (suitable for development)
  • No models are currently defined, but Django is configured for future database needs
  • Run python manage.py migrate to set up the database schema

Caching

  • In-memory cache is used for sessions (development)
  • Note: For production, consider switching to Redis or another persistent cache backend

CORS Configuration

  • CORS is configured to allow cross-origin requests
  • In production, configure CORS_ALLOW_ALL_ORIGINS and ALLOWED_HOSTS appropriately

Deployment

Docker Deployment (HuggingFace Spaces)

The backend includes a Dockerfile configured for HuggingFace Spaces deployment.

  1. Set environment variables in your Space settings:

    • SECRET_KEY
    • HUGGINGFACEHUB_API_TOKEN
    • DEBUG=False
    • ALLOWED_HOSTS=your-space-name.hf.space
    • CORS_ALLOW_ALL_ORIGINS=False
    • CSRF_TRUSTED_ORIGINS=https://your-space-name.hf.space
    • SESSION_COOKIE_SECURE=True
    • CSRF_COOKIE_SECURE=True

  2. Push your code to the Space repository

  3. The API will be available at https://your-space-name.hf.space/api/v1/

General Production Deployment

  1. Set production environment variables (see Environment Variables)
  2. Set DEBUG=False
  3. Configure a proper database (PostgreSQL recommended)
  4. Set up Redis or another cache backend for sessions
  5. Use a production ASGI server (Uvicorn with multiple workers or Gunicorn with Uvicorn workers)
  6. Configure reverse proxy (Nginx, Apache) with SSL/TLS
  7. Set up static file serving or use a CDN

Testing

To test the API endpoints:

# Health check
curl http://localhost:8000/api/v1/hello/

# Send a chat message
curl -X POST http://localhost:8000/api/v1/chat/ \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, translate this to Spanish", "mode": "default", "tone": "default"}'

# End session
curl -X POST http://localhost:8000/api/v1/end/

Troubleshooting

Common Issues

  1. Module not found errors: Ensure your virtual environment is activated and dependencies are installed
  2. Secret key errors: Make sure SECRET_KEY is set in your .env file
  3. HuggingFace API errors: Verify your HUGGINGFACEHUB_API_TOKEN is valid
  4. CORS errors: Check CORS_ALLOW_ALL_ORIGINS and ALLOWED_HOSTS settings
  5. Session not persisting: Ensure cache backend is configured correctly

Notes

  • The application uses in-memory session storage for development. For production, consider using Redis.
  • The HuggingFace model (openai/gpt-oss-safeguard-20b) is used for all language processing tasks.
  • Conversation state is managed per Django session using LangGraph's checkpoint system.
  • The structured output wrapper ensures responses follow a consistent JSON schema.

License

See the LICENSE file for details.