DEV Community: Lotfi

Introduction to Using Generative AI Models: Create Your Own Chatbot 🤖💬

Lotfi — Tue, 08 Oct 2024 15:13:44 +0000

Find the final source code produced by this article here.

Introduction

The aim of this article is to guide you step by step in creating an application that interacts with generative AI models. We will start by setting up a Python development environment, following best practices. Then, we will explain the basics of interacting with generative AI model as well as the fundamental principles of the Langchain framework. Once these foundations are laid, we will implement a simple chatbot using the OpenAI API and Langchain. Finally, we will integrate this chatbot into a graphical interface with Streamlit, to offer a smooth and interactive user experience.

Prerequisites

To follow this article, you will need the following:

Some knowledge of algorithms and Python programming.
Python version 3.11.9.
An OpenAI account to use their API.

We will use OpenAI models for this tutorial, but you can eventually replace them with other similar models according to your preferences.

Preparing the Work Environment

If you are already comfortable with Python, you can skip this section.

Creating the Project

Start by creating a directory for our project:

$ mkdir my_awesome_ai_project

Then, navigate into it:

$ cd my_awesome_ai_project

Installing the Appropriate Python Version with Pyenv

Pyenv is an essential tool for managing multiple Python versions on your machine. It allows you to install and switch between different Python versions easily, which is particularly useful when working on multiple projects requiring distinct versions.

To install Pyenv, follow the instructions provided on the Pyenv GitHub repository.

After installing Pyenv, use it to install the Python version required for this project:

$ pyenv install 3.11.9

Then, to ensure that this version is used by default in your project, create a .python-version file at the root of the project directory with the chosen version:

3.11.9

This will ensure that all Python commands executed in this directory use the correct version.

To verify that everything is working correctly, run the following command in the project directory:

$ python --version

You should then see the correct Python version displayed.

A Virtual Environment

To start your project well, it is essential to set up a Python virtual environment. But what exactly is a Python virtual environment? It's an isolated space that allows you to manage dependencies specific to each project, without interfering with those of other projects on your machine. This ensures a clean and secure working environment, where each project uses the specific library versions it needs.

To create a virtual environment in our project, run the following command at the project root:

python -m venv .venv

This command creates a .venv folder at the project root, which represents the virtual environment.

To activate our virtual environment, simply enter the following command:

source .venv/bin/activate

On Windows, use this command:

.venv\Scripts\activate.bat

To deactivate the virtual environment, simply type the following command:

deactivate

Dependency Management in a Python Project

In the following part of this article, you will need to add external dependencies to your project, meaning you will install packages in your virtual environment. To do this, you will use the following command:

pip install <package_name>

For example, to install the requests library, you would type:

pip install requests

Once you have installed all your dependencies, it is important to document them in a file that can be used later to recreate the environment exactly. For this, you will use the command:

pip freeze > requirements.txt

This command will generate a requirements.txt file containing the complete list of installed packages and their exact versions. This file is essential for sharing your project with other developers or deploying your application, as it will allow anyone to recreate the environment by running the following command:

pip install -r requirements.txt

This ensures that everyone working on the project is using the same package versions, preventing issues related to compatibility or version differences.

The "Hello World!"

Now that our project is properly configured, we will implement a small test program, the famous "Hello World". Create a main.py file at the project root with the following content:

def main():
    # The main() function represents the core of our program.
    # This is where we define the main actions to execute.
    print("Hello World!")

# The following condition checks if this script is run directly.
# If so, it calls the main() function. If the script is imported
# as a module in another file, this block will not be executed unless
# explicitly called.
if __name__ == "__main__":
    main()

To run this script, launch the following command:

python main.py

Running the script should display the phrase: "Hello World!".

And there you have it! We are now ready to start. 😄

OpenAI API

If you plan to use a model other than those offered by OpenAI, you can skip this section.

In this part, we will see how to obtain an OpenAI API key, which will allow us to interact with OpenAI's APIs.

Start by creating an account on the OpenAI website and log in to your account via this link: here.

Once authenticated, access the Dashboard/API Keys section and create a new API key. Copy the generated key, as we will need it later.

It's important to note that using this API is paid 💵. However, for the purposes of this article, a minimal amount will suffice to cover the essential needs and perform the proposed tests.

Environment Variable

The value of this API key is confidential and should never appear directly in your source code. To follow best practices, you will store it in an environment variable, which will allow the script to access it easily and securely.

To manage environment variables, you will use the dotenv package. Install it with the following command:

pip install python-dotenv

Don't forget to activate the Python virtual environment before running the pip install command. This will install the package in the project's virtual environment.

Once the package is installed, create a .env file at the project root. This file will contain the value of your API key:

OPENAI_API_KEY="<YOUR_API_KEY>"

If you are using a versioning system such as Git, make sure to add the .env file to your .gitignore to avoid versioning it.

