mentalsaathi-ai 0.1.0__tar.gz

mentalsaathi_ai-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: mentalsaathi-ai
+Version: 0.1.0
+Summary: LangChain-based AI engine for mental health support conversations
+Author-email: Rhydham Mittal <manjeetsinghdangi786@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
+Provides-Extra: groq
+Requires-Dist: langchain-groq; extra == "groq"
+
+# 🌿 MentalSaathi AI Engine
+
+The AI backbone of [Mental Saathi](https://www.mentalsaathi.in) — a mental health platform built for Indian college students. This package handles risk detection, LLM chains, prompt management, and agent orchestration.
+
+---
+
+## Features
+
+- **Risk Detection Agent** — analyses user-submitted text and returns a structured risk assessment (`risk_score`, `risk_level`, `summary`)
+- **LangChain-powered chains** — modular, composable chains built on `langchain-core`
+- **Groq LLM integration** — fast inference via `langchain-groq`
+- **Pydantic output schemas** — structured, validated responses from every chain
+- **Pluggable prompt system** — prompts and parsers are decoupled and easy to swap
+
+---
+
+## Project Structure
+
+```
+mentalsaathi.backend/ai/
+├── agent/               # High-level agents (entry points)
+│   └── risk_detection.py
+├── chains/              # LangChain chains
+│   └── calculate_risk.py
+├── core/                # App settings & config
+│   └── settings.py
+├── llms/                # LLM instantiation
+│   └── llm.py
+├── prompts/             # Prompt templates & parsers
+│   └── risk.py
+└── schemas/             # Pydantic output schemas
+    └── risk.py
+```
+
+---
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+# Clone the repo
+git clone https://github.com/your-org/mentalsaathi.git
+cd mentalsaathi.backend
+
+# Install the AI package in editable mode
+pip install -e ".[dev]"
+```
+
+---
+
+## Configuration
+
+Create a `.env` file in `mentalsaathi.backend/`:
+
+```env
+GROQ_API_KEY=your_groq_api_key
+GROQ_MODEL=llama3-8b-8192
+```
+
+All settings are loaded via `ai.core.Settings` (Pydantic `BaseSettings`).
+
+---
+
+## Usage
+
+### Risk Detection
+
+```python
+from ai.agent import risk_agent
+
+result = risk_agent.invoke({"user_input": "I've been feeling really hopeless lately..."})
+
+print(result.risk_level)   # e.g. "HIGH"
+print(result.risk_score)   # e.g. 78
+print(result.summary)      # e.g. "User expresses signs of hopelessness..."
+```
+
+### Risk Levels
+
+| Level      | Description                              |
+|------------|------------------------------------------|
+| `MINIMAL`  | No significant distress detected         |
+| `LOW`      | Mild emotional difficulty                |
+| `MODERATE` | Noticeable distress, worth monitoring    |
+| `HIGH`     | Significant risk, prompt attention needed|
+| `CRITICAL` | Immediate intervention recommended       |
+
+---
+
+## Dependencies
+
+Key packages used:
+
+| Package              | Purpose                        |
+|----------------------|--------------------------------|
+| `langchain-core`     | Chain & prompt abstractions    |
+| `langchain-groq`     | Groq LLM integration           |
+| `pydantic`           | Output schema validation       |
+| `python-dotenv`      | Environment variable loading   |
+| `rich`               | Pretty console output          |
+| `langsmith`          | Tracing & observability        |
+
+Full list in [`pyproject.toml`](./pyproject.toml).
+
+---
+
+## Development
+
+```bash
+# Run a quick smoke test on the risk agent
+python -c "from ai.agent import risk_agent; print(risk_agent.invoke({'user_input': 'test'}))"
+```
+
+Make sure the package is installed from the repo root so absolute imports (`from ai.x import ...`) resolve correctly.
+
+---
+
+## License
+
+MIT © 2026 Mental Saathi

mentalsaathi_ai-0.1.0/README.md

@@ -0,0 +1,121 @@
+# 🌿 MentalSaathi AI Engine
+
+The AI backbone of [Mental Saathi](https://www.mentalsaathi.in) — a mental health platform built for Indian college students. This package handles risk detection, LLM chains, prompt management, and agent orchestration.
+
+---
+
+## Features
+
+- **Risk Detection Agent** — analyses user-submitted text and returns a structured risk assessment (`risk_score`, `risk_level`, `summary`)
+- **LangChain-powered chains** — modular, composable chains built on `langchain-core`
+- **Groq LLM integration** — fast inference via `langchain-groq`
+- **Pydantic output schemas** — structured, validated responses from every chain
+- **Pluggable prompt system** — prompts and parsers are decoupled and easy to swap
+
+---
+
+## Project Structure
+
+```
+mentalsaathi.backend/ai/
+├── agent/               # High-level agents (entry points)
+│   └── risk_detection.py
+├── chains/              # LangChain chains
+│   └── calculate_risk.py
+├── core/                # App settings & config
+│   └── settings.py
+├── llms/                # LLM instantiation
+│   └── llm.py
+├── prompts/             # Prompt templates & parsers
+│   └── risk.py
+└── schemas/             # Pydantic output schemas
+    └── risk.py
+```
+
+---
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+# Clone the repo
+git clone https://github.com/your-org/mentalsaathi.git
+cd mentalsaathi.backend
+
+# Install the AI package in editable mode
+pip install -e ".[dev]"
+```
+
+---
+
+## Configuration
+
+Create a `.env` file in `mentalsaathi.backend/`:
+
+```env
+GROQ_API_KEY=your_groq_api_key
+GROQ_MODEL=llama3-8b-8192
+```
+
+All settings are loaded via `ai.core.Settings` (Pydantic `BaseSettings`).
+
+---
+
+## Usage
+
+### Risk Detection
+
+```python
+from ai.agent import risk_agent
+
+result = risk_agent.invoke({"user_input": "I've been feeling really hopeless lately..."})
+
+print(result.risk_level)   # e.g. "HIGH"
+print(result.risk_score)   # e.g. 78
+print(result.summary)      # e.g. "User expresses signs of hopelessness..."
+```
+
+### Risk Levels
+
+| Level      | Description                              |
+|------------|------------------------------------------|
+| `MINIMAL`  | No significant distress detected         |
+| `LOW`      | Mild emotional difficulty                |
+| `MODERATE` | Noticeable distress, worth monitoring    |
+| `HIGH`     | Significant risk, prompt attention needed|
+| `CRITICAL` | Immediate intervention recommended       |
+
+---
+
+## Dependencies
+
+Key packages used:
+
+| Package              | Purpose                        |
+|----------------------|--------------------------------|
+| `langchain-core`     | Chain & prompt abstractions    |
+| `langchain-groq`     | Groq LLM integration           |
+| `pydantic`           | Output schema validation       |
+| `python-dotenv`      | Environment variable loading   |
+| `rich`               | Pretty console output          |
+| `langsmith`          | Tracing & observability        |
+
+Full list in [`pyproject.toml`](./pyproject.toml).
+
+---
+
+## Development
+
+```bash
+# Run a quick smoke test on the risk agent
+python -c "from ai.agent import risk_agent; print(risk_agent.invoke({'user_input': 'test'}))"
+```
+
+Make sure the package is installed from the repo root so absolute imports (`from ai.x import ...`) resolve correctly.
+
+---
+
+## License
+
+MIT © 2026 Mental Saathi

mentalsaathi_ai-0.1.0/mentalsaathi_ai/__init__.py

@@ -0,0 +1,128 @@
+"""MentalSaathi AI — emotional support pipeline for Indian university students.
+
+3-stage pipeline (3 LLM calls total):
+
+    Stage 1  FullAnalysisChain        emotion + depth perception + root cause
+    Stage 2  CrisisDetectionChain     safety gate — routes to crisis or response
+    Stage 3  ResponseGenerationChain  reframe + relief (non-crisis path only)
+
+Package layout::
+
+    mentalsaathi_ai/
+    ├── __init__.py         ← you are here — top-level API
+    ├── core/               ← Settings (env vars)
+    ├── llms/               ← LLMFactory + brain singleton
+    ├── schemas/            ← Pydantic output schemas (BasePipelineSchema hierarchy)
+    ├── prompts/            ← BasePrompt + loader + templates/*.txt
+    ├── chains/             ← BaseChain + all LCEL chain classes
+    ├── agent/              ← risk detection agent
+    └── memory/             ← conversation memory (in progress)
+
+Quickstart — one function::
+
+    from mentalsaathi_ai import run
+
+    result = run("mujhe neend nahi aa rahi aur ghar pe sab chup hain.")
+    print(result)           # the message the student will read (or crisis response)
+    print(bool(result))     # False if crisis (CrisisCheck._is_truthy), True otherwise
+
+Quickstart — pipeline object::
+
+    from mentalsaathi_ai import mentalsaathi_chain
+
+    result = mentalsaathi_chain("yaar bahut stressed hoon")
+    result = mentalsaathi_chain(
+        student_message="I don't see the point anymore",
+        conversation_context="earlier: student mentioned failing exams",
+    )
+
+    print(len(mentalsaathi_chain))   # 3  (number of LLM calls)
+    print(mentalsaathi_chain)        # MentalSaathiPipeline(3 LLM calls)
+
+Return types::
+
+    ReliefResponse  — normal path: .response (str), .anchor (str)
+    CrisisCheck     — crisis path: .crisis_response (str), .resources (list)
+
+    bool(result)    → True for ReliefResponse, False for CrisisCheck
+    str(result)     → the student-facing message text in both cases
+"""
+
+from mentalsaathi_ai.chains.mentalsaathi_chain import (
+    MentalSaathiPipeline,
+    mentalsaathi_chain,
+)
+from mentalsaathi_ai.schemas import (
+    BasePipelineSchema,
+    EmotionalDetection,
+    SurfaceVsDeep,
+    DeepPainEntry,
+    RootCauseExtraction,
+    FullAnalysis,
+    CrisisCheck,
+    CrisisResource,
+    Reframe,
+    ReliefResponse,
+    RiskToolOutput,
+)
+
+__version__ = "0.2.0"
+__author__ = "MentalSaathi"
+
+__all__ = [
+    # Version
+    "__version__",
+    "__author__",
+    # Top-level API
+    "run",
+    # Pipeline
+    "MentalSaathiPipeline",
+    "mentalsaathi_chain",
+    # Output schemas — normal path
+    "ReliefResponse",
+    # Output schemas — crisis path
+    "CrisisCheck",
+    "CrisisResource",
+    # Output schemas — intermediate (for type hints / testing)
+    "BasePipelineSchema",
+    "FullAnalysis",
+    "EmotionalDetection",
+    "SurfaceVsDeep",
+    "DeepPainEntry",
+    "RootCauseExtraction",
+    "Reframe",
+    "RiskToolOutput",
+]
+
+
+def run(
+    student_message: str,
+    conversation_context: str = "",
+) -> ReliefResponse | CrisisCheck:
+    """Run the full 3-stage pipeline on a student message.
+
+    Convenience wrapper around :data:`mentalsaathi_chain`. Synchronous.
+
+    Args:
+        student_message:      Raw text from the student (Hindi/English/Hinglish).
+        conversation_context: Recent conversation history as a plain string.
+                              Pass ``""`` or omit when there is no prior context.
+
+    Returns:
+        :class:`ReliefResponse` on the normal path — contains ``.response``
+        (the message to show the student) and ``.anchor`` (a grounded action).
+
+        :class:`CrisisCheck` when crisis signals are detected — contains
+        ``.crisis_response`` and ``.resources`` (helpline list). Always
+        evaluates to ``False`` in a boolean context so callers can branch::
+
+            result = run(msg)
+            if not result:          # crisis path
+                show_crisis_ui(result.crisis_response, result.resources)
+            else:                   # normal path
+                show_response(result.response)
+    """
+    return mentalsaathi_chain(
+        student_message=student_message,
+        conversation_context=conversation_context,
+    )

mentalsaathi_ai-0.1.0/mentalsaathi_ai/agent/__init__.py

@@ -0,0 +1,15 @@
+"""Agent utilities for the MentalSaathi AI package.
+
+Currently exposes the risk detection agent — a standalone chain that
+scores a student message for risk level independent of the main pipeline.
+
+Usage::
+
+    from mentalsaathi_ai.agent import risk_agent
+
+    result = risk_agent.invoke({"student_message": "..."})
+"""
+
+from mentalsaathi_ai.agent.risk_detection import risk_agent
+
+__all__ = ["risk_agent"]

mentalsaathi_ai-0.1.0/mentalsaathi_ai/agent/risk_detection.py

@@ -0,0 +1,3 @@
+from mentalsaathi_ai.chains.calculate_risk import risk_calculation_chains as risk_agent
+
+__all__ = ["risk_agent"]

mentalsaathi_ai-0.1.0/mentalsaathi_ai/chains/__init__.py

@@ -0,0 +1,81 @@
+"""LCEL chain classes and singleton instances for the MentalSaathi pipeline.
+
+Active 3-stage pipeline::
+
+    MentalSaathiPipeline
+    ├── Stage 1: FullAnalysisChain          (1 LLM call — emotion + depth + root cause)
+    ├── Stage 2: CrisisDetectionChain       (1 LLM call — safety gate)
+    └── Stage 3: ResponseGenerationChain    (1 LLM call — reframe + relief, non-crisis)
+
+All chain classes inherit :class:`BaseChain` which provides ``__call__``,
+``invoke``, ``__or__``, and ``__repr__`` uniformly.
+
+Quick usage::
+
+    from mentalsaathi_ai.chains import mentalsaathi_chain, MentalSaathiPipeline
+
+    result = mentalsaathi_chain("yaar bahut stressed hoon")
+    print(len(mentalsaathi_chain))   # 3
+    print(mentalsaathi_chain)        # MentalSaathiPipeline(3 LLM calls)
+
+Individual stage access (for testing or custom pipelines)::
+
+    from mentalsaathi_ai.chains import (
+        full_analysis_chain,
+        crisis_detection_chain,
+        response_generation_chain,
+    )
+
+    analysis = full_analysis_chain.invoke({"student_message": "...", "conversation_context_block": ""})
+
+Legacy chains (kept for reference — not used by the active pipeline)::
+
+    from mentalsaathi_ai.chains import (
+        emotional_tone_detection_chain,
+        depth_perception_chain,
+        root_cause_extraction_chain,
+        reframing_chain,
+        relief_response_chain,
+        risk_agent,
+    )
+"""
+
+from mentalsaathi_ai.chains.base_chain import BaseChain
+
+# Active pipeline — primary entry points
+from mentalsaathi_ai.chains.mentalsaathi_chain import MentalSaathiPipeline, mentalsaathi_chain
+
+# Active individual stages
+from mentalsaathi_ai.chains.full_analysis_chain import FullAnalysisChain, full_analysis_chain
+from mentalsaathi_ai.chains.crisis_detection_chain import CrisisDetectionChain, crisis_detection_chain
+from mentalsaathi_ai.chains.response_generation_chain import ResponseGenerationChain, response_generation_chain
+
+# Legacy individual stages (pre-merge, not active in pipeline)
+from mentalsaathi_ai.chains.emotional_tone_detection import emotional_tone_detection_chain
+from mentalsaathi_ai.chains.depth_perception_chain import depth_perception_chain
+from mentalsaathi_ai.chains.root_cause_extraction_chain import root_cause_extraction_chain
+from mentalsaathi_ai.chains.reframe_scenario_chain import reframing_chain
+from mentalsaathi_ai.chains.relief_response_chain import relief_response_chain
+from mentalsaathi_ai.chains.calculate_risk import risk_calculation_chains as risk_agent
+
+__all__ = [
+    # Base class
+    "BaseChain",
+    # Active pipeline
+    "MentalSaathiPipeline",
+    "mentalsaathi_chain",
+    # Active stages
+    "FullAnalysisChain",
+    "full_analysis_chain",
+    "CrisisDetectionChain",
+    "crisis_detection_chain",
+    "ResponseGenerationChain",
+    "response_generation_chain",
+    # Legacy stages
+    "emotional_tone_detection_chain",
+    "depth_perception_chain",
+    "root_cause_extraction_chain",
+    "reframing_chain",
+    "relief_response_chain",
+    "risk_agent",
+]

mentalsaathi_ai-0.1.0/mentalsaathi_ai/chains/__main__.py

@@ -0,0 +1,109 @@
+import sys
+from mentalsaathi_ai import run
+from mentalsaathi_ai.schemas import CrisisCheck
+
+RESET  = "\033[0m"
+BOLD   = "\033[1m"
+DIM    = "\033[2m"
+CYAN   = "\033[96m"
+GREEN  = "\033[92m"
+YELLOW = "\033[93m"
+RED    = "\033[91m"
+GREY   = "\033[90m"
+WHITE  = "\033[97m"
+
+def header():
+    print(f"""
+{CYAN}{BOLD}╔══════════════════════════════════════════════╗
+║           TalkSaathi — Dev Chat            ║
+║        type 'quit' or Ctrl+C to exit       ║
+╚══════════════════════════════════════════════╝{RESET}
+""")
+
+def divider():
+    print(f"{GREY}{'─' * 48}{RESET}")
+
+def format_bot(text: str, anchor: str = ""):
+    print(f"\n{GREEN}{BOLD}TalkSaathi{RESET}")
+    # word-wrap at 48 chars
+    words = text.split()
+    line, lines = [], []
+    for w in words:
+        if sum(len(x) + 1 for x in line) + len(w) > 48:
+            lines.append(" ".join(line))
+            line = [w]
+        else:
+            line.append(w)
+    if line:
+        lines.append(" ".join(line))
+    for l in lines:
+        print(f"  {WHITE}{l}{RESET}")
+    if anchor:
+        print(f"\n  {YELLOW}[anchor] {anchor}{RESET}")
+
+def format_crisis(crisis_response: str, resources):
+    print(f"\n{RED}{BOLD}[CRISIS DETECTED]{RESET}")
+    print(f"  {WHITE}{crisis_response}{RESET}")
+    print(f"\n{RED}Helplines:{RESET}")
+    for r in resources:
+        print(f"  {YELLOW}{r.name}{RESET} — {r.contact} ({r.available})")
+
+def format_thinking():
+    print(f"\n  {DIM}thinking...{RESET}", end="\r")
+
+def build_context(history: list[dict]) -> str:
+    if not history:
+        return ""
+    lines = []
+    for turn in history[-6:]:  # last 6 turns max
+        lines.append(f"Student: {turn['student']}")
+        lines.append(f"TalkSaathi: {turn['bot']}")
+    return "\n".join(lines)
+
+def main():
+    header()
+    history: list[dict] = []
+
+    while True:
+        try:
+            print(f"\n{CYAN}{BOLD}You{RESET}")
+            user_input = input(f"  {WHITE}> {RESET}").strip()
+        except (KeyboardInterrupt, EOFError):
+            print(f"\n\n{DIM}Take care.{RESET}\n")
+            sys.exit(0)
+
+        if not user_input:
+            continue
+        if user_input.lower() in ("quit", "exit", "bye"):
+            print(f"\n{DIM}Take care.{RESET}\n")
+            sys.exit(0)
+        if user_input.lower() == "clear":
+            history.clear()
+            print(f"{DIM}[conversation cleared]{RESET}")
+            continue
+
+        context = build_context(history)
+        format_thinking()
+
+        try:
+            result = run(
+                student_message=user_input,
+                conversation_context=context,
+            )
+        except Exception as e:
+            print(f"\n  {RED}[error] {e}{RESET}")
+            continue
+
+        print(" " * 20, end="\r")  # clear "thinking..."
+
+        if isinstance(result, CrisisCheck):
+            format_crisis(result.crisis_response, result.resources)
+            history.append({"student": user_input, "bot": result.crisis_response or ""})
+        else:
+            format_bot(result.response, result.anchor)
+            history.append({"student": user_input, "bot": result.response})
+
+        divider()
+
+if __name__ == "__main__":
+    main()

mentalsaathi_ai-0.1.0/mentalsaathi_ai/chains/base_chain.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from langchain_core.runnables import Runnable
+
+
+class BaseChain(ABC):
+    """Abstract base class for all MentalSaathi pipeline chain stages.
+
+    Subclasses must implement:
+        _build() -> Runnable   — assemble the LCEL chain
+        __str__() -> str       — human-readable one-liner description
+
+    Provides automatically:
+        __call__   — invoke the chain with a dict
+        invoke     — alias for __call__ (LangChain convention)
+        __or__     — pipe this chain into another runnable (chain | next)
+        __repr__   — class name + chain repr
+    """
+
+    def __init__(self) -> None:
+        self._chain: Runnable = self._build()
+
+    @abstractmethod
+    def _build(self) -> Runnable:
+        """Assemble and return the LCEL chain for this stage."""
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """One-line human description of what this stage does."""
+
+    def __call__(self, inputs: dict):
+        return self._chain.invoke(inputs)
+
+    def invoke(self, inputs: dict):
+        return self._chain.invoke(inputs)
+
+    def __or__(self, other) -> Runnable:
+        return self._chain | other
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(chain={self._chain!r})"

mentalsaathi_ai-0.1.0/mentalsaathi_ai/chains/calculate_risk.py

@@ -0,0 +1,17 @@
+import mentalsaathi_ai.prompts
+import langchain_core.prompts
+import mentalsaathi_ai.llms
+
+prompt = langchain_core.prompts.ChatPromptTemplate.from_messages(
+    [
+        ("system", mentalsaathi_ai.prompts.risk_prompt["system"]),
+        ("human", mentalsaathi_ai.prompts.risk_prompt["human"]),
+    ]
+)
+prompt = prompt.partial(
+    format_instructions=mentalsaathi_ai.prompts.risk_parser["instructions"]
+)
+
+risk_calculation_chains = (
+    prompt | mentalsaathi_ai.llms.brain | mentalsaathi_ai.prompts.risk_parser["body"]
+)

mentalsaathi_ai-0.1.0/mentalsaathi_ai/chains/crisis_detection_chain.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import Runnable, RunnablePassthrough
+from mentalsaathi_ai.chains.base_chain import BaseChain
+from mentalsaathi_ai.prompts import crisis_detection_tools
+
+
+class CrisisDetectionChain(BaseChain):
+    """Stage 2 — the safety gate. Never merged with other stages.
+
+    Uses RunnablePassthrough.assign so all upstream analysis keys are
+    preserved alongside the new crisis_check key.
+
+    A false negative here can cost a life. When in doubt, flag as crisis.
+    """
+
+    def _build(self) -> Runnable:
+        import mentalsaathi_ai.llms
+        template = ChatPromptTemplate.from_messages(
+            [
+                ("system", crisis_detection_tools.system_prompt),
+                ("human", crisis_detection_tools.human_prompt),
+            ]
+        ).partial(format_instructions=crisis_detection_tools.parser.get_format_instructions())
+
+        return RunnablePassthrough.assign(
+            crisis_check=(template | mentalsaathi_ai.llms.brain | crisis_detection_tools.parser)
+        )
+
+    def __str__(self) -> str:
+        return "CrisisDetectionChain(safety gate → adds crisis_check key)"
+
+
+crisis_detection_chain = CrisisDetectionChain()