Turn therapy session notes into standard GAD-7 and PHQ-9 assessments, and see whether a client is improving, plateauing or getting worse between sessions.
Built as a proof of concept for Mentalyc with a LangGraph multi-agent workflow, served through FastAPI and containerised with Docker.
- Structured assessments: analyses structured session notes (for example SOAP notes) generated from session recordings.
- Symptom tracking: scores each symptom per session and compares sessions to show progress.
- Multi-agent design: a separate agent for each assessment protocol (GAD-7, PHQ-9), so new protocols can be added without touching the others.
- Therapist view: a simple web interface for submitting sessions and reading the progress report.
- Sentiment classification. The entry node reads the session notes and classifies them as anxious or depressed.
- Assessment router. Anxious sessions go to the GAD-7 agent; depressed sessions go to the PHQ-9 agent.
- Assessment agents. Each agent scores every item of its questionnaire, classifies severity and justifies each score from the notes.
- Summarizer. Compares sessions item by item (improved, plateaued or worsened) and writes a report with actionable insights for the therapist.
Each node does one job, so the workflow is easy to follow, test and extend.
- Python 3.10+
- Poetry
- Docker and Docker Compose (optional, for containers)
- A Groq API key
git clone https://github.com/danielAdama/mentalyc-note.git
cd mentalyc-noteCreate a .env file in the project root:
GROQ_API_KEY=<your-groq-api-key>Other settings live in app_config.yml.
poetry install
poetry shell
make start_dev- API docs: http://localhost:8002/docs
- Frontend: http://localhost:8081
make compose_upThis builds the images and starts the backend and frontend containers in one step.
Health check.
{ "message": "Mentalyc Service API is RUNNING!" }Analyses a client's sessions and returns per-item scores for each session, a severity classification with justification, and a written progress report.
Example result for a client with anxiety:
| Session 1 | Session 2 | |
|---|---|---|
| GAD-7 total | 10 | 4 |
| Severity | Moderate anxiety | Mild anxiety |
| Trend | Improved on 6 of 7 items; "trouble relaxing" plateaued |
Full JSON response
{
"code": 200,
"message": "Progress tracked successfully",
"data": {
"sentiment": "anxious",
"GAD7_analysis": {
"session1": {
"gad_7_scoring_table": {
"Feeling nervous, anxious, or on edge": 2,
"Not being able to stop or control worrying": 2,
"Worrying too much about different things": 2,
"Trouble relaxing": 1,
"Being so restless that it's hard to sit still": 1,
"Becoming easily annoyed or irritable": 1,
"Feeling afraid as if something awful might happen": 1
},
"total_gad_7_score": 10,
"anxiety_severity_classification": "Moderate anxiety",
"justification": "The client reported experiencing symptoms of anxiety, including feeling nervous and anxious, worrying too much, and having trouble relaxing, over the past six weeks. These align with moderate anxiety severity based on the GAD-7 scoring criteria."
},
"session2": {
"gad_7_scoring_table": {
"Feeling nervous, anxious, or on edge": 1,
"Not being able to stop or control worrying": 1,
"Worrying too much about different things": 1,
"Trouble relaxing": 1,
"Being so restless that it's hard to sit still": 0,
"Becoming easily annoyed or irritable": 0,
"Feeling afraid as if something awful might happen": 0
},
"total_gad_7_score": 4,
"anxiety_severity_classification": "Mild anxiety",
"justification": "The client reported a significant reduction in anxiety and stress, with improved task management and boundary-setting. His symptoms have decreased following the application of therapy strategies, indicating mild anxiety severity based on the GAD-7 scoring criteria."
}
},
"insight": "### Assessment Summary\nThe client underwent a GAD-7 assessment, which measures the severity of generalized anxiety disorder symptoms. Between Session 1 and Session 2, the client's severity classification improved from \"Moderate anxiety\" to \"Mild anxiety.\" Initially, the client reported experiencing several symptoms of anxiety, including feeling nervous, worrying too much, and having trouble relaxing, which aligned with moderate anxiety severity. However, by Session 2, the client showed a significant reduction in anxiety and stress levels, attributed to improved task management, boundary-setting, and the application of therapy strategies. This progress led to a reclassification to mild anxiety severity.\n\n### Progress Analysis\nThe progress report across sessions indicates the following changes in symptoms:\n- **Feeling nervous, anxious, or on edge:** Improvement\n- **Not being able to stop or control worrying:** Improvement\n- **Worrying too much about different things:** Improvement\n- **Trouble relaxing:** Plateau\n- **Being so restless that it's hard to sit still:** Improvement\n- **Becoming easily annoyed or irritable:** Improvement\n- **Feeling afraid as if something awful might happen:** Improvement\n- **Total score:** Improvement\n\nOverall, the client has shown significant improvement in most anxiety symptoms, with the total score reflecting this positive trend. However, the symptom of \"trouble relaxing\" has plateaued, indicating a need for targeted strategies to address this specific issue.\n\n### Actionable Insights\nTo sustain the improvements and address the plateau:\n- For symptoms showing improvement, continue and possibly intensify the current therapy strategies and stress management techniques, as they seem to be effective.\n- For \"trouble relaxing,\" which has plateaued, consider introducing or enhancing relaxation techniques such as deep breathing exercises, progressive muscle relaxation, or mindfulness meditation. Regular practice of these techniques could help improve the client's ability to relax.\n- It might also be beneficial to explore the underlying reasons for the difficulty in relaxing, which could be related to unresolved issues, unmanaged stress, or physical discomfort.\n\n### Encouragement\nIt's truly commendable to see the significant progress made between sessions, reflecting the client's hard work and dedication to their mental health. Continuing on this path, with a focus on overcoming the remaining challenges, such as trouble relaxing, will be key to further progress. Remember, mental health is a journey, and it's okay to take it one step at a time."
}
}mentalyc-note/
├── mentalyc_ai/ # Agent workflow
│ ├── agents/ # base_agent.py and the assessment agents
│ ├── nodes/ # Classifier, assessment and summarizer nodes
│ ├── routers/ # Routes a session to GAD-7 or PHQ-9
│ ├── schema/ # GAD-7, PHQ-9, sentiment, state and summary schemas
│ ├── prompt/templates/ # System prompts for each node
│ └── utils.py
├── src/ # FastAPI app
│ ├── controllers/ # Request handlers
│ ├── services/ # Business logic
│ ├── repositories/ # Data access
│ ├── schemas/ # Pydantic request and response models
│ ├── exceptions/ # Custom exception handlers
│ └── utils/
├── frontend/ # Static therapist view (HTML, CSS, JS)
├── config/ # Configuration and logging
├── agent_graph_workflow.png # Workflow diagram
├── Dockerfile.backend
├── Dockerfile.frontend
├── docker-compose.yml
├── Makefile
└── pyproject.toml
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-change - Commit your changes:
git commit -m "add: my change" - Push the branch:
git push origin feature/my-change - Open a pull request
MIT. See LICENSE.
Daniel Enemona Adama · adamadaniel321@gmail.com · Portfolio