To access the environment variable in the script, simply use the load_dotenv function at the beginning. Let's add this logic to the main.py file:

import os
from dotenv import load_dotenv

# Load environment variables from the .env file
load_dotenv()

def main():
    # Retrieve the OpenAI API key from environment variables
    openai_api_key: str = os.environ.get("OPENAI_API_KEY")

    # Display the API key (for testing)
    print(openai_api_key)

if __name__ == "__main__":
    main()

The script should display the value of your OpenAI key.

First Contact

To interact with the OpenAI API, you will install the openai package:

pip install openai

We will use this package to call the OpenAI API and generate a haiku using the gpt-4o-mini model. Let's modify our main.py file as follows:

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

def main():
    openai_api_key = os.environ.get("OPENAI_API_KEY")

    # Configure the OpenAI client with the API key
    client = OpenAI(api_key=openai_api_key)

    # Create a request to generate a haiku from the gpt-4o-mini model
    completion = client.chat.completions.create(
        # The model to use for generating the response, here "gpt-4o-mini"
        model="gpt-4o-mini",
        # The messages sent to the model, in list form. Each message has a "role" (here "user")
        # and a "content", which is the text we send to the model.
        messages=[
            {"role": "user", "content": "write a haiku about ai"}
        ],
        # The temperature parameter adjusts the creativity of the response. A value close to 0
        # gives more deterministic responses, while a higher value (up to 1)
        # allows for more diversity and improvisation in the response.
        temperature=0.7
    )

    # Display the response generated by the model
    print(completion.choices[0].message.content)

if __name__ == "__main__":
    main()

By running this script, the OpenAI API will generate a haiku about artificial intelligence, which the program will then display in the console.

We have just made a simple call to the OpenAI API to generate a haiku. This basic example allows us to familiarize ourselves with the API and understand how to interact with OpenAI models. In the rest of this article, we will explore more advanced interactions with the API using Langchain.

LangChain

If theory gives you a headache 🤯, feel free to skip this section and go directly to the part where we implement our chatbot!

In this chapter, we will explore the Langchain library and explain its basic principles.

Why Use LangChain

Langchain is a powerful library that facilitates the integration of generative AI models into complex process chains. This library is particularly useful when you need to manage multiple steps in an interaction between your applications and AI models.

By using LangChain, you can not only optimize the management of your interactions with AI APIs, but also create more modular workflows, allowing you to add new functionalities without complicating your code. Moreover, LangChain implements many tools that simplify our work and prevent us from reinventing the wheel, thus allowing us to focus on adding specific value to our applications.

Principle

LangChain is based on a simple principle: it allows chaining multiple processing steps with AI models in a fluid and organized manner. The goal is to create chains (hence the name "LangChain") that link AI models, data flows, and functionalities in a modular way.

To better understand how LangChain works, we will go through its key concepts step by step, putting them into practice with Python code examples:

1. Loaders

Loaders are used to import and manage data from different sources (files, APIs, etc.). This allows for quickly integrating external data into your workflows, thus optimizing the enrichment of AI model responses.

Code Example:

from langchain_community.document_loaders import TextLoader  

# Load a text file  
loader = TextLoader('my_file.txt')  

# Load the documents  
documents = loader.load()  

# Display the number of loaded documents  
print(f"Number of loaded documents: {len(documents)}")  

# Display the content of the first document  
print(f"Document content: {documents[0].page_content}")

Here, we use TextLoader to load the content of my_file.txt and import it as documents exploitable by LangChain.

2. Prompts

Prompts are the instructions you send to the AI model. With LangChain, you can customize these prompts to precisely match what you expect from the model.

Code Example:

from langchain.prompts import PromptTemplate  

# Create a prompt template  
template = "Translate the following text into English: {text}"  

prompt_template = PromptTemplate(  
    input_variables=["text"],  
    template=template,  
)  

# Generate the prompt with a variable  
my_prompt = prompt_template.format(text="Bonjour, comment allez-vous ?")  

print(my_prompt)

Here, we create a PromptTemplate that takes a text variable and generates a prompt by inserting this variable into the template.

3. LLMs (Large Language Models)

LLMs are large language models like OpenAI's GPT. LangChain directly integrates these models, allowing you to call them to generate responses.

Code Example:

import os  
from dotenv import load_dotenv  
from langchain_openai.llms import OpenAI  

load_dotenv()  

llm = OpenAI(openai_api_key=os.environ['OPENAI_API_KEY'])  

# Generate a response from a prompt  
response = llm.invoke(my_prompt)  

print(response)

Here, we initialize an OpenAI LLM model using our API key, then we use the previously generated prompt to get a response.

4. Chains

Chains allow you to link multiple steps in the same workflow. You can thus build more complex workflows by combining prompts, models, and other functionalities.

Code Example:

# Create a chain that combines the prompt and the LLM model  
chain = prompt_template | llm  

