This is the beauty of GraphQL. Rather than pulling all possible data from an endpoint like in REST APIs, GraphQL allows you to ask for only what you need. No extra data, no unnecessary overload. And what makes this experience even better is Python Strawberry, an easy-to-use library that allows you to set up GraphQL servers with Python.

In this extended journey, we’ll explore the core concepts of Strawberry, delve into some practical use cases. Let’s not only learn how to install and use Strawberry, but also dive deeper into the technical aspects of creating, mutating, and handling real-time data.

Step 1: Setting the Scene - Installing the Essentials

Before you embark on this seamless grocery shopping experience, you need the right tools. Just like how you wouldn't start grocery shopping without a cart, we need to install a few key packages to get Strawberry and GraphQL up and running.

To install the required packages, you’ll need to have Python 3.10+ installed. After that, Strawberry can be installed using pip:

pip install strawberry-graphql

If you want to integrate Strawberry with FastAPI (which we will later in the article), install the FastAPI package too:

pip install fastapi
pip install strawberry-graphql[fastapi]

You’ll also need Uvicorn, an ASGI server to run your FastAPI app:

pip install uvicorn

Now you’re all set to begin building with Strawberry!

Gathering the Right Ingredients

Think of installing these packages like gathering the ingredients you need for a recipe. You wouldn’t start cooking without the basics like flour, eggs, and milk. Similarly, you need these libraries to kick off your GraphQL adventure. Once you have them in place, you’re ready to start cooking up some awesome APIs.

Step 2: Understanding GraphQL Basics

Before diving into coding, let’s take a moment to appreciate why GraphQL is so powerful. Think of your data as a grocery store. In the traditional REST API world, you walk down every aisle (or hit every endpoint) to collect your items, but you often end up grabbing things you don’t need, like that family-size bag of chips (unwanted data). The REST API doesn’t let you be selective—either you get everything in the aisle, or nothing.

GraphQL flips this concept on its head. Instead of walking through every aisle, you simply hand over a precise shopping list (your query) to the store manager (the GraphQL server). The manager retrieves only the specific items you requested, down to the last strawberry. It’s efficient, precise, and saves you the headache of sifting through a pile of unnecessary data.

So, how do you get started with this neat querying system? Let’s jump into our first example.

Step 3: Creating Your First Query - Ask for Exactly What You Need

Let’s say you want to retrieve information about a particular fruit from a database (or your hypothetical grocery store). You’re only interested in a strawberry and its level of sweetness, not all the fruits available in the store. This is where GraphQL shines—you define what data you need and get exactly that.

Here's how you create a Strawberry Schema in Python to query specific fruit details:

import strawberry

@strawberry.type
class Fruit:
    name: str
    sweetness: int

@strawberry.type
class Query:
    @strawberry.field
    def get_fruit(self) -> Fruit:
        return Fruit(name="Strawberry", sweetness=8)

schema = strawberry.Schema(query=Query)

In this example, we define a Fruit type with two fields: name and sweetness. Then, we create a Query type that fetches a specific fruit. Here, the query always returns a strawberry with a sweetness level of 8.

Now that we’ve set up the schema, we can query it by executing a GraphQL request like this:

{
  getFruit {
    name
    sweetness
  }
}

The response:

{
  "data": {
    "getFruit": {
      "name": "Strawberry",
      "sweetness": 8
    }
  }
}

Customizing Your Grocery List

This is like telling the store manager, "I need only strawberries and I want them to have a sweetness level of 8." You’re being very specific with what you need, and the manager delivers exactly that. In contrast, if you had used a REST API, you might have received a whole fruit basket, with apples and bananas, even though you only wanted one type of fruit.

Step 4: Expanding Queries with Nested Fields

What if you want to know not only the fruit details but also information about the farm it came from? With GraphQL, you can use nested fields to get more detailed information in a single query. You’ll ask for strawberries, and also request details about the farm where they were grown.

@strawberry.type
class Farm:
    name: str
    location: str

@strawberry.type
class Fruit:
    name: str
    sweetness: int
    farm: Farm

@strawberry.type
class Query:
    @strawberry.field
    def get_fruit(self) -> Fruit:
        return Fruit(
            name="Strawberry",
            sweetness=8,
            farm=Farm(name="Sunny Farms", location="California")
        )

schema = strawberry.Schema(query=Query)

Now, when you query for a fruit, you can also request information about the farm:

{
  getFruit {
    name
    sweetness
    farm {
      name
      location
    }
  }
}

The Response:

{
  "data": {
    "getFruit": {
      "name": "Strawberry",
      "sweetness": 8,
      "farm": {
        "name": "Sunny Farms",
        "location": "California"
      }
    }
  }
}

Asking for More Details

Imagine you walk up to the store manager and say, “I’d like to know more about these strawberries—where are they from?” The manager provides you with not only the strawberries but also the name of the farm and its location. This nested query feature in GraphQL helps you get exactly what you want, without the extra clutter.

Step 5: Mutations - Making Changes to Your Grocery List

What if you want to add a new item to your cart while shopping? In GraphQL, this is called a mutation. Mutations allow you to modify data on the server, such as adding, updating, or deleting records.

Here’s an example of adding a new fruit using a mutation:

@strawberry.type
class Mutation:
    @strawberry.mutation
    def add_fruit(self, name: str, sweetness: int) -> Fruit:
        return Fruit(name=name, sweetness=sweetness)

