MagicSearch IT project 2A

Welcome in the promised land of trading card games players! By following these instructions, you will access our API where we gave our blood and tears to provide you with a diversity of searching tools !

Before accessing the app, it is necessary to have a PostgreSQL ready

To do so, go to https://datalab.sspcloud.fr, and create a PostgreSQL service.

This PostgreSQL service needs to be configured with pgvector.

To do so, when creating the service, go into the PostgreSQL section, then Image section, Image name, and select inseefrlab/onyxia-postgresql-pgvector.

Once this is done, a pop-up should open, giving you something like this:

Hostname : *a hostname*
Port : *a port*
Database : defaultdb
Username : *a username*
Password : *a password

Now, go into the MagicSearch root of the project on VSCode, and create a .env file. In it, you should put :

POSTGRES_HOST=*the hostname*
POSTGRES_PORT=*the port*
POSTGRES_DATABASE=defaultdb
POSTGRES_USER=*the user*
POSTGRES_PASSWORD=*the password*
POSTGRES_SCHEMA=projet

After this, you are able to reset the database to fill it, and then you can use the app.

To reset the database in case of need :

Download AtomicCards.json on https://mtgjson.com/downloads/all-files/

Put it in the root repository

Run embed_batch.py as a main to obtain all embeddings of the cards in the database

Start reset_database.py as a main to reset the database

To access the app :

Install all modules in requirements.txt :

pip install -r requirements.txt 

Have the src folder as the root for executing files :

• In the .env :

  PYTHONPATH="/home/onyxia/work/MagicSearch/src"

• Then do :

  export PYTHONPATH=/home/onyxia/work/MagicSearch/src:$PYTHONPATH

Then, you need to export an api token to use the features using embeddings :

• Go on https://llm.lab.sspcloud.fr/ << Settings << Account << copy the API token

• Put in the terminal :

  export API_TOKEN= followed by the token you just copied

Go to the module src/app.py :

• Run this python file
• At the bottom right of your screen, you should have a pop-up giving you the option to "Open in Browser", click it

When you want to close the API make sure to write Ctrl+C in your terminal !

To create all the cards embedding if necessary :

Execute embed_batch.py (takes approximately 30 minutes)

To create a card using the API:

The only mandatory arguments are id_card (to create a card, just keep 0, a new one is gonna get created), layout, name and type_line.

If you want to keep an argument empty :

• If it's a string or a int, you can write it as None
• If it's a list, keep the list empty
• If it's a dict, keep the dict empty

If you look at the model that should be used to create or update a card, you might notice that some arguments either are of a dict type or a list of dict.

Those arguments are : "foreign_data", "leadership_skills", "legalities", "purchase_urls" and "rulings".

None of those arguments are mandatory, therefore, if you don't want them to have any values, keep them with an empty dict or list.

Since the columns in those dict are fixed, you need to make sure to use the correct ones, so here's the template for each of those:

"foreignData" is a list of dict.

"foreignData": [
    {
        "language": "string",      # Mandatory
        "name": "string",          # Mandatory
        "faceName": "string",
        "flavorText": "string",
        "text": "string",
        "type": "string"
    }
]

For "leadership_skills", all of its column are mandatory.

"leadership_skills": {
    "brawl": bool,
    "commander": bool,
    "oathbreaker": bool
}

For legality, for each column, you either put "Banned", "Restricted" or "Legal". None of the columns are mandatory.

"legalities": {
    "commander": "string",
    "oathbreaker": "string",
    "duel": "string",
    "legacy": "string",
    "vintage": "string",
    "modern": "string",
    "penny": "string",
    "timeless": "string",
    "brawl": "string",
    "historic": "string",
    "gladiator": "string",
    "pioneer": "string",
    "predh": "string",
    "paupercommander": "string",
    "pauper": "string",
    "premodern": "string",
    "future": "string",
    "standardbrawl": "string",
    "standard": "string",
    "alchemy": "string",
    "oldschool": "string"
}

For "purchase_urls", none of the columns are mandatory.