# Execute the chain with an input  
result = chain.invoke({"text": "Bonjour, comment allez-vous ?"})  

print(result)

Here, we create a chain that combines our prompt and the LLM model, then we execute the chain with a specific input to obtain the result.

5. Memory

Memory in LangChain offers the possibility to manage context in a conversation by keeping track of previous messages. This allows for creating smarter chatbots or assistants, capable of remembering past interactions to offer a more coherent user experience.

Code Example:

from langchain_community.chat_message_histories import ChatMessageHistory  
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage  

# Create an instance of ChatMessageHistory to track the conversation message history  
history = ChatMessageHistory()  

# Add a system message to the history, which defines the assistant's behavior  
history.add_message(SystemMessage(content="You are a helpful assistant. Answer all questions to the best of your ability."))  

# Add a human message to the history, representing the user's input in the conversation  
history.add_message(HumanMessage(content="Hi!"))  

# Add an AI message to the history, representing the assistant's response  
history.add_message(AIMessage(content="Hello! How can I help you?"))  

# Display the list of messages in the conversation history  
print(history.messages)

Here, ChatMessageHistory is used to store the history of exchanges. Each message from the system, user, or AI is added to this history, thus preserving the context of the conversation for future interactions.

By combining these elements, LangChain allows you to build complex and modular workflows, seamlessly integrating AI models. Whether it's for processing data, generating text, or creating intelligent conversational assistants, LangChain offers a flexible structure for your AI projects.

Creating a Chatbot

We finally arrive at the long-awaited part! Here, we will put into practice what we've seen previously to implement a simple chatbot using the LangChain library and OpenAI API.

Note: If you wish to use another model, you can consult the official LangChain documentation to learn how to change it easily.

Installing Dependencies

Let's start by installing the necessary packages by executing the following command:

pip install langchain langchain_openai langchain-community

Modifying the main.py file

Next, let's modify the main.py file to look like this:

import os  
from dotenv import load_dotenv  
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder  
from langchain_core.messages import SystemMessage  
from langchain_community.chat_message_histories import ChatMessageHistory  
from langchain_openai import ChatOpenAI

# Load environment variables from a .env file
load_dotenv()

# Retrieve the OpenAI API key from environment variables
openai_api_key = os.getenv("OPENAI_API_KEY")  

# Create a conversation prompt template with messages
prompt = ChatPromptTemplate.from_messages(
   [        
       # System message to define the assistant's role  
       SystemMessage("You are a helpful assistant. Answer all questions to the best of your ability."),  
       # Placeholder for messages to be filled dynamically  
       MessagesPlaceholder(variable_name="messages"),  
   ]  
)  

# Initialize the GPT-4 model with the API key and set the temperature to adjust creativity  
llm = ChatOpenAI(api_key=openai_api_key, model="gpt-4o-mini", temperature=0.7)

# Create a processing chain combining the prompt and the LLM model  
chain = prompt | llm  

# Create a chat message history to track the conversation  
chat_history = ChatMessageHistory()  

# Main function that manages the conversation with the assistant  
def main():  
   # Infinite loop to maintain a continuous conversation with the user 
   while True:  
       # Ask for user input  
       user_input = input("You: ")  

       # Add the user's message to the conversation history  
       chat_history.add_user_message(user_input)  

       # Use the model to generate a response based on the message history  
       response = chain.invoke({"messages": chat_history.messages})  

       # Display the assistant's response  
       print("Assistant:", response.content)  

       # Add the assistant's response to the message history  
       chat_history.add_ai_message(response.content)  


# Entry point of the program, calls the main function
if __name__ == "__main__":  
   main()

By running our main.py script, we will be able to interact with the chatbot.

Bonus 🎁: Graphical Interface

In this bonus part, we will see how to add a simple and elegant graphical interface to interact with the chatbot in a more user-friendly way.

We will use the Streamlit library to quickly create a functional graphical interface.

But before that, we're going to make some modifications to our source code to better structure it.

Code Refactoring

Creating the chatbot_core module

We will structure our code by creating a new file chatbot_core.py that will contain the core of the chatbot as a module:

import os
from dotenv import load_dotenv  
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder  
from langchain_core.messages import SystemMessage  
from langchain_community.chat_message_histories import ChatMessageHistory  
from langchain_openai import ChatOpenAI  


