Sentinel (Content Moderation Microservice)

A high-performance, asynchronous content moderation API powered by FastAPI and Google Gemini AI.

Architecture

Sentinel implements a non-blocking architecture using FastAPI's BackgroundTasks:

1. Ingest: API receives text payload and saves it to MySQL with status PENDING.
2. Acknowledge: Returns a task_id to the client immediately.
3. Process: A background worker thread sends the payload to selected Google's Gemini model.
4. Update: The result (Safe/Unsafe, Category, Confidence) is written back to the database asynchronously.

Tech Stack

• API Framework: FastAPI (Python)
• AI Model: Google Gemini Flash/Pro (can be configured in .env)
• Database: MySQL 8.0
• Containerization: Docker & Docker Compose

Quick Start

Option 1: Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/damashiai/sentinel.git
   cd sentinel

2. Configure Environment: Create a .env file in the root directory:

   # Database Config
   MYSQL_ROOT_PASSWORD=secret
   MYSQL_DATABASE=sentinel_db
   MYSQL_USER=sentinel_user
   MYSQL_PASSWORD=sentinel_pass
   
   # AI Config
   GEMINI_API_KEY=your_google_api_key_here
   GEMINI_MODEL=models/gemini-flash-latest

3. Launch:

   docker-compose up --build

   The API will be available at http://localhost:8000/docs.

Option 2: Local Development

1. Install Dependencies:

   python -m venv venv
   source venv/bin/activate # or venv\Scripts\activate on Windows
   pip install -r requirements.txt

2. Setup Database: Ensure you have a MySQL server running (or have a cloud MySQL instance running) and update the DATABASE_URL in your .env file to point to localhost (or your cloud MySQL DB URL).

3. Run Server:

   uvicorn main:app --reload

API Usage

1. Submit Content

POST /analyze

{
  "text": "You are stupid and I hate you."
}

2. Check Status

GET /status/{task_id}

{
  "id": 1,
  "status": "COMPLETED",
  "result": {
    "safe": false,
    "category": "hate_speech",
    "confidence": 0.99
  }
}

License

MIT License.