schema = strawberry.Schema(query=Query, mutation=Mutation)

To execute the mutation:

mutation {
  addFruit(name: "Blueberry", sweetness: 6) {
    name
    sweetness
  }
}

The Response:

{
  "data": {
    "addFruit": {
      "name": "Blueberry",
      "sweetness": 6
    }
  }
}

Changing Your Grocery List on the Fly

This is like telling the store manager, “Hey, I want to add some blueberries to my cart.” The manager doesn’t hesitate—they promptly update your cart with the new item. Similarly, mutations allow you to adjust data in real-time, adding or changing items as needed.

Step 6: Real-Time Updates with Subscriptions

Let’s say you’re waiting for fresh strawberries to be restocked at the store. Wouldn’t it be great if you could get notified the moment new strawberries are available? This is where GraphQL subscriptions come in handy. Subscriptions allow you to listen for real-time updates from the server.

In Strawberry, setting up a subscription is easy:

import asyncio

@strawberry.type
class Subscription:
    @strawberry.subscription
    async def new_fruit(self) -> Fruit:
        await asyncio.sleep(1)
        return Fruit(name="Strawberry", sweetness=9)

schema = strawberry.Schema(query=Query, subscription=Subscription)

You can subscribe to this real-time data by executing a GraphQL subscription query:

subscription {
  newFruit {
    name
    sweetness
  }
}

This setup will notify you when a new fruit is added or updated.

Waiting for Fresh Stock

Imagine you’re waiting for the latest batch of fresh strawberries to arrive. Instead of constantly checking the produce section, the store manager promises to notify you the moment they’re available. Similarly, with GraphQL subscriptions, you can wait for real-time updates and be notified immediately when changes occur.

Step 7: Integrating Strawberry with FastAPI - A Seamless Checkout

What good is a grocery trip without a seamless checkout? FastAPI is like the lightning-fast cashier, ensuring that your requests are processed with minimal wait time. Integrating Strawberry with FastAPI is incredibly simple, and it combines the power of GraphQL with the speed and efficiency of FastAPI.

Here’s how you can set it up:

import strawberry
from fastapi import FastAPI
from strawberry.fastapi import GraphQLRouter

@strawberry.type
class Query:
    @strawberry.field
    def get_fruit(self) -> str:
        return "Strawberry"

schema = strawberry.Schema(query=Query)
graphql_app = GraphQLRouter(schema)

app = FastAPI()
app.include_router(graphql_app, prefix="/graphql")

Smooth Checkout

At the end of your grocery run, you want to ensure the checkout is fast and painless. FastAPI, in this analogy, is the cashier who scans your items with lightning speed, ensuring that you get in and out efficiently. Strawberry, integrated with FastAPI, ensures your data requests are processed just as quickly and smoothly.

Conclusion: The Perfect Grocery Store Experience with Strawberry and GraphQL

By the time you walk out of the store, you're carrying the exact items you wanted, nothing more, nothing less. And this is the magic of Python Strawberry—it gives you precision, flexibility, and control over your API requests, ensuring efficient data handling every step of the way.

From querying to mutations, real-time subscriptions to error handling, Strawberry simplifies the complex world of GraphQL with elegance. And when paired with FastAPI, it’s like having the ultimate grocery store experience—efficient, flexible, and always responsive to your needs.

So, the next time you’re thinking about API design, imagine yourself in that grocery store, requesting only what you need, when you need it.

The King’s Vision: Why Choose Beanie?

Every great kingdom needs a clear vision. You wouldn’t want your kingdom’s libraries (databases) to be cluttered, your roads (data flow) blocked, or your citizens waiting in line for ages (latency). This is where Beanie shines. Beanie is your kingdom’s wise advisor, managing data effectively, without the headaches of manual bookkeeping (CRUD operations).

Why Beanie?

• Asynchronous: Like a team of knights who can joust, guard, and entertain the crowd all at once, Beanie handles multiple database operations simultaneously without slowing down.

• Pydantic-powered models: Beanie ensures that the data entering the kingdom follows the correct protocols (data validation), so no one sneaks in with invalid passports (bad data).

• Schema migrations: Need to add a new wing to your castle? No problem! Beanie allows you to expand your data model seamlessly without disturbing the foundation.

Now that we know what Beanie can do for your kingdom, let’s start building!

Step 1: Building the Castle’s Foundation (Setting Up Beanie and FastAPI)

No kingdom can function without a castle. In our case, the castle is your backend—built using Beanie, MongoDB, and FastAPI. But before we lay the first brick, we need to install the right tools to ensure our kingdom runs like a well-oiled machine.

pip install fastapi beanie motor uvicorn

• FastAPI is the front gate of your castle, allowing citizens to interact with your kingdom through API endpoints.

• Beanie is the architect, keeping the data organized and accessible.

• Motor is the messenger, ensuring communication between your kingdom (app) and MongoDB.

• Uvicorn is the herald, broadcasting your kingdom’s greatness to the world (by running the development server).

Step 2: Drafting the Blueprints (Modeling with Beanie)

Before you start constructing new buildings in your kingdom, you need blueprints for each structure. These blueprints will ensure that all your houses (data documents) are built correctly and are easy to maintain.

In Beanie, blueprints are created using Pydantic models. Let’s design the citizens of your kingdom (user profiles):