class ChatbotCore:  
    def __init__(  
            self,  
            openai_api_key=None,  
            system_prompt="You are a helpful assistant. Answer all questions to the best of your ability.",  
            model="gpt-4o-mini",  
            temperature=0.7,  
    ):  
        if openai_api_key is None:  
            load_dotenv()  
            openai_api_key = os.getenv("OPENAI_API_KEY")  
        self.api_key = openai_api_key  

        self.prompt = ChatPromptTemplate.from_messages(  
            [                SystemMessage(system_prompt),  
                MessagesPlaceholder(variable_name="messages"),  
            ]  
        )  
        # Configure the language model  
        self.llm = ChatOpenAI(  
            api_key=self.api_key, model=model, temperature=temperature  
        )  

        self.chain = self.prompt | self.llm  

        # Initialize conversation history  
        self.chat_history = ChatMessageHistory()  

    def send_message(self, message):  
        """  
        Send a message to the chatbot and receive the response.  
        Args:
            message (str): The message to send to the chatbot.  
        Returns:
            str: The chatbot's response.
        """
        self.chat_history.add_user_message(message)  
        response = self.chain.invoke({"messages": self.chat_history.messages})  
        self.chat_history.add_ai_message(response.content)  
        return response.content  

    def get_history(self):  
        """  
        Access the conversation history.  
        Returns:
            list: A list of conversation messages.
        """
        return self.chat_history.messages

We have encapsulated the chatbot logic in a ChatbotCore class that exposes useful methods for interacting with the chatbot.

Updating the main.py file

Here's how to use this class in main.py:

from chatbot_core import (ChatbotCore)

def main():  
    chatbot_core = ChatbotCore()

    while True:  
        user_input = input("You: ")  
        response = chatbot_core.send_message(user_input)  
        print("Assistant:", response)  


if __name__ == "__main__":  
    main()

Now that we have clean and modular source code, let's start the graphical interface part.

Implementing the Graphical Interface

Let's install Streamlit with the following command:

pip install streamlit

Then, create a chatbot_interface.py file to implement the interface:

import streamlit as st
from chatbot_core import ChatbotCore

# Define the application title in the Streamlit interface
st.title("💬 Chatbot")

# Add a caption under the title to describe the application
st.caption("🚀 A Streamlit chatbot powered by OpenAI")

# Check if a 'chatbot' object exists in the session state, otherwise create a new one
if "chatbot" not in st.session_state:
    # Create an instance of ChatbotCore in the session state
    st.session_state.chatbot = ChatbotCore()

# Display the chatbot's message history (user and assistant messages)
for msg in st.session_state.chatbot.get_history():
    # Display a message depending on whether it's from a user or an assistant
    st.chat_message("user" if msg.type == "human" else "assistant").write(msg.content)

# Check if the user has entered a message in the interface
if prompt := st.chat_input():
    # Display the user's message in the interface
    st.chat_message("user").write(prompt)

    # Send the message to the chatbot instance and get the response
    response = st.session_state.chatbot.send_message(prompt)

    # Display the chatbot's response in the interface
    st.chat_message("assistant").write(response)

To launch the graphical interface, run this command:

streamlit run chatbot.py

Conclusion

This guide has allowed you to discover the basics of generative AI models and create an interactive chatbot. To go further, Retrieval-augmented generation (RAG) and AI Agents represent a promising evolution of what we have achieved here. These technologies can enrich interactions and offer even more sophisticated solutions. Additionally, you can also explore how to deploy your Streamlit application to make it accessible online.

We hope this article has inspired you to continue exploring and developing AI-based applications. Good luck!

Three in one (code first) : NestJs & GraphQl & Mongoose

Lotfi — Sun, 01 Nov 2020 07:29:32 +0000

Follow me on Twitter, happy to take your suggestions and improvements.

I decided to write this blog post after working on a personal project. As I started it, I thought about a way to put in place a solid architecture to create a GraphQL API with NestJs and Mongoose.

Why GraphQL?

No more Over- and Underfetching ;

Rapid Product Iterations on the Frontend ;

Insightful Analytics on the Backend ;

Benefits of a Schema & Type System ;

-- How to GraphQL

Why NestJs?

Nest provides a level of abstraction above these common Node.js frameworks (Express/Fastify) but also exposes their APIs directly to the developer. This allows developers the freedom to use the myriad of third-party modules that are available for the underlying platform.

-- Filipe Mazzon

Why Mongoose?

MongooseJS provides an abstraction layer on top of MongoDB that eliminates the need to use named collections.

Models in Mongoose perform the bulk of the work of establishing up default values for document properties and validating data.

Functions may be attached to Models in MongooseJS. This allows for seamless incorporation of new functionality.

Queries use function chaining rather than embedded mnemonics which result in code that is more flexible and readable, therefore more maintainable as well.

-- Jim Medlock

Problem

There is a question that always comes up when I start to set up the architecture of a project, it is the definition of the data model and how the different layers of the application will consume it. In my case, the definition of a data model for the different layers of the application gives me some irritation 😓:

The definition of a schema for GraphQL to implement the API endpoint ;
The definition of a schema for Mongoose to organize the documents of the database ;
The definition of a data model so that the application map objects ;

Solution

The ideal is to have to define the data model only once and thus it will be used to generate the GraphQL schema, the MongoDB collection schemas as well as the classes used by NestJs providers. And the magic is that NestJs with its plugins allow us to do it easily 😙.

NestJs plugins

