How I Built a 'Digital Companion' Chatbot for Mindfulness with FastAPI, Celery, and spaCy

”

Who This Guide Is For

This guide is for Python backend developers building conversational AI for mental health and wellness. You should have solid understanding of FastAPI, NLP concepts, and asynchronous task processing. If you're creating wellness chatbots, mental health assistants, or any application requiring proactive user engagement, this guide is for you.

The inspiration for this project came from the desire to create a tool that offers proactive mental wellness support. Instead of a user always having to seek out help, what if an application could gently offer a moment of calm during a busy day? This "Digital Companion" is a project that showcases how modern web technologies can be used to build applications with a positive impact on mental well-being.

We will build a chatbot that can:

”

Key Definition: NLP Intent Recognition & spaCy Natural Language Processing (NLP) intent recognition is the process of automatically determining what a user wants from their text input. In chatbot systems, this means mapping user messages to specific intents like "stress_management," "anxiety_relief," or "meditation_request." spaCy is an industrial-strength NLP library for Python that provides pre-trained models for 60+ languages and support for 80+ tokenizers. Unlike heavier frameworks like TensorFlow or PyTorch, spaCy is designed for production use—blazing fast (1M+ tokens/second) and lightweight. According to spaCy benchmark tests, it's 10-100x faster than NLTK for common operations while maintaining state-of-the-art accuracy. spaCy's pipeline architecture makes it perfect for intent recognition: text tokenization → part-of-speech tagging → dependency parsing → entity recognition. For mental health chatbots, this means understanding that "I feel overwhelmed" maps to "stress_management" intent in under 5 milliseconds, enabling real-time conversational responses.

1. Listen: Accept a user's message about their current state of mind.
2. Understand: Use spaCy to recognize the user's intent (e.g., feeling stressed or anxious).
3. Act: Immediately suggest a relevant mindfulness exercise.
4. Remind: Asynchronously schedule a series of gentle reminders for short mindfulness breaks throughout the day using Celery.

This project is perfect for developers interested in the practical application of NLP, asynchronous task scheduling, and modern backend development.

Prerequisites

• Python 3.7+ and an understanding of virtual environments.
• Basic knowledge of building APIs.
• Docker and Docker Compose for easy setup of our message broker.

Many mental wellness apps are reactive; they require the user to open the app and actively seek out a meditation or exercise. The challenge is to create a more proactive system that can intelligently schedule reminders without being intrusive.

This is where our tech stack shines:

• FastAPI: For creating a high-performance API that can handle incoming user messages efficiently.
• spaCy: To perform lightweight yet powerful intent recognition on user messages, allowing our chatbot to understand the user's needs.
• Celery: To manage asynchronous tasks. When a user expresses stress, we don't want our main application to be blocked while scheduling future reminders. Celery, with a message broker like Redis, handles this in the background.
• Celery Beat: A scheduler for Celery that allows us to trigger periodic tasks, like sending daily mindfulness tips or checking in with the user.

Before we start coding, let's set up our environment.

First, create a project directory and a virtual environment:

mkdir digital-companion && cd digital-companion
python3 -m venv venv
source venv/bin/activate

Next, create a requirements.txt file with the necessary libraries:

fastapi
uvicorn
celery[redis]
spacy
requests

Install these dependencies:

pip install -r requirements.txt

We also need to download a spaCy language model. We'll use a small English model for this project:

python -m spacy download en_core_web_sm

Finally, we'll use Docker to run Redis, our message broker. Create a docker-compose.yml file:

version: '3.8'
services:
  redis:
    image: redis:6.2-alpine
    ports:
      - "6379:6379"

Start Redis by running:

docker-compose up -d

Your Redis instance is now running in the background.

Let's create the basic structure for our FastAPI application.

What we're doing

We'll create a main.py file that will house our API. We'll start with a simple endpoint to make sure everything is working correctly.

Implementation

Create a file named main.py:

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Welcome to your Digital Companion"}```

### How it works

This code snippet initializes a FastAPI application and defines a single endpoint for the root URL (`/`). When a GET request is made to this URL, it returns a simple JSON response.

To run the application, use uvicorn:

