README.md

---
title: 🕉 KarmaCheck - Spiritual Guidance & MCP Server
emoji: 🕉
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.33.1
app_file: app.py
pinned: true
license: mit
short_description: Universal wisdom AI with MCP server
tags:
- mcp-server-track
- spiritual-guidance
- ancient-wisdom
- life-coaching
- ethical-guidance
- track-1
- mcp-server
- llamaindex
- rag
video_overview: https://youtu.be/4XG0SDb7BTw
collection: https://huggingface.co/collections/Agents-MCP-Hackathon
---
# 🕉️ KarmaCheck - Spiritual Guidance with MCP Server

KarmaCheck is an AI-powered spiritual assistant that provides guidance based on ancient Vedic wisdom. It combines Retrieval-Augmented Generation (RAG) with Vedic scriptures to offer meaningful insights for modern life challenges.

## ✨ Features

- 🔮 **Spiritual Guidance**: Get personalized advice based on Vedic principles
- 📚 **Sacred Texts**: Draws from Bhagavad Gita, Upanishads, and dharmic teachings
- 🤖 **MCP Server**: Integrate with Claude Desktop for seamless AI interactions
- 🌟 **Daily Wisdom**: Receive daily spiritual insights
- ⚖️ **Ethical Analysis**: Analyze dilemmas using dharmic principles
- 🎯 **Concept Explanation**: Understand spiritual concepts deeply

## 🚀 Quick Start

### 1. Installation

```bash
# Clone or download the project
git clone <your-repo-url>
cd karmacheck

# Install dependencies
pip install -r requirements.txt
```

### 2. Get Hugging Face API Token

1. Go to [Hugging Face Settings](https://huggingface.co/settings/tokens)
2. Create a new token (read access is sufficient)
3. Copy the token

### 3. Configuration

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env and add your token
HUGGINGFACE_API_TOKEN=your_actual_token_here
```

### 4. Run the Application

```bash
python karma_check.py
```

The app will be available at:
- 🌐 **Web UI**: http://localhost:7860
- 🔧 **MCP Server**: Same address for Claude Desktop

## 🤖 Claude Desktop Integration

### Setup Steps:

1. **Install Claude Desktop** (if not already installed)

2. **Configure MCP Server**:
   
   Add this to your Claude Desktop MCP configuration:

   ```json
   {
     "mcpServers": {
       "karmacheck": {
         "command": "python",
         "args": ["/absolute/path/to/karma_check.py"],
         "env": {
           "HUGGINGFACE_API_TOKEN": "your_hf_token_here"
         }
       }
     }
   }
   ```

3. **Update the path**: Replace `/absolute/path/to/karma_check.py` with the actual path to your file

4. **Restart Claude Desktop**

### Available MCP Tools:

- `get_spiritual_guidance(question)` - Main spiritual guidance function
- `find_vedic_quotes(topic)` - Find quotes on specific topics
- `explain_concept(concept)` - Explain spiritual concepts
- `daily_wisdom()` - Get daily spiritual insight
- `analyze_dilemma(situation)` - Analyze ethical dilemmas

### Example Usage in Claude:

```
User: Use KarmaCheck to help me understand karma
Claude: I'll use the KarmaCheck tool to explain karma for you.

[Uses explain_concept("karma")]

Based on Vedic teachings, karma refers to...
```

## 📚 Data Sources

The system comes with sample Vedic texts including:
- Bhagavad Gita verses and commentary
- Upanishad teachings
- Dharmic principles and guidance

### Adding Your Own Texts:

1. Create text files in the `data/` directory
2. Include verses, commentary, and context
3. Restart the application to rebuild the index

## 🛠️ Technical Details

- **RAG System**: LlamaIndex with FAISS vector store
- **Embeddings**: Hugging Face `all-MiniLM-L6-v2`
- **LLM**: Mistral-7B-Instruct via Hugging Face Inference API
- **UI**: Gradio with MCP server support
- **Vector Storage**: Local FAISS index with persistence

## 🔧 Customization

### Model Configuration:

Edit the configuration in `karma_check.py`:

```python
@dataclass
class KarmaCheckConfig:
    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
    llm_model: str = "mistralai/Mistral-7B-Instruct-v0.1"
    chunk_size: int = 512
    similarity_top_k: int = 5
    # ... other settings
```

### Adding New MCP Tools:

```python
@gr.mcp_tool()
def your_new_tool(parameter: str) -> str:
    """Description of your tool for MCP clients"""
    # Your implementation
    return result
```

## 📖 Example Questions

### Life & Purpose:
- "How can I find my life's true purpose?"
- "I feel lost in my career. What should I do?"
- "How do I know if I'm following my dharma?"

### Relationships:
- "How should I handle conflicts with family?"
- "What does love mean spiritually?"
- "How can I forgive someone who hurt me?"

### Personal Growth:
- "How do I overcome anxiety?"
- "What is the spiritual meaning of suffering?"
- "How can I develop inner peace?"

### Ethics:
- "I'm facing an ethical dilemma at work"
- "How do I balance personal desires with duty?"
- "What does righteous living mean today?"

## 🐛 Troubleshooting

### Common Issues:

1. **Token Error**: Make sure `HUGGINGFACE_API_TOKEN` is set correctly
2. **Model Loading**: Hugging Face models may take time to load initially
3. **Dependencies**: Ensure all packages are installed: `pip install -r requirements.txt`
4. **Claude Desktop**: Use absolute file paths in MCP configuration

### Getting Help:

- Check the console output for detailed error messages
- Ensure stable internet connection for Hugging Face API
- Verify Python version (3.8+ recommended)

## 🙏 Contributing

Contributions are welcome! Areas for improvement:
- Additional Vedic texts and translations
- Enhanced spiritual analysis features
- Better multilingual support
- Advanced meditation and practice recommendations

## 📜 License

This project is open source. Use it for personal growth and spiritual development.

## 🕉️ Acknowledgments

- Ancient Vedic sages for their timeless wisdom
- Hugging Face for democratizing AI
- Gradio team for excellent tooling
- LlamaIndex for powerful RAG capabilities

---

*"यदा यदा हि धर्मस्य ग्लानिर्भवति भारत। अभ्युत्थानमधर्मस्य तदात्मानं सृजाम्यहम्॥"*

*"Whenever there is a decline in righteousness and an increase in unrighteousness, I manifest myself."* - Bhagavad Gita 4.7

#### 🌟 May this tool serve your spiritual journey with wisdom and compassion.