{"id":28229502,"url":"https://github.com/abenezeradane/bodyguard","last_synced_at":"2026-01-31T21:39:27.818Z","repository":{"id":293890879,"uuid":"985425171","full_name":"abenezeradane/bodyguard","owner":"abenezeradane","description":"Cyberbulling Detection System","archived":false,"fork":false,"pushed_at":"2025-12-05T06:59:04.000Z","size":25041,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-08T14:42:49.109Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abenezeradane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-17T18:28:31.000Z","updated_at":"2025-12-05T06:59:08.000Z","dependencies_parsed_at":"2025-06-23T18:40:15.565Z","dependency_job_id":"3464455c-04ff-49b3-b1b1-9e2c42178b94","html_url":"https://github.com/abenezeradane/bodyguard","commit_stats":null,"previous_names":["abenezeradane/bodyguard"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/abenezeradane/bodyguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abenezeradane%2Fbodyguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abenezeradane%2Fbodyguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abenezeradane%2Fbodyguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abenezeradane%2Fbodyguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abenezeradane","download_url":"https://codeload.github.com/abenezeradane/bodyguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abenezeradane%2Fbodyguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28956443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T18:30:42.805Z","status":"ssl_error","status_checked_at":"2026-01-31T18:30:19.593Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-18T16:10:30.307Z","updated_at":"2026-01-31T21:39:27.811Z","avatar_url":"https://github.com/abenezeradane.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bodyguard\n\u003e **Cyberbullying Detection System (Advocacy Project)**\n\nThis project aims to reduce cyberbullying on social media platforms by detecting harmful content in real-time using Natural Language Processing (NLP) and machine learning. The focus is on text-based tweets, analyzed through a browser extension and a backend ML service.\n\n## Objective\n\nDesign and deploy a system that:\n\n- Detects potential cyberbullying in tweets.\n- Flags tweets with warnings in the user interface.\n- Stores flagged data for analysis and improvement.\n\n## Project Plan\n\n### Month 1 – Research, Planning, and Data Collection\n\n**Weeks 1-2:**\n\n- Research cyberbullying definitions and patterns.\n- Study prior ML approaches in NLP tasks (text classification, sentiment analysis).\n\n**Week 3:**\n\n- Define scope: Detect offensive content in Twitter text.\n- Choose models (e.g., BERT, RoBERTa).\n- Set up Python, Transformers, TensorFlow/PyTorch.\n\n**Week 4:**\n\n- Collect datasets (Twitter Sentiment, Hateful Memes, etc.).\n- Preprocess and annotate the text data.\n\n### Month 2 – Development, Testing, and Deployment\n\n**Week 1:**\n\n- Build a rule-based prototype using keyword matching/sentiment scoring.\n\n**Weeks 2–3:**\n\n- Fine-tune a transformer-based classifier (e.g., RoBERTa).\n- Compare models and tune hyperparameters.\n- Create a frontend overlay for flagged tweets.\n\n**Week 4:**\n\n- Evaluate the model (precision, recall, F1-score).\n- Integrate feedback and finalize the system.\n\n## Tech Stack\n\n- **Frontend:** Browser Extension (Vanilla JS, DOM API)\n- **Backend:** FastAPI, PostgreSQL, Docker\n- **ML:** Transformers (RoBERTa), PyTorch\n- **Deployment:** Docker Compose\n\n## Architecture Overview\n\n### Sequence Diagram\n\n```mermaid\nsequenceDiagram\n    participant U as User on Twitter\n    participant C as Content Script\n    participant B as Background Script\n    participant A as API Server (FastAPI)\n    participant M as ML Model\n    participant D as Database\n\n    U -\u003e\u003e C: Tweet appears in DOM\n    C -\u003e\u003e B: Send tweet text, author, ID\n    B -\u003e\u003e A: POST /predict (text)\n    activate A\n    A -\u003e\u003e M: Run classification\n    M --\u003e\u003e A: Return label\n    A --\u003e\u003e B: Return classification result\n    deactivate A\n    B -\u003e\u003e D: POST /store (tweet + label)\n    B --\u003e\u003e C: Return label\n    C -\u003e\u003e U: Show \"⚠️ Possible Cyberbullying\" overlay (if flagged)\n```\n\n### Component Diagram\n\n```mermaid\ngraph TD\n    A[Browser Extension]\n    B[FastAPI Backend]\n    C[RoBERTa Model]\n    D[PostgreSQL Database]\n\n    A --\u003e|/predict| B\n    B --\u003e|Inference| C\n    B --\u003e|Log tweet| D\n    A \u003c--\u003e|Display results| B\n```\n\n## Model Training\n\n- **Dataset**: Preprocessed Twitter-like text, binary labels.\n- **Model**: `roberta-base` fine-tuned with class weights for imbalance.\n- **Metrics**: Accuracy, F1-score.\n- **Output**: Saved model artifacts and tokenizer for inference.\n\n## Evaluation\n\n- Weighted loss used to handle class imbalance.\n- F1-score prioritized to minimize false negatives.\n- Model deployed behind a FastAPI endpoint `/predict`.\n\n## Privacy \u0026 Ethics\n\n- Does **not** store any personally identifiable information (PII).\n- Data is stored locally/internally and not shared externally.\n- Intended as an advocacy/proof-of-concept tool only.\n\n## Deployment\n\n1. **Clone** the repository.\n2. **Train the model**:\n    - Preferred: Run `engine/core/train.ipynb` (interactive).\n    - Alternative: Install dependencies from `engine/core/requirements.txt` and run `engine/core/train.py`.\n3. **Set up** `.env` with your PostgreSQL credentials.\n4. **Set up** `engine/core/config.yaml` with config\n    ```yaml\n    server:\n        port: 8080\n    \n    database:\n        username: [FILL OUT]\n        password: [FILL OUT]\n        name: bodyguarddb\n        port: 5432\n    ```  \n5. **Run the backend**:\n    ```bash\n    docker-compose up --build\n    ```\n6. **Install the browser extension**:\n    - Download from the [Releases](https://github.com/your-username/bodyguard/releases).\n    - **Chrome**: Drag `.crx` file into `chrome://extensions` with Developer Mode enabled.\n    - **Firefox**: Go to `about:addons` → gear icon → *Install Add-on From File...* and select `.xpi`.\n7. **Browse Twitter**:\n    - Tweets flagged as cyberbullying will be masked with a warning banner and a toggle button.\n\n## API Reference\n\n### POST `/predict`\n\n**Request:**\n\n```json\n{\n    \"text\": \"You are so stupid and ugly\"\n}\n```\n\n**Response:**\n\n```json\n{\n    \"label\": {\n        \"label\": \"cyberbullying\",\n        \"confidence\": 0.999\n    }\n}\n```\n\n---\n\n### POST `/store`\n\n**Request:**\n\n```json\n{\n    \"id\": \"123456\",\n    \"author\": \"@user\",\n    \"text\": \"example tweet\",\n    \"label\": \"cyberbullying\"\n}\n```\n\n**Response:**\n\n```json\n{\n    \"status\": \"stored\"\n}\n```\n\n---\n\n## Known Shortcomings\n\n- **False Negatives**: Some subtle bullying may not be flagged (e.g., sarcasm).\n- **False Positives**: Some innocuous tweets may be incorrectly flagged.\n- **Low Training Samples**: Especially for nuanced or niche forms of cyberbullying.\n- **No Context Awareness**: Lacks thread-level or user history context.\n\n---\n\n## Project Structure\n\n```plaintext\n.\n├── extension/              # Browser extension files\n├── engine/\n│   ├── app.py              # FastAPI server\n│   ├── config.yaml         # Configs for DB and server\n│   ├── predict.py          # Inference logic\n│   ├── model/              # Saved model + tokenizer\n│   ├── data/               # Processed dataset\n│   ├── train.ipynb         # Training script (Jupyter Notebook)\n│   └── train.py            # Training script\n├── docker-compose.yml\n```\n\n## Future Improvements\n\n- Add image and video support.\n- Add multilingual support.\n- Real-time moderation dashboard.\n- User feedback integration loop for false positives/negatives.\n\n## Acknowledgements\n\n- HuggingFace Transformers\n- OLID (Offensive Language Identification Dataset)\n- Jigsaw (Toxic Comment Classification Challenge)\n- Open-source contributors working on online safety and NLP\n\n---\n\n**Author:** Abenezer Adane  \n**Version:** 1.0 – Advocacy Proof-of-Concept  \n**License:** This project is for educational and advocacy purposes. Use responsibly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabenezeradane%2Fbodyguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabenezeradane%2Fbodyguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabenezeradane%2Fbodyguard/lists"}