from beanie import Document, init_beanie
from pydantic import BaseModel
from motor.motor_asyncio import AsyncIOMotorClient
from fastapi import FastAPI
import asyncio

# Define a Document model with Beanie
class Citizen(Document):
    name: str
    profession: str
    loyalty_points: int = 0  # Every citizen starts out loyal... for now.

    class Settings:
        collection = "citizens"

# FastAPI app initialization
app = FastAPI()

# Database connection and Beanie initialization
async def init_db():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    database = client["kingdom_db"]
    await init_beanie(database, document_models=[Citizen])

@app.on_event("startup")
async def on_startup():
    await init_db()

Breaking It Down:

• Citizen is your user profile model—a blueprint for each citizen in your kingdom. It contains attributes like name, profession, and loyalty_points.

• The Settings class specifies which collection these citizens will be stored in (citizens). Think of it as deciding whether to put your citizens in the town square or the royal archives.

• init_db is the magic that connects your kingdom (app) to MongoDB, ensuring all data is organized neatly.

Step 3: Making Royal Decrees (Creating FastAPI Endpoints)

Every monarch needs a way to communicate with their people. In this case, your royal decrees are API endpoints that allow users to interact with the kingdom.

Let’s create a decree for adding new citizens to the kingdom and checking on their status:

# Endpoint to create a new citizen
@app.post("/citizen")
async def create_citizen(citizen: Citizen):
    await citizen.insert()
    return {"message": "Citizen has been added to the kingdom!"}

# Endpoint to get a citizen’s information
@app.get("/citizen/{name}")
async def get_citizen(name: str):
    citizen = await Citizen.find_one(Citizen.name == name)
    if citizen:
        return citizen
    return {"error": "Citizen not found in the archives!"}

The Royal Analogy:

• create_citizen is like opening the castle gates and letting a new citizen into the kingdom. They are added to the royal records (database).

• get_citizen is like sending a scribe to check on a specific citizen’s details in the royal archives. If they exist, the scribe brings back their information; if not, the scribe returns empty-handed.

Step 4: Running the Kingdom Smoothly (Handling Complex Queries)

As your kingdom grows, you’ll need a more efficient way to manage resources and citizens. You don’t want to check each one manually, right? Let’s automate some of the royal duties by adding an endpoint to retrieve all loyal citizens.

@app.get("/citizens/loyal")
async def get_loyal_citizens():
    loyal_citizens = await Citizen.find(Citizen.loyalty_points >= 50).to_list()
    return loyal_citizens

The Royal Analogy:

Imagine you’re organizing a grand feast, but you only want to invite citizens who’ve been particularly loyal. Instead of checking every name in the archives, you send out an automated decree to retrieve only those who have loyalty_points above a certain number. This is your royal banquet guest list.

Step 5: Expanding the Castle (Schema Migrations)

As your kingdom prospers, you might want to add new buildings, like a library or a blacksmith’s forge. Similarly, in Beanie, you’ll eventually need to expand your data models without breaking existing functionality.

Let’s say you want to track each citizen’s favorite tavern. Easy! Just add a new field to your Citizen model:

class Citizen(Document):
    name: str
    profession: str
    loyalty_points: int = 0
    favorite_tavern: Optional[str] = None

    class Settings:
        collection = "citizens"

The Royal Analogy:

This is like adding a new wing to your castle. You don’t need to demolish the whole building—just add the new feature and continue as usual. Beanie handles these “renovations” with grace, ensuring no data is lost during the process.

Step 6: Royal Predictions

As a wise ruler, you want to stay ahead of the game. How can you predict which citizens are most likely to stay loyal? By analyzing past behavior, of course! With Beanie’s querying capabilities, you can predict future trends based on historical data.

Here’s how to fetch the top 5 most loyal citizens:

@app.get("/citizens/top_loyal")
async def predict_loyalty():
    loyal_citizens = await Citizen.find().sort("-loyalty_points").limit(5).to_list()
    return loyal_citizens

The Royal Analogy:

Imagine your kingdom’s knights taking a vote on who’s most likely to defend the castle in a crisis. You can look at past battles (loyalty points) to predict which citizens will rise to the occasion. Similarly, this query pulls the top citizens based on loyalty, giving you a shortlist of who’s most loyal.

Step 7: Protecting the Realm (Ensuring Data Consistency)

No kingdom is complete without proper defenses! You wouldn’t let just anyone into the castle, would you? Similarly, you need to protect your data with validation and consistency checks to keep things in order.

Here’s how to validate that every new citizen has a proper profession:

class Citizen(Document):
    name: str
    profession: str
    loyalty_points: int = 0
    favorite_tavern: Optional[str] = None

    @root_validator
    def validate_profession(cls, values):
        profession = values.get("profession")
        if profession not in ["Knight", "Mage", "Peasant"]:
            raise ValueError("Invalid profession!")
        return values

The Royal Analogy:

This is your kingdom’s security guard. Every time someone tries to enter, the guard checks their credentials to ensure they belong. No imposters allowed! The validation ensures every new citizen has a valid profession, keeping the kingdom orderly.

Conclusion: Building Your Data Kingdom with Beanie and FastAPI