NestJS plugins encapsulate different technologies in NestJs modules for easy use and integration into the NestJs ecosystem. In this case, we will use the following two plugins: @nestjs/mongoose and @nestjs/graphql

These two plugins allow us to proceed in two ways:

schema-first: first, define the schemas for Mongoose and for GraphQL, then use it to generate our typescript classes.
code-first: first, define our typescript classes, then use them to generate our schemas Mongoose/GraphQL.

I used the code-first approach because it allows me to implement a single model (typescript classes) and use it to generate my schemas for GraphQL as well as for Mongoose 👌.

Implementation

Here is the final project source code on GitHub.

Okay, I've talked too much. Warm-up our fingers to do some magic 🧙!

NestJS

First, create our NestJs project using @nestjs/cli. We will call it three-in-one-project:

$ npm i -g @nestjs/cli
$ nest new three-in-one-project

This will initiate our NestJs project:

What interests us here is the content of the src/ folder :

main.ts: the entry point of the NestJS app where we bootstrap it.

app.module.ts: the root module of the NestJS app. It implemente a controller AppController and a provider AppService.

To serve the nest server run :

$ npm start

For better organization, we will put the AppModule files in a dedicated folder src/app/ and update the import path of AppModule in main.ts:

Don't forget to update the import path of AppModule in main.ts

Model

We are going to create an API that manages a list of Peron who have a list of Hobby for that we will create these two model in app/ folder:

// person.model.ts

export class Person {
  _id: string;
  name: string;
  hobbies: Hobby[];
}

// hobby.model.ts

export class Hobby {
  _id: string;
  name: string;
}

Mongoose

Installing dependencies

From the two classes Hobby and Person we will generate the corresponding mongoose schema HobbySchema and PersonSchema. For that we will install the package @nestjs/mongoose with some other dependencies :

$ npm i @nestjs/mongoose mongoose
$ npm i --save-dev @types/mongoose

Connection to MongoDB

To connecte our backend to mongoDB data base, we will import in AppModule the MongooseModule :

// app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MongooseModule } from '@nestjs/mongoose';

