Self-Compassion AI™ LLM for Neurodiverse Brains ❥ 🧠

✨ Introduction

• Research shows that individuals with neurodiverse conditions (e.g., ADHD, autism) often struggle with self-compassion (Beaton et al., 2002). Everyday reminders to be kind to oneself can be cognitively demanding and difficult to sustain, especially during stressful situations or when executive function is taxed. This project addresses that gap by offering a lightweight and accessible tool to make self-compassion easier and less effortful. Drawing from leading evidence-based research, this app provides a structured and easy way to practice kindness toward oneself ❥.
  
  

---

💕 Live Demo

• Try out the deployed app (no setup required!) 👉🏻

videowalkthrough.webm

---

💡 Features

• Science-based: built using leading empirical research and science on neurodiversity and self-compassion.

• Interactive Web Interface: easy-to-use Streamlit app with fast, instant responses (press 'Enter' or click 'Answer').

  

• Smart Search Options: choose between hybrid, BM25, or vector retrieval to find the most relevant guidance.

  

• Personalized Experience (LLM Evaluation): select from 3 prompt styles based on your moods and needs-- 💕 Supportive, 📚 Direct, or 💪🏻 Action-Oriented!

  

Prompt Style	Purpose	Example Response Tone
💕 Supportive	Compassionate, reflective guidance	"It's completely understandable that you're feeling this way..."
📚 Direct	Concise, factual information	"Here are three evidence-based strategies for..."
💪🏻 Action-Oriented	Practical steps and exercises	"Try this 5-minute exercise: First, notice..."

• Advanced Customization: adjust search depth (top-k results), LLM creativity (temperature), and choose between GPT models (gpt-4o-mini or gpt-3.5-turbo).

• Enhanced Retrieval: optional query expansion and document re-ranking for better, more relevant results.

• Built-in Analytics: Real-time feedback collection and monitoring dashboards to track usage and effectiveness.

---

🛠️ Environment & Configuration

• Python version: Python 3.11+ recommended
• Environment variables:
  • OPENAI_API_KEY (required for LLM features; set in a .env file or your environment).
    
    

---

🚀 Quickstart (clone and run locally)

• Clone the repo and install dependencies:

  git clone https://github.com/<your-username>/selfcompassion-llm.git
  cd selfcompassion-llm
  pip install -r requirements.txt

• Run ingestion to build the index:

  python ingestion.py

• Launch the Streamlit app:

  streamlit run streamlit_app.py

🛥 Alternative: Docker Setup

• Set up API key. Create a .env file in project root:

  OPENAI_API_KEY=your_actual_api_key_here

• Run docker:

  docker-compose up -- build

• Access at http://localhost:8503
  
  

---

📂 Project Structure

selfcompassion-llm/
├── streamlit_app.py        # main Streamlit app
├── ingestion.py            # build FAISS/embedding index
├── monitor.py              # simple monitoring dashboard
├── docker-compose.yml      # docker setup
├── Dockerfile
├── Makefile                # developer shortcuts 
├── processed_documents_clean.json  # demo dataset
├── requirements.txt
├── images                  # images folder
└── notebooks/              # exploration notebook with example code

---

🏠 System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERFACE                               │
│                     Streamlit Web App                               │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
│  │   Query     │  │   Settings  │  │  Feedback   │                  │
│  │   Input     │  │   Panel     │  │   Radio     │                  │
│  └─────────────┘  └─────────────┘  └─────────────┘                  │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      QUERY PROCESSING                               │
│                                                                     │
│  ┌─────────────┐         ┌─────────────┐                            │
│  │   Query     │────────▶│  Original   │                            │
│  │ Rewriting   │         │   Query     │                            │ 
│  └─────────────┘         └─────────────┘                            │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    RETRIEVAL LAYER                                  │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
│  │    BM25     │  │   Vector    │  │   Hybrid    │                  │
│  │   Search    │  │   Search    │  │   Search    │                  │
│  └─────────────┘  └─────────────┘  └─────────────┘                  │
│                               │                                     │
│                               ▼                                     │
│                   ┌─────────────────┐                               │
│                   │   Document      │                               │
│                   │  Re-ranking     │                               │
│                   └─────────────────┘                               │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   KNOWLEDGE BASE                                    │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
│  │ Documents   │  │ Embeddings  │  │ BM25 Index  │                  │
│  │    JSON     │  │    .npy     │  │   Memory    │                  │
│  └─────────────┘  └─────────────┘  └─────────────┘                  │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    LLM GENERATION                                   │
│                                                                     │
│  ┌─────────────┐         ┌─────────────┐                            │
│  │   OpenAI    │◀────────│   Prompt    │                            │
│  │  gpt-4o-mini│         │ Engineering │                            │
│  └─────────────┘         └─────────────┘                            │
│                               │                                     │
│  ┌─────────────┐              │                                     │
│  │   3 Prompt  │◀─────────────┘                                     │
│  │   Styles    │                                                    │
│  └─────────────┘                                                    │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   MONITORING & LOGGING                              │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
│  │  Event Log  │  │ Feedback    │  │ Dashboard   │                  │
│  │   JSONL     │  │ Collection  │  │  Charts     │                  │
│  └─────────────┘  └─────────────┘  └─────────────┘                  │
└─────────────────────────────────────────────────────────────────────┘

