Metadata-Version: 2.4
Name: mentalsaathi-ai
Version: 0.2.2
Summary: LangChain-based AI engine for mental health support conversations
Author-email: Rhydham Mittal <rhydham937@gmail.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: langchain-core
Requires-Dist: langchain-google-genai
Requires-Dist: python-dotenv
Requires-Dist: pydantic

# MentalSaathi AI

The AI engine powering [MentalSaathi](https://www.mentalsaathi.in) — an emotional support platform for Indian college students.

Handles the full conversation pipeline: emotion analysis, crisis detection, and human-sounding response generation — in Hinglish or English, whichever the student writes in.

---

## How it works

Three LLM calls per message, in sequence:

```
Student message
      │
      ▼
Stage 1 — FullAnalysisChain
  Detects emotion, intensity, surface vs deep pain, root cause
      │
      ▼
Stage 2 — CrisisDetectionChain
  Safety gate: is this student in crisis right now?
  ├─ YES → CrisisCheck (crisis response + helplines)
  └─ NO  ──────────────────────────────────────────┐
                                                    ▼
                                         Stage 3 — ResponseGenerationChain
                                           Warm, specific reply + grounding anchor
                                                    │
                                                    ▼
                                              ReliefResponse
```

---

## Installation

```bash
pip install mentalsaathi-ai
```

Requires Python 3.11+. Set your Gemini API key before using:

```env
# .env
GOOGLE_API_KEY=your_google_api_key
GEMINI_MODEL=gemini-2.5-flash-lite   # optional, this is the default
```

---

## Quickstart

### One function

```python
from mentalsaathi_ai import run

result = run("yaar bahut stressed hoon, result bahut bura aaya")
print(result)        # the message the student will read
print(result.anchor) # grounding suggestion specific to their situation
```

### With conversation history

```python
result = run(
    student_message="haa koi solution hai kya?",
    conversation_context="Student: result bahut bura aaya\nTalkSaathi: Itni mehnat ke baad...",
)
```

### Pipeline object

```python
from mentalsaathi_ai import mentalsaathi_chain

result = mentalsaathi_chain("I don't see the point of studying anymore")
print(len(mentalsaathi_chain))  # 3  (number of LLM calls)
```

---

## Return types

```python
from mentalsaathi_ai.schemas import ReliefResponse, CrisisCheck

# Normal path
result.response   # str — the message to show the student
result.anchor     # str — one small grounding action, specific to their situation

# Crisis path
result.crisis_response  # str — warm, direct crisis message
result.resources        # list of helplines (iCall, AASRA, Vandrevala, etc.)

# Distinguish them
bool(result)  # True → ReliefResponse, False → CrisisCheck
str(result)   # student-facing text in both cases
```

---

## Terminal chat (dev)

```bash
python -m mentalsaathi_ai.chains
```

Colored terminal interface with conversation memory. Type `clear` to reset history, `quit` to exit.

---

## Package structure

```
mentalsaathi_ai/
├── __init__.py                  # top-level API: run(), mentalsaathi_chain
├── core/settings.py             # env var config (GEMINI_MODEL, GOOGLE_API_KEY)
├── llms/llm.py                  # LLMFactory + brain singleton
├── schemas/                     # Pydantic v2 output schemas
├── prompts/
│   ├── loader.py                # loads .txt templates from disk
│   └── templates/               # all prompt templates as .txt files
├── chains/
│   ├── base_chain.py            # abstract BaseChain with dunders
│   ├── full_analysis_chain.py
│   ├── crisis_detection_chain.py
│   ├── response_generation_chain.py
│   └── mentalsaathi_chain.py    # orchestrates all three
└── agent/risk_detection.py      # standalone risk scoring agent
```

---

## Configuration

| Variable | Default | Description |
|---|---|---|
| `GOOGLE_API_KEY` | — | Required. Your Gemini API key |
| `GEMINI_MODEL` | `gemini-2.5-flash-lite` | Any Gemini chat model |

---

## Running tests

```bash
pip install mentalsaathi-ai pytest
pytest testing/unit testing/chain   # 105 tests, no API calls needed
pytest testing/integration          # real LLM calls, needs GOOGLE_API_KEY
```

---

## Dependencies

| Package | Purpose |
|---|---|
| `langchain-core` | LCEL chain and prompt abstractions |
| `langchain-google-genai` | Gemini LLM integration |
| `pydantic` | Structured output validation |
| `python-dotenv` | `.env` loading |

---

## License

MIT © 2026 Rhydham Mittal