@Module({
  // "mongodb://localhost:27017/three-in-one-db" is the connection string to the project db
  imports: [
    MongooseModule.forRoot('mongodb://localhost:27017/three-in-one-db'),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

For better organization we will create two sub-modules PersonModule and HobbyModule each manage the corresponding model. We will use @nestjs/cli to do that quickly :

$ cd src\app\
$ nest generate module person
$ nest generate module hobby

The created modules PersonModule and HobbyModule are automatically imported in AppModule.

Now, move each file person.model.ts and hobby.model.ts into its corresponding modules :

Schema generation

We can now start to set up the generation of mongoose schemas. @nestjs/mongoose gives us a decorators to annotate our typescript classes to indicate how to generate the mongoose schemas. let's add some decorator to our classes:

// person.model.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Document, Schema as MongooseSchema } from 'mongoose';

import { Hobby } from '../hobby/hobby.model';

@Schema()
export class Person {
  _id: MongooseSchema.Types.ObjectId;

  @Prop()
  name: string;

  @Prop()
  hobbies: Hobby[];
}

export type PersonDocument = Person & Document;

export const PersonSchema = SchemaFactory.createForClass(Person);

// hobby.model.ts

import { Document, Schema as MongooseSchema } from 'mongoose';
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';

@Schema()
export class Hobby {
  _id: MongooseSchema.Types.ObjectId;

  @Prop()
  name: string;
}

export type HobbyDocument = Hobby & Document;

export const HobbySchema = SchemaFactory.createForClass(Hobby);

The @Prop() decorator defines a property in the document.

The @Schema() decorator marks a class as a schema definition
Mongoose documents (ex: PersonDocument) represent a one-to-one mapping to documents as stored in MongoDB.
MongooseSchema.Types.ObjectId is a mongoose type typically used for unique identifiers

And finally, we import the model to MongooseModule in our two modules :

// person.module.ts

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';

import { Person, PersonSchema } from './person.model';

@Module({
  imports: [
    MongooseModule.forFeature([{ name: Person.name, schema: PersonSchema }]),
  ],
})
export class PersonModule {}

// hobby.module.ts

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';

import { Hobby, HobbySchema } from './hobby.model';

@Module({
  imports: [
    MongooseModule.forFeature([{ name: Hobby.name, schema: HobbySchema }]),
  ],
})
export class HobbyModule {}

CRUD Operations

We will create the layer for our two modules witch implement CRUD operations. For each module, create a NestJS service who implements that. To create the two services, execute the following commands :

$ cd src\app\person\
$ nest generate service person --flat
$ cd ..\hobby\
$ nest generate service hobby --flat

we use --flat to not generate a folder for the service.

Update services to add CRUD methods and their inputs classes :

// person.service.ts

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model, Schema as MongooseSchema } from 'mongoose';

import { Person, PersonDocument } from './person.model';
import {
  CreatePersonInput,
  ListPersonInput,
  UpdatePersonInput,
} from './person.inputs';

@Injectable()
export class PersonService {
  constructor(
    @InjectModel(Person.name) private personModel: Model<PersonDocument>,
  ) {}

  create(payload: CreatePersonInput) {
    const createdPerson = new this.personModel(payload);
    return createdPerson.save();
  }

  getById(_id: MongooseSchema.Types.ObjectId) {
    return this.personModel.findById(_id).exec();
  }

  list(filters: ListPersonInput) {
    return this.personModel.find({ ...filters }).exec();
  }

  update(payload: UpdatePersonInput) {
    return this.personModel
      .findByIdAndUpdate(payload._id, payload, { new: true })
      .exec();
  }

  delete(_id: MongooseSchema.Types.ObjectId) {
    return this.personModel.findByIdAndDelete(_id).exec();
  }
}

// person.inputs.ts

import { Schema as MongooseSchema } from 'mongoose';
import { Hobby } from '../hobby/hobby.model';

export class CreatePersonInput {
  name: string;
  hobbies: Hobby[];
}

export class ListPersonInput {
  _id?: MongooseSchema.Types.ObjectId;
  name?: string;
  hobbies?: Hobby[];
}

export class UpdatePersonInput {
  _id: MongooseSchema.Types.ObjectId;
  name?: string;
  hobbies?: Hobby[];
}

// hobby.service.ts

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model, Schema as MongooseSchema } from 'mongoose';

import { Hobby, HobbyDocument } from './hobby.model';
import {
  CreateHobbyInput,
  ListHobbyInput,
  UpdateHobbyInput,
} from './hobby.inputs';

@Injectable()
export class HobbyService {
  constructor(
    @InjectModel(Hobby.name) private hobbyModel: Model<HobbyDocument>,
  ) {}

  create(payload: CreateHobbyInput) {
    const createdHobby = new this.hobbyModel(payload);
    return createdHobby.save();
  }

  getById(_id: MongooseSchema.Types.ObjectId) {
    return this.hobbyModel.findById(_id).exec();
  }

  list(filters: ListHobbyInput) {
    return this.hobbyModel.find({ ...filters }).exec();
  }

  update(payload: UpdateHobbyInput) {
    return this.hobbyModel
      .findByIdAndUpdate(payload._id, payload, { new: true })
      .exec();
  }

  delete(_id: MongooseSchema.Types.ObjectId) {
    return this.hobbyModel.findByIdAndDelete(_id).exec();
  }
}

// hobby.inputs.ts

export class CreateHobbyInput {
  name: string;
}

export class ListHobbyInput {
  _id?: MongooseSchema.Types.ObjectId;
  name?: string;
}

export class UpdateHobbyInput {
  _id: MongooseSchema.Types.ObjectId;
  name?: string;
}

Note that the attribute hobbies of Hobby class is an array of reference to Hobby object. So let's make some adjustment:

// person.model.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Document, Schema as MongooseSchema } from 'mongoose';

import { Hobby } from '../hobby/hobby.model';

@Schema()
export class Person {
  _id: MongooseSchema.Types.ObjectId;

  @Prop()
  name: string;

  @Prop({ type: [MongooseSchema.Types.ObjectId], ref: Hobby.name })
  hobbies: MongooseSchema.Types.ObjectId[];
}

export type PersonDocument = Person & Document;

export const PersonSchema = SchemaFactory.createForClass(Person);

// person.inputs.ts

import { Hobby } from '../hobby/hobby.model';
import { Schema as MongooseSchema } from 'mongoose';

export class CreatePersonInput {
  name: string;
  hobbies: MongooseSchema.Types.ObjectId[];
}

export class ListPersonInput {
  _id?: MongooseSchema.Types.ObjectId;
  name?: string;
  hobbies?: MongooseSchema.Types.ObjectId[];
}

export class UpdatePersonInput {
  _id: MongooseSchema.Types.ObjectId;
  name?: string;
  hobbies?: MongooseSchema.Types.ObjectId[];
}

GraphQL

We are almost done, we just have to implement the graphQL layer.

Dependencies installation

$ npm i @nestjs/graphql graphql-tools graphql apollo-server-express

Schema generation

As for the mongoose, we will use decorators from @nestjs/graphql to annotate our typescript classes to indicate how to generate the graphQL schemas:

// person.model.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Field, ObjectType } from '@nestjs/graphql';
import { Document, Schema as MongooseSchema } from 'mongoose';

import { Hobby } from '../hobby/hobby.model';

@ObjectType()
@Schema()
export class Person {
  @Field(() => String)
  _id: MongooseSchema.Types.ObjectId;

  @Field(() => String)
  @Prop()
  name: string;

  @Field(() => [String])
  @Prop({ type: [MongooseSchema.Types.ObjectId], ref: Hobby.name })
  hobbies: MongooseSchema.Types.ObjectId[];
}

export type PersonDocument = Person & Document;

export const PersonSchema = SchemaFactory.createForClass(Person);

// hobby.model.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Field, ObjectType } from '@nestjs/graphql';
import { Document, Schema as MongooseSchema } from 'mongoose';

@ObjectType()
@Schema()
export class Hobby {
  @Field(() => String)
  _id: MongooseSchema.Types.ObjectId;

  @Field(() => String)
  @Prop()
  name: string;
}

export type HobbyDocument = Hobby & Document;

export const HobbySchema = SchemaFactory.createForClass(Hobby);

For more information about @nestjs/graphql decorators ObjectType and Field: official doc

Resolvers

To define our graphQL query, mutation, and resolvers we will create a NestJS resolver. we can use the NestJs CLI to do that:

$ cd src\app\person\
$ nest generate resolver person --flat
$ cd ..\hobby\
$ nest generate resolver hobby --flat

Then, update the generated files :

// person.resolver.ts

import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
import { Schema as MongooseSchema } from 'mongoose';

import { Person } from './person.model';
import { PersonService } from './person.service';
import {
  CreatePersonInput,
  ListPersonInput,
  UpdatePersonInput,
} from './person.inputs';

@Resolver(() => Person)
export class PersonResolver {
  constructor(private personService: PersonService) {}

  @Query(() => Person)
  async person(
    @Args('_id', { type: () => String }) _id: MongooseSchema.Types.ObjectId,
  ) {
    return this.personService.getById(_id);
  }

  @Query(() => [Person])
  async persons(
    @Args('filters', { nullable: true }) filters?: ListPersonInput,
  ) {
    return this.personService.list(filters);
  }

  @Mutation(() => Person)
  async createPerson(@Args('payload') payload: CreatePersonInput) {
    return this.personService.create(payload);
  }

  @Mutation(() => Person)
  async updatePerson(@Args('payload') payload: UpdatePersonInput) {
    return this.personService.update(payload);
  }

  @Mutation(() => Person)
  async deletePerson(
    @Args('_id', { type: () => String }) _id: MongooseSchema.Types.ObjectId,
  ) {
    return this.personService.delete(_id);
  }
}

// hobby.resolver.ts

import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
import { Schema as MongooseSchema } from 'mongoose';

import { Hobby } from './hobby.model';
import { HobbyService } from './hobby.service';
import {
  CreateHobbyInput,
  ListHobbyInput,
  UpdateHobbyInput,
} from './hobby.inputs';

@Resolver(() => Hobby)
export class HobbyResolver {
  constructor(private hobbyService: HobbyService) {}

  @Query(() => Hobby)
  async hobby(
    @Args('_id', { type: () => String }) _id: MongooseSchema.Types.ObjectId,
  ) {
    return this.hobbyService.getById(_id);
  }

  @Query(() => [Hobby])
  async hobbies(@Args('filters', { nullable: true }) filters?: ListHobbyInput) {
    return this.hobbyService.list(filters);
  }

  @Mutation(() => Hobby)
  async createHobby(@Args('payload') payload: CreateHobbyInput) {
    return this.hobbyService.create(payload);
  }

  @Mutation(() => Hobby)
  async updateHobby(@Args('payload') payload: UpdateHobbyInput) {
    return this.hobbyService.update(payload);
  }

  @Mutation(() => Hobby)
  async deleteHobby(
    @Args('_id', { type: () => String }) _id: MongooseSchema.Types.ObjectId,
  ) {
    return this.hobbyService.delete(_id);
  }
}

For more information about @nestjs/graphql decorators Mutation, Resolver,and Query: official doc

let's add some decorators to inputs classes so that GraphQl recognizes them :

// person.inputs.ts

import { Field, InputType } from '@nestjs/graphql';
import { Schema as MongooseSchema } from 'mongoose';

import { Hobby } from '../hobby/hobby.model';

@InputType()
export class CreatePersonInput {
  @Field(() => String)
  name: string;

  @Field(() => [String])
  hobbies: MongooseSchema.Types.ObjectId[];
}

@InputType()
export class ListPersonInput {
  @Field(() => String, { nullable: true })
  _id?: MongooseSchema.Types.ObjectId;

  @Field(() => String, { nullable: true })
  name?: string;

  @Field(() => [String], { nullable: true })
  hobbies?: MongooseSchema.Types.ObjectId[];
}

@InputType()
export class UpdatePersonInput {
  @Field(() => String)
  _id: MongooseSchema.Types.ObjectId;

  @Field(() => String, { nullable: true })
  name?: string;

  @Field(() => [String], { nullable: true })
  hobbies?: MongooseSchema.Types.ObjectId[];
}

// hobby.inputs.ts

import { Schema as MongooseSchema } from 'mongoose';
import { Field, InputType } from '@nestjs/graphql';

@InputType()
export class CreateHobbyInput {
  @Field(() => String)
  name: string;
}

@InputType()
export class ListHobbyInput {
  @Field(() => String, { nullable: true })
  _id?: MongooseSchema.Types.ObjectId;

  @Field(() => String, { nullable: true })
  name?: string;
}

@InputType()
export class UpdateHobbyInput {
  @Field(() => String)
  _id: MongooseSchema.Types.ObjectId;

  @Field(() => String, { nullable: true })
  name?: string;
}

Import GraphQLModule

Finally, import the GraphQLModule in AppModule:

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { GraphQLModule } from '@nestjs/graphql';
import { join } from 'path';

import { PersonModule } from './person/person.module';
import { HobbyModule } from './hobby/hobby.module';

import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [
    MongooseModule.forRoot('mongodb://localhost:27017/three-in-one-db'),
    GraphQLModule.forRoot({
      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
      sortSchema: true,
      playground: true,
      debug: false,
    }),
    PersonModule,
    HobbyModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

autoSchemaFile property value is the path where your automatically generated schema will be created

sortSchema the types in the generated schema will be in the order they are defined in the included modules. To sort the schema lexicographically turn this attribute to true
playground to activate graqh-playground
debug to turn on/off debug mode

GraphQL playground

The playground is a graphical, interactive, in-browser GraphQL IDE, available by default on the same URL as the GraphQL server itself. To access the playground, you need a basic GraphQL server configured and running.
-- NestJs Doc

We have already activated playground in the previous step, once the server is started (yarn start), we can access it via the following URL: http://localhost:3000/graphql :

Populate & ResolveField

Mongoose has a powerful method called populate(), which lets you reference documents in other collections.

Population is the process of automatically replacing the specified paths in the document with document(s) from other collection(s). We may populate a single document, multiple documents, a plain object, multiple plain objects, or all objects returned from a query. Let's look at some examples.
-- Mongoose Doc

We can use Mongoose populate to resolve hobbies field of Person :

// person.resolver.ts

import {
  Args,
  Mutation,
  Parent,
  Query,
  ResolveField,
  Resolver,
} from '@nestjs/graphql';
import { Schema as MongooseSchema } from 'mongoose';

import { Person, PersonDocument } from './person.model';
import { PersonService } from './person.service';
import {
  CreatePersonInput,
  ListPersonInput,
  UpdatePersonInput,
} from './person.inputs';
import { Hobby } from '../hobby/hobby.model';

@Resolver(() => Person)
export class PersonResolver {
  constructor(private personService: PersonService) {}

  @Query(() => Person)
  async person(
    @Args('_id', { type: () => String }) _id: MongooseSchema.Types.ObjectId,
  ) {
    return this.personService.getById(_id);
  }

  @Query(() => [Person])
  async persons(
    @Args('filters', { nullable: true }) filters?: ListPersonInput,
  ) {
    return this.personService.list(filters);
  }

  @Mutation(() => Person)
  async createPerson(@Args('payload') payload: CreatePersonInput) {
    return this.personService.create(payload);
  }

  @Mutation(() => Person)
  async updatePerson(@Args('payload') payload: UpdatePersonInput) {
    return this.personService.update(payload);
  }

  @Mutation(() => Person)
  async deletePerson(
    @Args('_id', { type: () => String }) _id: MongooseSchema.Types.ObjectId,
  ) {
    return this.personService.delete(_id);
  }

  @ResolveField()
  async hobbies(
    @Parent() person: PersonDocument,
    @Args('populate') populate: boolean,
  ) {
    if (populate)
      await person
        .populate({ path: 'hobbies', model: Hobby.name })
        .execPopulate();

    return person.hobbies;
  }
}

// person.model.ts

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Field, ObjectType } from '@nestjs/graphql';
import { Document, Schema as MongooseSchema } from 'mongoose';

import { Hobby } from '../hobby/hobby.model';

@ObjectType()
@Schema()
export class Person {
  @Field(() => String)
  _id: MongooseSchema.Types.ObjectId;

  @Field(() => String)
  @Prop()
  name: string;

  @Field(() => [Hobby])
  @Prop({ type: [MongooseSchema.Types.ObjectId], ref: Hobby.name })
  hobbies: MongooseSchema.Types.ObjectId[] | Hobby[];
}

export type PersonDocument = Person & Document;

export const PersonSchema = SchemaFactory.createForClass(Person);

This allows us to do request Person in this way:

Conclusion

As a developer, we combine different bricks of technologies to set up a viable ecosystem 🌍 for our project. In a javascript ecosystem, the advantage (or the disadvantage) is the abundance of brick and the possibility of combination. I hope to still have some motivation to be able to write a sequel to this blog post which explains the integration of this GraphQL API in a monorepo development environment and thus shares this data model between several applications and libraries.