```bash
uvicorn main:app --reload

You should see output indicating that the server is running. You can now visit http://127.0.0.1:8000 in your browser and see the welcome message.

Now, let's integrate Celery for our asynchronous tasks.

What we're doing

We will create a Celery instance and define a simple task. This will involve creating a celery_worker.py file to configure Celery and define our tasks.

Implementation

Create a celery_worker.py file:

# celery_worker.py
from celery import Celery
import time

# Configure Celery
celery_app = Celery(
    'tasks',
    broker='redis://localhost:6379/0',
    backend='redis://localhost:6379/0'
)

@celery_app.task
def send_mindfulness_reminder(user_id: int, message: str):
    """
    A mock function to simulate sending a mindfulness reminder.
    In a real application, this would send an email, a push notification, etc.
    """
    print(f"Sending reminder to user {user_id}: '{message}'")
    time.sleep(5)  # Simulate a delay
    return f"Reminder sent to user {user_id}"

celery_app.conf.beat_schedule = {
    'send-daily-tip': {
        'task': 'celery_worker.send_mindfulness_reminder',
        'schedule': 86400.0,  # Every 24 hours
        'args': (0, "Here is your daily mindfulness tip: Take a moment to notice three things you can see around you.")
    },
}
celery_app.conf.timezone = 'UTC'```

### How it works

We create a Celery instance, specifying our Redis instance as both the message broker and the result backend. We then define a task `send_mindfulness_reminder` using the `@celery_app.task` decorator. We've also configured Celery Beat to send a daily tip every 24 hours.

To run the Celery worker, open a new terminal and run:

```bash
celery -A celery_worker.celery_app worker --loglevel=info

To run Celery Beat, open another terminal:

celery -A celery_worker.celery_app beat --loglevel=info

Now for the "smart" part of our chatbot. We'll use spaCy to understand the user's intent.

What we're doing

We'll create a simple intent recognition function that can identify if a user's message indicates stress.

Implementation

Create a new file nlp.py:

# nlp.py
import spacy

# Load the spaCy model
nlp = spacy.load("en_core_web_sm")

# Define keywords for different intents
STRESS_KEYWORDS = ["stress", "anxious", "overwhelmed", "worried", "burnout"]

def recognize_intent(text: str):
    doc = nlp(text.lower())
    for token in doc:
        if token.lemma_ in STRESS_KEYWORDS:
            return "stress_intent"
    return "unknown_intent"

How it works

This function takes a text string, processes it with spaCy, and checks if any of the lemmatized words match our predefined stress keywords. Lemmatization reduces words to their base form (e.g., "worried" becomes "worry"), making our keyword matching more robust. This is a simple but effective way to perform basic intent recognition.

Now let's integrate everything into our FastAPI application.

What we're doing

We'll create a new endpoint in main.py that accepts a user's message, uses our nlp.py module to recognize the intent, and if stress is detected, triggers Celery to schedule a series of mindfulness reminders.

Implementation

Update main.py:

# main.py
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
from celery_worker import send_mindfulness_reminder
from nlp import recognize_intent
from datetime import timedelta

app = FastAPI()

class Message(BaseModel):
    user_id: int
    text: str

@app.get("/")
def read_root():
    return {"message": "Welcome to your Digital Companion"}

@app.post("/chat")
def chat(message: Message, background_tasks: BackgroundTasks):
    intent = recognize_intent(message.text)

    if intent == "stress_intent":
        # Immediate response
        response = {
            "message": "I understand you're feeling stressed. Here's a quick exercise: Take a deep breath in for 4 seconds, hold for 4, and exhale for 6. Repeat this three times."
        }

        # Schedule follow-up reminders
        reminders = [
            ("In 1 hour, take a moment to stretch.", timedelta(hours=1)),
            ("In 3 hours, how about a 5-minute walk?", timedelta(hours=3)),
            ("Before you end your day, reflect on one positive thing that happened.", timedelta(hours=6))
        ]

        for msg, delay in reminders:
            send_mindfulness_reminder.apply_async(args=[message.user_id, msg], countdown=delay.total_seconds())

        return response
    else:
        return {"message": "I'm here to help with mindfulness. Try telling me if you're feeling stressed."}

How it works

1. We define a Message model to structure the incoming request body.
2. The /chat endpoint receives a user's message and user_id.
3. It calls recognize_intent to determine the user's state.
4. If the intent is stress_intent, it provides an immediate mindfulness exercise.
5. Crucially, it then uses send_mindfulness_reminder.apply_async to schedule several follow-up reminders at different intervals using the countdown argument. These tasks are sent to our Celery worker to be executed in the background, so the API response is immediate.

• Input Validation: FastAPI, with Pydantic, automatically validates incoming data. This is a great first line of defense.
• Authentication: In a real-world application, you would protect your endpoints with an authentication mechanism like OAuth2 to ensure only authorized users can interact with the chatbot.
• Rate Limiting: To prevent abuse, consider implementing rate limiting on your API endpoints.

• Containerization: For a production environment, you would containerize the FastAPI app, the Celery worker, and the Celery Beat scheduler using Docker.
• Environment Variables: Use environment variables for sensitive information like database credentials or API keys, rather than hardcoding them.
• Monitoring: Tools like Flower can be used to monitor your Celery workers and tasks.

• More Advanced NLP: For more sophisticated intent recognition, you could train a custom machine learning model using libraries like Rasa or even leverage large language models (LLMs) for more conversational abilities.
• WebSocket for Real-time Communication: Instead of a simple HTTP endpoint, you could use WebSockets for a more interactive, real-time chat experience.

How does Celery differ from simple background threads or cron jobs?

Celery is a distributed task queue built on message brokers like Redis or RabbitMQ, offering significant advantages over alternatives. Unlike Python's threading module, Celery tasks run in separate worker processes, avoiding Python's GIL limitations and providing true parallelism. Unlike cron jobs which run on fixed schedules, Celery supports dynamic scheduling with apply_async(countdown=N) to trigger tasks at variable times. Celery also provides task result tracking, automatic retries on failure, task prioritization, and horizontal scaling—you can add more workers to handle increased load. For wellness reminders where timing matters and reliability is critical, Celery's robustness justifies the added complexity.

Can I use spaCy for languages other than English?

Yes, spaCy supports 60+ languages with trained models for 25+ languages including Chinese, Spanish, German, French, and Japanese. For supported languages, simply download the appropriate model like python -m spacy download zh_core_web_sm for Chinese or de_core_web_sm for German. For unsupported languages, spaCy can still perform tokenization, sentence boundary detection, and lemmatization if you provide language-specific rules. The intent recognition approach in this tutorial—matching lemmatized keywords—works across all spaCy-supported languages. For production multilingual chatbots, consider language detection first (using libraries like langdetect), then loading the appropriate spaCy model.

How do I scale this chatbot for thousands of concurrent users?

Scaling requires addressing multiple layers. FastAPI supports async/await and can handle 10,000+ requests/second on a single server with proper async database drivers. Use Gunicorn with Uvicorn workers in production: gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker. Celery scales horizontally—add more worker processes across multiple machines. Redis as broker can handle 100,000+ operations/second. For the database, use connection pooling and consider read replicas for read-heavy operations. For global scale, deploy workers across multiple regions near your users. Monitor with Flower (Celery monitoring tool) and implement rate limiting to prevent abuse.

What privacy considerations apply to mental health chatbots?

Mental health data is sensitive protected health information (PHI) under regulations like HIPAA (US), GDPR (EU), and similar laws worldwide. Key considerations: data encryption (TLS in transit, at-rest encryption for storage), access controls (role-based authentication, audit logging), data minimization (only collect what's necessary), user consent (clear disclosure of data use), right to deletion (ability to export/delete all user data), and third-party risk (vet cloud providers). Avoid storing identifiable information unnecessarily. Consider on-premises deployment for healthcare organizations. Disclaimer that the chatbot is not clinical advice is essential—include a prominent statement that users should seek professional help for crises.

We've successfully built a "Digital Companion" chatbot that combines a FastAPI backend, Celery for asynchronous task scheduling, and spaCy for natural language processing. This project is a great starting point for anyone looking to build intelligent, responsive, and impactful web applications.

The key takeaway is how these powerful tools can be integrated to solve a real-world problem. By offloading tasks to a background worker, our API remains fast and responsive, providing a much better user experience.

Next steps for readers:

• Expand the number of intents our chatbot can recognize.
• Integrate a database to store user preferences and conversation history.
• Implement a more sophisticated method for sending reminders, such as email or push notifications.

• FastAPI Documentation
• Celery Project
• spaCy 101