By now, you've gone from ruling over a small village to commanding a vast, data-driven kingdom—all thanks to the powers of Beanie and FastAPI. From creating blueprints (data models) to managing citizens (documents) efficiently, you’ve built a kingdom that runs like clockwork.

Just like any great kingdom, your app is scalable, flexible, and ready to grow. Beanie’s asynchronous power means that no matter how many new citizens arrive, you’re always ready to handle them—without breaking a sweat.

As a proud ruler, I’d like to share that I have developed an application that interacts with a fine-tuned model (or any other model) using Python Beanie and FastAPI. You can explore the code and its functionalities by visiting my GitHub repository.

You have probably heard about Gemini AI already. Gemini is a family of generative AI models that can generate content and solve problems. There are different models with their own set of capabilities. We will be focusing on the Gemini 1.0 Pro model. Throughout this tutorial, we will be using the name gemini-pro. It is an alias for Gemini 1.0 Pro. To know more about gemini models, Refer Here.

We will be creating an AI Chat Bot powered by Gemini AI, with JWT authentication using python.

You can find the complete code on my Github repo: Converse3.0

Tech Stack

• Python

• Flask

• PostgreSQL

• Docker

Let's Start

Obtain API Key to use Gemini

1. Go to Google AI Studio

2. Login with google account

3. Create API Key

Install PostgreSQL

Download and install postgreSQL, from here. Go with the latest version.

If you are using linux, make sure that you install libpq-dev

• Linux (with apt package manager)

    sudo apt-get install libpq-dev
  

Install Docker (Optional)

Installing docker is completely optional. Having the Dockerfile and docker compose setup will help in faster deployment.

You can also spin up a docker container for postgreSQL instead of installing it in your system.

docker run -d \
  --name gemini_postgres \
  -p 5432:5432 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password\
  -e POSTGRES_DB=postgres\
  postgres:latest

Postgres now accessible on port 5432.

Setup Environment

Create Virtual Environment

python -m venv venv

Activate Virtual Environment

• Windows (CMD)

    venv\Scripts\activate
  

• Mac/Linux

    source venv/bin/activate
  

Install Python Packages

With the virtual environment activated, you can install Python packages using pip.

pip install Flask
pip install Flask-JWT-Extended
pip install Flask-SQLAlchemy
pip install Flask-Cors

• Flask is a lightweight and flexible web framework for Python

• Flask-JWT-Extended - provides support for JSON Web Tokens (JWTs). We will be using JWTs for implementing authentication and authorization in this web application.

• Flask-SQLAlchemy - integrates SQLAlchemy with Flask. We will be using SQLAlchemy to interact with PostgreSQL.

• Flask-Cors - enables Cross-Origin Resource Sharing (CORS)

pip install psycopg2

• Psycopg2 is a PostgreSQL database adapter

pip install python-decouple

• Decouple helps in loading values from .env files

pip install jsonpickle

• jsonpickle helps in the conversion of complex python object to JSON and vice-versa. We will use this library to convert and store the chat history.

Install Python SDK for Gemini API

pip install google-generativeai

Start Coding

Configure Python Decouple

Python decouple automatically picks up .env file. But, since we are also planning to deploy the application into production, we need it to pick up a different .env when in production environment. So, rather than using the default config provided by decouple, we will create a method to return a decouple config which includes our additional logic.

import os
import decouple
from decouple import RepositoryEnv
import pathlib


class DecoupleConfigUtil:

    @classmethod
    def get_env_config(cls) -> decouple.Config:
        """
        Creates and returns a Config object based on the environment setting.
        It uses .env for development and .prod.env for production.
        """

        ENVIRONMENT = os.getenv("ENVIRONMENT", default="DEVELOPMENT")

        env_files = {
            "DEVELOPMENT": ".env",
            "PRODUCTION": ".env.prod",
        }

        app_dir_path = pathlib.Path(__file__).resolve().parent.parent
        env_file_name = env_files.get(ENVIRONMENT, ".env")
        file_path = app_dir_path / env_file_name

        if not file_path.is_file():
            raise FileNotFoundError(f"Environment file not found: {file_path}")

        return decouple.Config(RepositoryEnv(file_path))

We create this class inside utils package. This would check for an environment variable called "ENVIRONMENT" in the system. According to the variable's value, it would decide from which .env, it should take the configurations from.

In the production environment, it would take values from .env.prod. So, make sure that you have this file when deploying the application to production.

You can add these values to the .env file:

APP_SECRET_KEY=this_is_my_secret_key
JWT_SECRET_KEY=this_is_my_secret_jwt_secret_key

CORS_ORIGINS=http://localhost:5173,http://localhost:4173

DATABASE_URI=postgresql://postgres:password@localhost:5432/postgres

HOST=0.0.0.0
PORT=8000

GOOGLE_API_KEY=AIzaSyDTzAF3jNsbktskJLC_EIBz0_QKPFdnHds

Create file for storing static messages

We create a messages.py file to store all the static messages we need.

USERNAME_REQUIRED = "Username is required"
PASSWORD_REQUIRED = "Password is required"
USERNAME_EXISTS = "Username already exists"
USER_REGISTRATION_SUCCESSFUL = "User has been successfully registered"

INVALID_USERNAME_PASSWORD = "Username or Password is invalid"

INVALID_PROMPT = "Provided prompt is invalid"