🔄 Data Flow

1. User Input → Query entered in Streamlit interface
2. Query Processing → Optional rewriting with domain terms
3. Retrieval → Multiple search methods (BM25/Vector/Hybrid)
4. Re-ranking → Document relevance scoring
5. Context Building → Top documents formatted for LLM
6. Generation → OpenAI API with custom prompts
7. Response → Answer + sources displayed to user
8. Monitoring → Events logged for analytics
   
   

---

📊 Monitoring

• Run it with:

  streamlit run monitor.py

• A separate monitoring page (monitor.py) tracks:
  • Sources per answer
  • Feedback breakdown
  • Query rewriting usage

---

✅ Evaluation Results

🚘 Running Evaluation

python evaluation.py

• App is deployed and running here.
• The Self-Compassion RAG system was evaluated on a golden dataset of 20 queries with labeled relevant documents. It tests the RAG system against the golden dataset.

---

💪🏻 Performance Metrics

Retrieval Method	Hit Rate	MRR	Precision@10	Recall@10
BM25	1.000	0.598	0.100	1.000
Vector	0.900	0.410	0.090	0.900
TF-IDF	0.900	0.410	0.090	0.900
Hybrid	0.950	0.520	0.095	0.950

🎯 LLM Evaluation Summary

Multiple prompt styles tested and compared:

• 💕 Supportive, 📚 Direct, 💪🏻 Action-Oriented prompts
• Each optimized for different query types
• User feedback collected to assess effectiveness

Multiple models evaluated:

• gpt-4o-mini (primary) vs gpt-3.5-turbo
• Performance tested across all retrieval methods

---

💡 Key Findings

• BM25 consistently achieves perfect hit rate and recall in this dataset, with the best MRR (0.598), ranking relevant documents higher.
• Hybrid slightly improves over pure TF-IDF and Vector, balancing precision and recall.
• Vector and TF-IDF show similar performance, with lower MRR than BM25 but decent recall.
• BM25 emerges as the most reliable retriever under current conditions, though Hybrid provides a good balance.

---

⚡ Data & Reproducibility

• Deterministic ingestion pipeline (ingestion.py)

• requirements.txt provided for environment setup

• Docker + docker-compose included for containerized runs

• Repo includes a small demo dataset (processed_documents_clean.json) to immediately run the app and test its functionality.

• To rebuild the larger embedding index files locally, run:

  make ingest

  or

  python ingestion.py

---

📘 Development Notes

• Exploration notebooks are under /notebooks/.
• Embeddings (embeddings.npy, id_index.json) are ignored from git.
• Feedback data is stored locally (not shared).

📄 Data Sources

• All data sources are carefully curated from peer-reviewed research, legally purchased books (excerpts only, fair use), and publicly available expert materials (e.g., podcast transcripts).
• Full PDF sources are maintained in a separate private repository for copyright compliance.

---

📝 Disclaimer

• All responses are anonymous — nothing is saved, logged, or tracked by the app.
• This app does not store, share, or distribute full PDFs or copyrighted materials. All content is based on short excerpts, summaries, or personal notes, either from books I’ve legally purchased or from publily available sources (e.g., peer-reviewed articles, podcast transcripts).
• This app is intended for educational and personal use only. It is not intended to diagnose, treat, cure, or prevent any mental health condition. If you are in emotional distress or experiencing a crisis, please contact a licensed mental health professional.

---

❥ Thank you so much for using the app-- I hope you find it useful! May we all be kind to ourselves! 💕🙏🏻

• This project is licensed under the MIT License