"purchase_urls": {
    "tcgplayer": "string",
    "cardKingdom": "string",
    "cardmarket": "string",
    "cardKingdomFoil": "string",
    "cardKingdomEtched": "string",
    "tcgplayerEtched": "string"
}

For "rulings", it is a list of dict and all columns are mandatory. In the date column, make sure to follow the "YYYY-MM-DD" format.

"rulings": [
    {
        "date": "YYYY-MM-DD",
        "text": "string"
    }
]

To update a card using the API

The id_card you put is the card that is gonna get updated.

You need to still write everything you don't want to get changed. If you keep a column empty, the card will get updated to have no value in that column.

Otherwise, same rules as creating a card when it comes to the dict values.

To do a filtered search using the API

The input is a list of "filter" objects and an integer 'page', with the following format :

{
    "variable_filtered": "string",
    "type_of_filtering": "string",
    "filtering_value": "string" or int
}

"variable_filtered" is the variable on which we apply the filter

"type_of_filtering" is the way we want to apply the filter

"filtering_value" is a value around which the filter operates

The point of the input being a list of filters is that filters can be cumulative, by listing filters you get a more precise fit to your requirements (see the example).

The point of the integer is to page the results : instead of getting the thousands of cards matching your description you get for 'page'=1 the 50 first cards and for 'page'=2 the next 50 cards etc.

Categorical filter

"variable_filtered" : str 
    The filter can be applied only to the following list of categorical variables : 
    -"type" 
    -"color"

"type_of_filtering" : str 
    A filter on categorical variables can be applied in only two ways : 
    -"positive" : we select all the cards that have the "filtering_value" in the "variable_filtered" 
    -"negative" : we select all the cards EXCEPT the ones that have the "filtering_value" in the "variable_filtered"

"filtering_value" :str 
    Could be anything but, for your information:  
    -the variable "type" mostly has the modalities "Land", "Creature", "Enchantment", "Artifact", "Sorcerie", "Instant", "Interrupt" and "Planeswalker" 
    -the variable "color" mostly refers to "B" (black), "U" (blue), "R" (red), "W" (white), "G" (green)

Numerical filter

"variable_filtered" : str 
    The filter can be applied only to the following list of numerical variables : 
    -"power" 
    -"toughness" 
    -"manaValue" 
    -"edhrecRank"

"type_of_filtering" : str 
    A filter on categorical variables can be applied in only two ways : 
    -"higher_than" : we select all the cards that have a value in their "variable_filtered" higher than the "filtering_value" 
    -"equal_to": same idea 
    -"lower_than" : ditto

"filtering_value" :int 
    Could be anything.

An enlightening example

If you wish to find a card that has a high edhrecRank (higher than 1000) and that has also a fairly low manaValue (equal to 1) but that's not all ! This card just HAS to be a creature and be anything but blue !

Your input in the list of filters would be : [ { "variable_filtered": "edhrecRank", "type_of_filtering": "higher_than", "filtering_value": 1000 }, { "variable_filtered": "power", "type_of_filtering": "equal_to", "filtering_value": 1 }, { "variable_filtered": "type", "type_of_filtering": "positive", "filtering_value": "Creature" }, { "variable_filtered": "color", "type_of_filtering": "negative", "filtering_value": "U" } ]

To create an account using the API

Replace string next to username the with the username that you want and keep the quatation marks. Do the same for the password.

To login using the API

Fill in the username and password fields with the exact credentials you used when creating your account. For the password field, make sure to leave the word "password" as it is. The last three fields should be left empty.

Once you’ve entered your credentials, you will gain access to features based on your status (Admin or Not). To authenticate, enter the same information in the "Authorize" section to proceed.

To delete a user using the API

You can delete a user from the database only if you have Admin access. To do this, you will need to provide only the username of the user you want to delete.

To retrieve informations about a User knowing his id using the API

If you have Admin permissions, you can retrieve a user's information by entering their user ID. This will return the username, password, and permissions (Admin or Not) of the user.

To update a user using the API

You can update a user from the database only if you have Admin access. To do this, you will need to provide id of the user. Then, you can change the username and or the password.