AI Agent Boilerplate

This project is a simple AI agent powered by Groq cloud (via LangChain), delivered through a Flask backend.

Tech Stack

• Flask – For backend
• Langchain – Framework to build Chatbot

Features

• Fast, production-ready backend (Flask)
• Modular integration with Groq's LLM via LangChain
• Runs on Windows, Linux, and macOS

Prerequisites

Install Python

• Windows
• macOS

Python version control

macOS and Linux

Details

The Python version needs to be the same as mentioned in the .tool-versions file.

Make sure the correct Python version has been set up using asdf before you work on this project.

python3 --version

Windows

Details

• The Python version needs to be the same as mentioned in the .python-version file using pyenv-win.

• Make sure the correct Python version has been set by running python --version

---

Get a valid Groq API

• Go to Groq and create API Key
• Put your Groq API key in code/.env file

---

Setup PostgreSQL

• Install and setup PostgreSQL in you local
• Adjust your username and password in code/.env file

Getting Started

Clone the repository:

git clone https://github.com/Madhyamakist/ai-agent-boilerplate.git myproject

---

Set up virtual environment

Windows

Details

- To create a virtual environment called "venv", run

python -m venv venv

• To activate the environment

venv\Scripts\activate

macOS

Details

• Create a virtual environment named "venv",

python3 -m venv venv

• To activate the environment

source venv/bin/activate

---

Install dependencies

After activating your virtual environment, install dependencies by

cd code
pip install -r requirements.txt

Run Flask to render frontend

Setup Env

Cope .env.example into .env (gitignored).

cp .env.example .env

Replace the values (get it from team members?)

GROQ_API_KEY=randomstring
DATABASE_URL=postgresql://username:password@localhost:5432/

Run

If virtual environment is activated and dependencies are installed then run chatbot by:

cd code
python app.py

Now visit http://127.0.0.1:5000/ in your browser. For newer APIs visit http://127.0.0.1:5001/api/docs.

Test Flask APIs

If flask is rendered successfully, then test APIs by:

cd code/test
pytest --html=test_report.html --self-contained-html -v

For Linting

Using ruff (example inside code/)

ruff check app.py --fix