# TonePilot
[](https://badge.fury.io/py/tonepilot)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
# 🧠 TonePilot
**Emotionally Intelligent Prompt & Response Engine for AI Chatbots**
> **TonePilot** helps your chatbot *understand the user’s tone and personality*—and respond like a human would.
> Whether you're building a customer support bot, a mental health assistant, or a flirty AI companion, TonePilot makes it emotionally resonant and personality-aware.
**✨ Free, Open Source, and Built for Multi-LLM Integration.**
---
## 🚀 Features
- 🎯 **Emotion Detection** – Detect nuanced tones like *anxious*, *playful*, *confused* using transformer-based models
- 🧠 **Emotionally Matched Responses** – Generate emotionally resonant replies using Gemini or Hugging Face
- 🧩 **Pluggable Architecture** – Easily switch between LLMs or swap in your own tone classifiers
- 💡 **Prompt-Only OR Full Response Mode** – Get just the enhanced prompt, or the complete reply
- 🛠️ **CLI + Python API** – Use it in scripts, backends, or with your own chat interface
---
## 📦 Installation
```bash
pip install tonepilot
```
## Quick Start
### Basic Usage (Prompt Generation Only)
```bash
# Generate an emotionally-aware prompt without API keys
tonepilot "I'm feeling overwhelmed with work deadlines"
```
**Output:**
```
📝 Input: I'm feeling overwhelmed with work deadlines
🏷️ Detected tags:
- stressed: 0.456
- anxious: 0.234
⚖️ Response tags and weights:
- calming_supporter: 0.445
- practical_helper: 0.289
🔍 Final prompt:
Respond with calm reassurance and practical guidance. Help organize thoughts and provide actionable steps.
User: I'm feeling overwhelmed with work deadlines
Assistant: (Aim to respond in about 89 words)
```
### Full Response Generation
```bash
# Generate complete responses (requires API key)
tonepilot "I'm excited about my new job!" --mode gemini --respond true
```
## Environment Setup
### For Response Generation (Optional)
If you want to generate actual responses (not just prompts), set up API credentials:
**Option 1: Environment Variable**
```bash
export GOOGLE_API_KEY=your_api_key_here
```
**Option 2: .env File**
```bash
echo "GOOGLE_API_KEY=your_api_key_here" > .env
```
Get your API key from: [Google AI Studio](https://makersuite.google.com/app/apikey)
## CLI Usage
### Basic Commands
```bash
# Default: HuggingFace mode, prompt only
tonepilot "Your text here"
# Generate full response with Gemini
tonepilot "Your text here" --mode gemini --respond true
# Generate full response with HuggingFace
tonepilot "Your text here" --mode hf --respond true
# Different boolean formats accepted
tonepilot "Text" --respond yes
tonepilot "Text" --respond 1
tonepilot "Text" --respond false
```
### Available Options
- `--mode {hf,gemini}`: Choose the response generation model (default: hf)
- `--respond {true,false,yes,no,1,0}`: Generate response or just prompt (default: false)
## Python API
```python
from tonepilot.core.tonepilot import TonePilotEngine
# Initialize engine
engine = TonePilotEngine(mode='hf', respond=False)
# Process text
result = engine.run("I'm nervous about my presentation tomorrow")
print("Detected emotions:", result['input_tags'])
print("Response emotions:", result['response_tags'])
print("Generated prompt:", result['final_prompt'])
# For response generation (requires API key)
engine_with_response = TonePilotEngine(mode='gemini', respond=True)
result = engine_with_response.run("I'm nervous about my presentation tomorrow")
print("Generated response:", result['response_text'])
```
## Architecture
TonePilot uses a sophisticated multi-stage pipeline:
1. **Emotion Detection**: Zero-shot classification using BART-large-MNLI
2. **Tone Mapping**: BERT-based classifier maps input emotions to response personalities
3. **Prompt Blending**: Combines personality traits with weighted importance
4. **Response Generation**: Optional text generation using HuggingFace or Gemini models
### Supported Emotions
**Input Emotions**: curious, angry, sad, excited, confused, hopeful, tired, scared, playful, assertive
**Response Personalities**: empathetic_listener, direct_ally, calming_supporter, practical_helper, and more
## Model Downloads
TonePilot uses a custom-trained BERT classifier for tone mapping. **The model is automatically downloaded on first use** - no manual installation required!
### BERT Tone Classifier
- **File**: `tonepilot_bert_classifier.pt` (475 MB)
- **Download**: [GitHub Releases](https://github.com/sdurgi/tonepilot/releases/download/v0.1.0/tonepilot_bert_classifier.pt)
- **Purpose**: Maps detected emotions to appropriate response personalities
- **Training**: Custom-trained on emotional response datasets
### Automatic Model Management
TonePilot automatically handles model downloads and caching:
1. **First Run**: Downloads model to `~/.cache/tonepilot/` (one-time, ~475 MB)
2. **Subsequent Runs**: Uses cached model for instant loading
3. **Fallback Locations**: Also checks current directory and package directory
**Manual Download** (if needed):
```bash
# Only needed if automatic download fails
wget https://github.com/sdurgi/tonepilot/releases/download/v0.1.0/tonepilot_bert_classifier.pt -P ~/.cache/tonepilot/
# Or place in current directory
curl -L -o tonepilot_bert_classifier.pt https://github.com/sdurgi/tonepilot/releases/download/v0.1.0/tonepilot_bert_classifier.pt
```
**Note**: Internet connection required only on first use for model download.
## Examples
### Different Emotional Contexts
```bash
# Sadness → Empathetic support
tonepilot "My dog passed away yesterday"
# Excitement → Enthusiastic encouragement
tonepilot "I just got accepted to my dream university!"
# Confusion → Clear guidance
tonepilot "I don't understand this math problem at all"
# Anger → Calming and validation
tonepilot "I'm so frustrated with this broken software!"
```
### Integration Examples
**Customer Support Bot:**
```python
def handle_customer_message(message):
engine = TonePilotEngine(mode='gemini', respond=True)
result = engine.run(message)
return result['response_text']
```
**Content Writing Assistant:**
```python
def get_writing_prompt(topic, desired_tone):
engine = TonePilotEngine(respond=False)
result = engine.run(f"Write about {topic} with a {desired_tone} tone")
return result['final_prompt']
```
## Requirements
- Python 3.8+
- PyTorch (automatically installed)
- Transformers library (automatically installed)
- Internet connection for model downloads on first use
**Optional for response generation:**
- Google API key (for Gemini mode)
## Development
```bash
# Clone repository
git clone https://github.com/sdurgi/tonepilot.git
cd tonepilot
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black tonepilot/
```
## Performance
- **Emotion Detection**: ~50ms on CPU
- **Response Generation**: 1-3 seconds (depending on model and length)
- **Memory Usage**: ~500MB (includes cached models)
- **Model Downloads**: ~1GB on first run (cached locally)
## Troubleshooting
**Import Errors**: Ensure all dependencies are installed with `pip install tonepilot`
**API Key Issues**: Verify your `.env` file or environment variables are set correctly
**Model Download Failures**: Check internet connection; models download automatically on first use
**Memory Issues**: Use smaller models or increase available memory
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Citation
```bibtex
@software{tonepilot2024,
title={TonePilot: Emotional Intelligence for Text Generation},
author={Durgi, Srivani},
year={2024},
url={https://github.com/sdurgi/tonepilot}
}
```
## Support
- 📧 Email: sdurgi21@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/sdurgi/tonepilot/issues)
---
**Made with ❤️ for building emotionally intelligent AI systems**
Raw data
{
"_id": null,
"home_page": null,
"name": "tonepilot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Srivani Durgi <sdurgi21@gmail.com>",
"keywords": "emotion, nlp, ai, text-generation, emotional-intelligence, sentiment-analysis, transformers",
"author": null,
"author_email": "Srivani Durgi <sdurgi21@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/60/1c/929856cdd5b4d899fdf2b9a4d572aec0cc6c38fed35b54c39802be106e9b/tonepilot-0.1.2.tar.gz",
"platform": null,
"description": "# TonePilot\n\n[](https://badge.fury.io/py/tonepilot)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n# \ud83e\udde0 TonePilot \n**Emotionally Intelligent Prompt & Response Engine for AI Chatbots**\n\n> **TonePilot** helps your chatbot *understand the user\u2019s tone and personality*\u2014and respond like a human would. \n> Whether you're building a customer support bot, a mental health assistant, or a flirty AI companion, TonePilot makes it emotionally resonant and personality-aware.\n\n**\u2728 Free, Open Source, and Built for Multi-LLM Integration.**\n\n---\n\n## \ud83d\ude80 Features\n\n- \ud83c\udfaf **Emotion Detection** \u2013 Detect nuanced tones like *anxious*, *playful*, *confused* using transformer-based models\n- \ud83e\udde0 **Emotionally Matched Responses** \u2013 Generate emotionally resonant replies using Gemini or Hugging Face\n- \ud83e\udde9 **Pluggable Architecture** \u2013 Easily switch between LLMs or swap in your own tone classifiers\n- \ud83d\udca1 **Prompt-Only OR Full Response Mode** \u2013 Get just the enhanced prompt, or the complete reply\n- \ud83d\udee0\ufe0f **CLI + Python API** \u2013 Use it in scripts, backends, or with your own chat interface\n\n---\n\n## \ud83d\udce6 Installation\n\n\n```bash\npip install tonepilot\n```\n\n## Quick Start\n\n### Basic Usage (Prompt Generation Only)\n\n```bash\n# Generate an emotionally-aware prompt without API keys\ntonepilot \"I'm feeling overwhelmed with work deadlines\"\n```\n\n**Output:**\n```\n\ud83d\udcdd Input: I'm feeling overwhelmed with work deadlines\n\n\ud83c\udff7\ufe0f Detected tags:\n - stressed: 0.456\n - anxious: 0.234\n\n\u2696\ufe0f Response tags and weights:\n - calming_supporter: 0.445\n - practical_helper: 0.289\n\n\ud83d\udd0d Final prompt:\nRespond with calm reassurance and practical guidance. Help organize thoughts and provide actionable steps.\n\nUser: I'm feeling overwhelmed with work deadlines\nAssistant: (Aim to respond in about 89 words)\n```\n\n### Full Response Generation\n\n```bash\n# Generate complete responses (requires API key)\ntonepilot \"I'm excited about my new job!\" --mode gemini --respond true\n```\n\n## Environment Setup\n\n### For Response Generation (Optional)\n\nIf you want to generate actual responses (not just prompts), set up API credentials:\n\n**Option 1: Environment Variable**\n```bash\nexport GOOGLE_API_KEY=your_api_key_here\n```\n\n**Option 2: .env File**\n```bash\necho \"GOOGLE_API_KEY=your_api_key_here\" > .env\n```\n\nGet your API key from: [Google AI Studio](https://makersuite.google.com/app/apikey)\n\n## CLI Usage\n\n### Basic Commands\n\n```bash\n# Default: HuggingFace mode, prompt only\ntonepilot \"Your text here\"\n\n# Generate full response with Gemini\ntonepilot \"Your text here\" --mode gemini --respond true\n\n# Generate full response with HuggingFace\ntonepilot \"Your text here\" --mode hf --respond true\n\n# Different boolean formats accepted\ntonepilot \"Text\" --respond yes\ntonepilot \"Text\" --respond 1 \ntonepilot \"Text\" --respond false\n```\n\n### Available Options\n\n- `--mode {hf,gemini}`: Choose the response generation model (default: hf)\n- `--respond {true,false,yes,no,1,0}`: Generate response or just prompt (default: false)\n\n## Python API\n\n```python\nfrom tonepilot.core.tonepilot import TonePilotEngine\n\n# Initialize engine\nengine = TonePilotEngine(mode='hf', respond=False)\n\n# Process text\nresult = engine.run(\"I'm nervous about my presentation tomorrow\")\n\nprint(\"Detected emotions:\", result['input_tags'])\nprint(\"Response emotions:\", result['response_tags'])\nprint(\"Generated prompt:\", result['final_prompt'])\n\n# For response generation (requires API key)\nengine_with_response = TonePilotEngine(mode='gemini', respond=True)\nresult = engine_with_response.run(\"I'm nervous about my presentation tomorrow\")\nprint(\"Generated response:\", result['response_text'])\n```\n\n## Architecture\n\nTonePilot uses a sophisticated multi-stage pipeline:\n\n1. **Emotion Detection**: Zero-shot classification using BART-large-MNLI\n2. **Tone Mapping**: BERT-based classifier maps input emotions to response personalities \n3. **Prompt Blending**: Combines personality traits with weighted importance\n4. **Response Generation**: Optional text generation using HuggingFace or Gemini models\n\n### Supported Emotions\n\n**Input Emotions**: curious, angry, sad, excited, confused, hopeful, tired, scared, playful, assertive\n\n**Response Personalities**: empathetic_listener, direct_ally, calming_supporter, practical_helper, and more\n\n## Model Downloads\n\nTonePilot uses a custom-trained BERT classifier for tone mapping. **The model is automatically downloaded on first use** - no manual installation required!\n\n### BERT Tone Classifier\n\n- **File**: `tonepilot_bert_classifier.pt` (475 MB)\n- **Download**: [GitHub Releases](https://github.com/sdurgi/tonepilot/releases/download/v0.1.0/tonepilot_bert_classifier.pt)\n- **Purpose**: Maps detected emotions to appropriate response personalities\n- **Training**: Custom-trained on emotional response datasets\n\n### Automatic Model Management\n\nTonePilot automatically handles model downloads and caching:\n\n1. **First Run**: Downloads model to `~/.cache/tonepilot/` (one-time, ~475 MB)\n2. **Subsequent Runs**: Uses cached model for instant loading\n3. **Fallback Locations**: Also checks current directory and package directory\n\n**Manual Download** (if needed):\n```bash\n# Only needed if automatic download fails\nwget https://github.com/sdurgi/tonepilot/releases/download/v0.1.0/tonepilot_bert_classifier.pt -P ~/.cache/tonepilot/\n\n# Or place in current directory\ncurl -L -o tonepilot_bert_classifier.pt https://github.com/sdurgi/tonepilot/releases/download/v0.1.0/tonepilot_bert_classifier.pt\n```\n\n**Note**: Internet connection required only on first use for model download.\n\n## Examples\n\n### Different Emotional Contexts\n\n```bash\n# Sadness \u2192 Empathetic support\ntonepilot \"My dog passed away yesterday\"\n\n# Excitement \u2192 Enthusiastic encouragement \ntonepilot \"I just got accepted to my dream university!\"\n\n# Confusion \u2192 Clear guidance\ntonepilot \"I don't understand this math problem at all\"\n\n# Anger \u2192 Calming and validation\ntonepilot \"I'm so frustrated with this broken software!\"\n```\n\n### Integration Examples\n\n**Customer Support Bot:**\n```python\ndef handle_customer_message(message):\n engine = TonePilotEngine(mode='gemini', respond=True)\n result = engine.run(message)\n return result['response_text']\n```\n\n**Content Writing Assistant:**\n```python\ndef get_writing_prompt(topic, desired_tone):\n engine = TonePilotEngine(respond=False)\n result = engine.run(f\"Write about {topic} with a {desired_tone} tone\")\n return result['final_prompt']\n```\n\n## Requirements\n\n- Python 3.8+\n- PyTorch (automatically installed)\n- Transformers library (automatically installed)\n- Internet connection for model downloads on first use\n\n**Optional for response generation:**\n- Google API key (for Gemini mode)\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/sdurgi/tonepilot.git\ncd tonepilot\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack tonepilot/\n```\n\n## Performance\n\n- **Emotion Detection**: ~50ms on CPU\n- **Response Generation**: 1-3 seconds (depending on model and length)\n- **Memory Usage**: ~500MB (includes cached models)\n- **Model Downloads**: ~1GB on first run (cached locally)\n\n## Troubleshooting\n\n**Import Errors**: Ensure all dependencies are installed with `pip install tonepilot`\n\n**API Key Issues**: Verify your `.env` file or environment variables are set correctly\n\n**Model Download Failures**: Check internet connection; models download automatically on first use\n\n**Memory Issues**: Use smaller models or increase available memory\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\n```bibtex\n@software{tonepilot2024,\n title={TonePilot: Emotional Intelligence for Text Generation},\n author={Durgi, Srivani},\n year={2024},\n url={https://github.com/sdurgi/tonepilot}\n}\n```\n\n## Support\n\n- \ud83d\udce7 Email: sdurgi21@gmail.com\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/sdurgi/tonepilot/issues)\n\n---\n\n**Made with \u2764\ufe0f for building emotionally intelligent AI systems**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Emotional intelligence for text generation - detect emotional tones and generate contextually appropriate responses",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/sdurgi/tonepilot/issues",
"Repository": "https://github.com/sdurgi/tonepilot"
},
"split_keywords": [
"emotion",
" nlp",
" ai",
" text-generation",
" emotional-intelligence",
" sentiment-analysis",
" transformers"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e047db01e1698f7dac7b42a494366be7fca7cb81371023898d72679f87ca46ab",
"md5": "16497c2ebf177b719c43967b4989601c",
"sha256": "cb224959d7d7b334497ddeedc18c74daae587f3e6cffc903f1f968eff5b0b41b"
},
"downloads": -1,
"filename": "tonepilot-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16497c2ebf177b719c43967b4989601c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26451,
"upload_time": "2025-07-10T12:12:17",
"upload_time_iso_8601": "2025-07-10T12:12:17.609570Z",
"url": "https://files.pythonhosted.org/packages/e0/47/db01e1698f7dac7b42a494366be7fca7cb81371023898d72679f87ca46ab/tonepilot-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "601c929856cdd5b4d899fdf2b9a4d572aec0cc6c38fed35b54c39802be106e9b",
"md5": "22d1c04a8a7083c4722297d1829e3f51",
"sha256": "6b50ef0d658137a6dd12d8480d739cf57afa06d8fc66006f02373dd9cc3ce4f3"
},
"downloads": -1,
"filename": "tonepilot-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "22d1c04a8a7083c4722297d1829e3f51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23693,
"upload_time": "2025-07-10T12:12:18",
"upload_time_iso_8601": "2025-07-10T12:12:18.837366Z",
"url": "https://files.pythonhosted.org/packages/60/1c/929856cdd5b4d899fdf2b9a4d572aec0cc6c38fed35b54c39802be106e9b/tonepilot-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 12:12:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sdurgi",
"github_project": "tonepilot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tonepilot"
}
JSON
