stevef1uk/emotion-service repository overview

⁠Emotion Service API – Powered by Fine-Tuned Gemma

A lightweight, fine-tuned Gemma3 emotion detection model served via an easy-to-use API.
Classifies raw text into a wide range of emotional categories for use in analytics, conversational AI, and more.

Why do I need this? View a comparison Emotion and Sentiment Model Analysis Report⁠

[Take a looks at the free UI and MCP Tooling that use this container]

(https://github.com/stevef1uk/emotion-server-demo⁠)

⁠🚀 Features

• Fast, containerized Emotion Service API – deploy anywhere with Docker.
• SLM - fine tuned Gemma3:120 model with fine-tuning for emotion detection
• Model file held as a zipped encrypted file in the container to save space
• No data leaves the docker container as LLM integrated
• Emotion detection across 14 categories:
  anger 😡, confusion 😕, desire 🧚, disgust 🤢, fear 😨, guilt 😔, happiness 😊, love ❤️, neutral 😐, sadness 😢, sarcasm 🤨, shame 😳, surprise 😲
• Lightweight inference suitable for edge devices (e.g., Raspberry Pi).
• REST API for easy integration into your apps, dashboards, services or agentic workflows.
• No need to have a GPU to run this container

⁠🚀 Demo of this container running

⁠📦 Getting Started

Pull the appropriate image for your platform:

# For Raspberry Pi (32-bit ARM)
docker pull stevef1uk/emotion-emotion-service:arm

# For Apple Silicon (M1/M2/M3)
docker pull stevef1uk/emotion-service:arm64

# For standard x86_64 (Linux/Windows servers)
docker pull stevef1uk/emotion-service:amd64
Run the container:
docker run -d -p 8000:8000 stevef1uk/emotion-service:arm64


🔗 Basic API Usage
Send a POST request with text to classify:
curl -X POST http://localhost:8000/predict \
     -H "Content-Type: application/json" \
     -d '{"text": "I’m so happy to see you!"}'
Response:
{
  "text": "I’m so happy to see you!",
  "emotion": "happiness",
  "emoji": "😊"
}

🔗 More detailed response API Usage

By default, /predict is optimized for the fastest possible response and returns confidence = 1.0 to avoid extra model work. If you need the actual model probability for the top emotion, opt-in by passing the accurate=1 flag. This incurs a performance penalty but returns true probabilities.

curl -s -X POST 'http://localhost:8000/predict?accurate=1' \
  -H 'Content-Type: application/json' \
  -d '{"text":"I am so happy today!"}' | jq .

For more comprehensive emotion analysis, you can use the detailed endpoint that returns all emotions with their probabilities:

curl -s -X POST http://localhost:8000/predict_detailed -H "Content-Type: application/json" -d '{"text":"Im indifferent to the whole thing"}'
{"predicted_emotion":"neutral","confidence":0.7519972242554809,"all_emotions":{"anger":0.0041356391019992484,"confusion":0.14895972403797408,"desire":0.0001866767494295926,"disgust":0.059526204384173324,"fear":0.00048645763160996185,"guilt":0.0008767175212511274,"happiness":0.007103915113959806,"love":0.0011666307253244926,"neutral":0.7519972242554809,"sadness":0.01683400383071159,"sarcasm":0,"shame":0.007173492306621872,"surprise":0.0007893216119695747}}

📄 Licensing Licensed for evaluation and non-commercial use until December 31st, 2025. After this date, usage requires a separate commercial agreement⁠ All rights to the underlying fine-tuned Gemma3 model remain with the model’s creators and licensors.

⚠️ Disclaimer Provided “as is”, with no warranty of any kind. No guarantee of accuracy, reliability, or fitness for a particular purpose. No official support is provided. Use at your own risk. Reverse engineering of the Data Model contained within this container is expressly forbidden

⁠General Terms

• Licenses are **valid until December 31st each year ** and must be renewed annually unless otherwise noted.
• All licenses are non-transferable without prior written permission.
• The software is provided “AS IS”, without warranty of any kind.
• No guarantee is made regarding fitness for purpose, merchantability, accuracy, or performance.
• The authors are not liable for any damages arising from the use or misuse of this software.

📌 For licensing questions or bulk purchases, please contact:
[Steven Fisher / SJFisher / [email protected]⁠ ** ** Identification SIRET: 902 395 201 00012. ** French VAT Number: FR05902395201. **