CHAT_HISTORY_LIST_RETRIEVED = "Chat history list has been successfully retrieved"
CHAT_HISTORY_RETRIEVED = "Chat history has been successfully retrieved"
CHAT_HISTORY_UNAVAILABLE = "Chat history is not available"

CHAT_RESPONSE_NOT_SAFE = "Chat response is not safe to be viewed publicly"
CHAT_NOT_FOUND = "Chat not found. Please provide correct details"

Create Models

We create models using SQLAlchemy and place these models inside the models package.

models.py

from flask_sqlalchemy import SQLAlchemy


db = SQLAlchemy()


def bulk_save_objects(objects):
    db.session.bulk_save_objects(objects)
    db.session.commit()


def delete_objects(objects):
    for obj in objects:
        db.session.delete(obj)

    db.session.commit()

Here, we initialize an instance of SQLAlchemy. This instance will be used to create further models. We also define two methods to bulk save objects and bulk delete objects.

user.py

from models.models import db
from models.document import Document
from werkzeug.security import generate_password_hash, check_password_hash


class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    password_hash = db.Column(db.String(256), nullable=False)

    documents = db.relationship(Document, back_populates="user")

    def __repr__(self):
        return "<User %r>" % self.username

    def set_password(self, password):
        self.password_hash = generate_password_hash(password)

    def check_password(self, password):
        return check_password_hash(self.password_hash, password)

    def save(self):
        db.session.add(self)
        db.session.commit()

We specify relationship between User model and Document model.

document.py

from models.models import db


class Document(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    document_name = db.Column(db.String(80), nullable=False)
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"), nullable=False)

    user = db.relationship("User", back_populates="documents")

    def __repr__(self):
        return "<UploadedDocuments %r>" % self.document_name

    def save(self):
        db.session.add(self)
        db.session.commit()

The Document model has a one-one relationship with the User model.

normal_chat_history.py

from models.models import db
from datetime import datetime


class NormalChatHistory(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    chat_history = db.Column(db.JSON)
    started_at = db.Column(db.DateTime, default=datetime.utcnow)
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"), nullable=False)

    def __repr__(self):
        return "<NormalChatHistory %r>" % self.id + "-" + self.user_id

    def save(self):
        db.session.add(self)
        db.session.commit()

The chat history is stored in JSON format. NormalChatHistory model has a one-one relationship with the User model.

Create Auth Controllers

User Registration

We place the controllers inside the controllers package.

register.py

from flask import request

from utils.common_response import CommonResponse
from service.user_registration import UserRegistration


def register():
    username = request.json.get("username", None)
    password = request.json.get("password", None)

    user_registration = UserRegistration()
    message, status = user_registration.register(username, password)

    return CommonResponse(message, status).format_response()

We also create custom response files to structure the response as we want. Create a file called common_response.py in utils package.

common_response.py

from flask import jsonify


class CommonResponse:

    def __init__(self, message, status, data=None) -> None:
        self.message = message
        self.status = status
        self.data = data

    def format_response(self):
        return (
            jsonify({"message": self.message, "data": self.data}),
            self.status,
        )

User Login

We place it in the controllers package.

login.py

from flask import request

from utils.login_response import LoginResponse
from utils.common_response import CommonResponse
from service.user_login import UserLogin


def login():
    username = request.json.get("username", None)
    password = request.json.get("password", None)

    user_login = UserLogin()
    response, status = user_login.login(username, password)
    if status != 200:
        return CommonResponse(response, status)
    else:
        return LoginResponse(response, status)

Create a file called login_response.py in utils package.

login_response.py

from flask import jsonify


class LoginResponse:

    def __init__(self, access_token, status) -> None:
        self.access_token = access_token
        self.status = status

    def format_response(self):
        return (
            jsonify({"access_token": self.access_token}),
            self.status,
        )

Create Auth Services

User Registration

We place the service classes inside the services package. This file will contain all the logic required for registering a new user.

user_registration.py

from models.user import User
from messages import (
    PASSWORD_REQUIRED,
    USER_REGISTRATION_SUCCESSFUL,
    USERNAME_EXISTS,
    USERNAME_REQUIRED,
)


class UserRegistration:

    def register(self, username, password):
        if not username:
            message = USERNAME_REQUIRED
            status = 400
        elif not password:
            message = PASSWORD_REQUIRED
            status = 400
        elif User.query.filter_by(username=username).first():
            message = USERNAME_EXISTS
            status = 400
        else:
            new_user = User(username=username)
            new_user.set_password(password)
            new_user.save()
            message = USER_REGISTRATION_SUCCESSFUL
            status = 201

        return message, status

User Login

This file will contain all the logic required for successfully logging in a valid user.

user_login.py

from flask_jwt_extended import create_access_token

from messages import INVALID_USERNAME_PASSWORD
from models.user import User


class UserLogin:

    def login(self, username, password):
        user = User.query.filter_by(username=username).first()
        if user and user.check_password(password):
            additional_claims = {"user_id": user.id}
            access_token = create_access_token(
                identity=username, additional_claims=additional_claims
            )
            return access_token, 200
        else:
            return INVALID_USERNAME_PASSWORD, 400

Add these lines to main.py:

main.py

from flask import Flask
from flask_cors import CORS
from flask_jwt_extended import JWTManager

from messages import CHAT_NOT_FOUND, CHAT_RESPONSE_NOT_SAFE
from exceptions import ChatNotFoundException, SafetyException
from models.models import db
from utils.decouple_config_util import DecoupleConfigUtil
from utils.common_response import CommonResponse
from controllers.register import register
from controllers.login import login
from controllers.normal_ai_chat import (
    NormalAiChat,
    NormalAiChatHistory,
    NormalAiChatHistoryList,
    deleteNormalAiChatHistory,
)


config = DecoupleConfigUtil.get_env_config()

app = Flask(__name__)
app.secret_key = config("APP_SECRET_KEY")

app.config["SQLALCHEMY_DATABASE_URI"] = config("DATABASE_URI")
app.config["JWT_SECRET_KEY"] = config("JWT_SECRET_KEY")

db.init_app(app)
jwt = JWTManager(app)

CORS(
    app,
    origins=config(
        "CORS_ORIGINS", cast=lambda v: [item.strip() for item in v.split(",")]
    ),
)

with app.app_context():
    db.create_all()


app.route("/register", methods=["POST"])(register)
app.route("/login", methods=["POST"])(login)

if __name__ == "__main__":
    app.run(host=config("HOST"), port=config("PORT"))

• Initialize the Flask application

• Initialize the DB

• Specify the API routes

Chat with AI

Custom Exceptions

Create custom exceptions and place it in exceptions.py.

class SafetyException(Exception):
    pass


class ChatNotFoundException(Exception):
    pass

We create an abstract class in client/ai_models. This abstract class will serve as the parent class for the other AI model classes.

ai_model.py

from abc import ABC, abstractmethod


class AIModel(ABC):

    @abstractmethod
    def chat(chat_history):
        pass

    @abstractmethod
    def get_chat_history():
        pass

Gemini AI Model

Since we are using Gemini as our AI model, we will put all the Gemini related files inside client/ai_models/gemini.

First, lets setup the required configurations in config.py.

config.py

from utils.decouple_config_util import DecoupleConfigUtil


config = DecoupleConfigUtil.get_env_config()


GOOGLE_API_KEY = config("GOOGLE_API_KEY")
GEMINI_MODEL_NAME = config("GEMINI_MODEL_NAME")

gemini_ai_model.py

import google.generativeai as genai
from google.generativeai.types.generation_types import StopCandidateException
import logging

from client.ai_models.ai_model import AIModel
from client.ai_models.gemini.config import GEMINI_MODEL_NAME, GOOGLE_API_KEY
from exceptions import SafetyException


logging.basicConfig(
    filename="app.log",
    level=logging.DEBUG,
    format="%(asctime)s %(levelname)s %(name)s %(threadName)s : %(message)s",
)

logger = logging.getLogger(__name__)


class GeminiAIModel(AIModel):

    def __init__(self, model_name=GEMINI_MODEL_NAME) -> None:
        genai.configure(api_key=GOOGLE_API_KEY, transport="rest")
        self.model = genai.GenerativeModel(model_name)

    def chat(self, prompt, chat_history):
        try:
            self.chat = self.model.start_chat(history=chat_history)
            response = self.chat.send_message(prompt)
            content_parts = response.candidates[0].content.parts[0]
            return content_parts.text
        except StopCandidateException as sce:
            logger.error(sce)
            raise SafetyException()

    def get_chat_history(self):
        if self.chat:
            return self.chat.history
        return []

• Initializes the Google AI python SDK with the necessary values to interact with Gemini

• chat method to chat with the AI model

• Raises the custom exception SafetyException if the StopCandidateException is caught

• get_chat_history method to get the entire history of that chat

Create AI Chat Controllers

In the controllers package, create file called normal_ai_chat.py.

normal_ai_chat.py

from flask import request
from flask_jwt_extended import get_jwt, jwt_required

from client.ai_models.gemini.gemini_ai_model import GeminiAIModel
from utils.common_response import CommonResponse
from messages import (
    CHAT_HISTORY_LIST_RETRIEVED,
    CHAT_HISTORY_RETRIEVED,
    CHAT_HISTORY_UNAVAILABLE,
    INVALID_PROMPT,
)
from service.normal_ai_chatter import NormalAiChatter
from utils.chat_response import ChatResponse


@jwt_required()
def NormalAiChat():
    prompt = request.json.get("prompt", None)
    chat_id = request.json.get("chat_id", None)
    user_id = get_jwt().get("user_id", None)

    if prompt:
        gemini_ai_model = GeminiAIModel()
        normal_chatter = NormalAiChatter(gemini_ai_model)
        ai_response, chat_id = normal_chatter.chat(prompt, chat_id, user_id)
        status = 200
    else:
        ai_response = INVALID_PROMPT
        status = 400

    return ChatResponse(ai_response, chat_id, status).format_response()

• Calls the Gemini model with the user prompt

@jwt_required()
def NormalAiChatHistoryList():
    user_id = get_jwt().get("user_id", None)

    normal_chatter = NormalAiChatter()
    chat_list = normal_chatter.get_chat_history_list(user_id)
    status = 200

    return CommonResponse(CHAT_HISTORY_LIST_RETRIEVED, status, chat_list).format_response()

• Retrieves the list of chats the user has made with the model

@jwt_required()
def NormalAiChatHistory():
    user_id = get_jwt().get("user_id", None)
    chat_id = request.args.get("chat_id", None)

    normal_chatter = NormalAiChatter()
    chat_history = normal_chatter.get_chat_history(user_id, chat_id)
    if chat_history:
        status = 200
        return CommonResponse(CHAT_HISTORY_RETRIEVED, status, chat_history).format_response()

    status = 404
    return CommonResponse(CHAT_HISTORY_UNAVAILABLE, status, None).format_response()

• Retrieves all the contents of a particular chat

@jwt_required()
def deleteNormalAiChatHistory():
    user_id = get_jwt().get("user_id", None)
    chat_id = request.args.get("chat_id", None)

    normal_chatter = NormalAiChatter()
    normal_chatter.delete_chat_history(user_id, chat_id)

    status = 204
    return "", status

• Delete chats based on user_id and chat_id

Create a file called chat_response.py in utils package.

chat_response.py

from flask import jsonify


class ChatResponse:

    def __init__(self, ai_response, chat_id, status) -> None:
        self.ai_response = ai_response
        self.chat_id = chat_id
        self.status = status

    def format_response(self):
        return (
            jsonify(
                {
                    "ai_response": self.ai_response,
                    "chat_id": self.chat_id,
                }
            ),
            self.status,
        )

Create AI Chat Service

We will create a file in the services package that handles chatting with the AI model.

normal_ai_chatter.py

import jsonpickle

from exceptions import ChatNotFoundException
from models.models import delete_objects
from models.normal_chat_history import NormalChatHistory


class NormalAiChatter:

    def __init__(self, model=None) -> None:
        self.model = model

    def chat(self, prompt, chat_id, user_id):
        chat_history = []
        if chat_id:
            normal_chat_history = (
                NormalChatHistory.query.filter_by(user_id=user_id)
                .filter_by(id=chat_id)
                .first()
            )
            if not normal_chat_history:
                raise ChatNotFoundException()
            chat_history = jsonpickle.decode(normal_chat_history.chat_history)
        else:
            normal_chat_history = NormalChatHistory(
                chat_history=chat_history, user_id=user_id
            )
            normal_chat_history.save()
            chat_id = normal_chat_history.id

        ai_response = self.model.chat(prompt, chat_history)
        self.save_chat_history(normal_chat_history)

        return ai_response, chat_id

    def save_chat_history(self, normal_chat_history):
        chat_history = self.model.get_chat_history()
        chat_history_json_string = jsonpickle.encode(chat_history)
        normal_chat_history.chat_history = chat_history_json_string
        normal_chat_history.save()

        return True

• If there is a chat_id, then it will fetch the chat history corresponding to that chat_id. Otherwise, it would create a new chat.

• After getting the response from the model, it would save the entire chat history.

def get_chat_history_list(self, user_id):
        chat_history_list = NormalChatHistory.query.filter_by(user_id=user_id).all()
        chat_list = [
            {"chat_id": chat.id, "chat_name": chat.started_at}
            for chat in chat_history_list
        ]

        return chat_list

• Get the list of all the chats of the particular user

def get_chat_history(self, user_id, chat_id):
        normal_chat_history = (
            NormalChatHistory.query.filter_by(user_id=user_id)
            .filter_by(id=chat_id)
            .first()
        )

        if normal_chat_history:
            chat_history = jsonpickle.decode(normal_chat_history.chat_history)
            chat_history_data = {
                "chat_id": chat_id,
                "chat_history": [
                    {"text": chat.parts[0].text, "role": chat.role}
                    for chat in chat_history
                ],
            }
            return chat_history_data

        return []

• Get all the contents of a particular chat of that user

def delete_chat_history(self, user_id, chat_id):
        if chat_id:
            normal_chat_history = (
                NormalChatHistory.query.filter_by(user_id=user_id)
                .filter_by(id=chat_id)
                .all()
            )
        else:
            normal_chat_history = NormalChatHistory.query.filter_by(
                user_id=user_id
            ).all()

        delete_objects(normal_chat_history)

        return True

• Delete a particular chat of the user if the chat_id is provided

• Delete all the chats of the user if the chat_id is not provided

Add Chat Routes

Update main.py with the following routes.

main.py

from controllers.normal_ai_chat import (
    NormalAiChat,
    NormalAiChatHistory,
    NormalAiChatHistoryList,
    deleteNormalAiChatHistory,
)


app.route("/normal_chat_with_ai", methods=["POST"])(NormalAiChat)
app.route("/normal_chat_history_list", methods=["GET"])(NormalAiChatHistoryList)
app.route("/normal_chat_history", methods=["GET"])(NormalAiChatHistory)
app.route("/normal_chat_history_list", methods=["DELETE"])(deleteNormalAiChatHistory)

Handle Custom Exceptions

Update main.py with the following code.

main.py

@app.errorhandler(SafetyException)
def handle_safety_exception(error):
    status = 403
    return CommonResponse(CHAT_RESPONSE_NOT_SAFE, status, None).format_response()


@app.errorhandler(ChatNotFoundException)
def handle_chat_not_found_exception(error):
    status = 404
    return CommonResponse(CHAT_NOT_FOUND, status, None).format_response()

Run the Application

We can now run the application by executing:

python main.py

• Make sure that PostgreSQL is already up and configured correctly

• Ensure that the correct details are provided in the .env file

• You can access the application on http://localhost:8000

Dockerize the Application (Optional)

Add these lines to the Dockerfile.

Dockerfile

FROM python:3.10-bookworm

ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONUNBUFFERED 1
ENV ENVIRONMENT DEVELOPMENT

WORKDIR /app

RUN apt-get update -y 
RUN apt-get install -y git ca-certificates
RUN apt-get update && \
    apt-get install -y \
    python3-dev \
    libpq-dev \
    libmariadb-dev \
    build-essential \
    cmake \
    swig \
    pkgconf

RUN apt-get install curl
RUN curl -k -L https://github.com/jwilder/dockerize/releases/download/v0.6.1/dockerize-linux-amd64-v0.6.1.tar.gz | tar -C /usr/local/bin -xzv

COPY requirements.txt /app/
RUN pip install wheel
RUN pip install --upgrade pip
RUN pip install pyarrow
RUN pip install pyOpenSSL
RUN pip install -r requirements.txt

COPY . /app/

EXPOSE 5000
EXPOSE 8000

RUN chmod +x deploy.sh

CMD ["python", "main.py"]

Run in Production

To run the application in production, use a WSGI server like Gunicorn to serve the Flask application.

Add the configurations in .prod.env instead of .env when in production

Imagine you're a magician performing a trick where you’re about to make a card disappear, but not just for the audience—the card will vanish from the view of everyone, including yourself, the magician. It sounds impossible, right? Yet, in the cryptographic world, Chaumian Blinding pulls off a similar trick, but with financial transactions. It keeps the who, what, and when of the transaction a mystery to even the central authority (like a bank) involved.

Developed by the cryptographer David Lee Chaum in his paper “Blind Signature for Untraceable Payments”, this technique essentially makes transactions anonymous to even the very people who approve them! Imagine doing something and not knowing exactly what you did, yet still getting it right—how wild is that?

The Players: Adrian, Becky, and the Trusting Bank

Let’s take a normal bank transaction between Adrian and Becky. Without any fancy tech, the bank knows who sent money to whom, how much was sent, and when. So much for privacy, huh?

Enter Chaumian Blinding. With this clever technique, Adrian can send money to Becky, and the bank won’t know a thing about who sent it or how much was involved. It’s like Adrian sent an invisible package through the bank—one they approve, but can’t open.

So, how do we make that happen?

The Secret Sauce: Functions and Trust

Chaumian Blinding revolves around a few special functions, each playing a role in our little magic act:

1. S (The Signing Function): Known only to the bank, S is like the bank’s magic seal that says, “Yep, this is legit.” Its inverse, S', is publicly known and used to verify the bank’s seal.

2. C (The Commuting Function): Adrian’s personal encryption trick. It scrambles his certificate (which contains the money and serial number) into cipher text. Only Adrian knows how to scramble and, more importantly, unscramble with C’.

3. r (Redundancy Check): Let’s not let any funny business slip through. This checks if the certificate makes sense. Think of it like spell-check, but for transactions.

The Magic Act Begins

So here’s how the trick unfolds:

Adrian wants to pay Becky. To do that, he needs the bank to approve his transaction by signing a certificate. This certificate includes the amount to be debited and a serial number. But here’s the thing: Adrian doesn’t want the bank snooping on his personal details.

So, what does he do? He encrypts the certificate using C, turning the details into gibberish.

Adrian’s encrypted certificate (Cipher text) -> Sent to the bank

Now, the bank sees this encrypted mumbo-jumbo but, surprisingly, they’re cool with it. They’ve entered into what’s called blind trust with Adrian. More on that in a bit.

The bank then uses their signing function S on the encrypted data:

S(Certificate, but scrambled) -> Signed by the bank

At this point, Adrian receives back his now-bank-approved certificate, still encrypted. But here’s the clever bit: Adrian applies his C’ function (the unscrambling one), and—presto!—he’s got a legitimate, bank-signed certificate without ever revealing the original details to the bank.

Ta-da! Becky Gets Paid

Adrian sends this freshly signed certificate to Becky. Becky, being the practical one in this whole ordeal, uses S’ (the public verification function) to check that everything’s in order:

Signed Certificate -> Verified by Becky -> Becky sends it to the bank

The bank then credits Becky’s account, all without ever knowing who sent the payment. It’s like Becky got an anonymous tip, but in cold hard cash.

Blind Trust: The Foolproof Magic Trick

Now, how does the bank make sure Adrian’s not pulling a fast one? The answer lies in blind trust.

Imagine the bank says, “Adrian, send me 1,000 copies of the certificate you want me to sign. They should all have the same amount of money, but different serial numbers.”

Adrian, who’s all in on this deal, sends over 1,000 certificates (one of which is the real one). The bank, in turn, picks 999 of them at random and says, “Show me the keys to decrypt these.”

Adrian obliges. The bank checks, and if all 999 decrypted certificates have the same amount of money, it signs the remaining one—blindly trusting that it, too, contains the same amount.

Chaumian Blinding in Real Life

Think of this process like a “choose-your-own-adventure” story, but every page is scrambled, and the person approving the story can only read random snippets. They trust that, based on the snippets they’ve seen, the rest of the story makes sense. It’s a leap of faith—wrapped in math.

In essence, Chaumian Blinding allows us to create an anonymous system where privacy is protected not by hiding information but by ensuring the approving party never gets to see the full details in the first place.

And that’s the beauty of it: It’s magic, but with cryptography instead of sleight of hand.