DEV Community: Adnan Halvadžija

QM2 Evolution: From Static Engine to AI-Powered Intelligence

Adnan Halvadžija — Sat, 14 Mar 2026 07:20:25 +0000

A high-performance CLI engine built with Python. Now evolved into a smart study companion with Gemini AI integration and 84% test coverage.

QM2 Evolution: From Static Engine to AI-Powered Intelligence

A few weeks ago, I introduced QM2 v1.0.25 — a high-performance CLI quiz engine built for speed and reliability. It was a solid foundation with 330+ tests, but it had one major "friction" point: content creation. Writing 50 questions about Kubernetes or React manually is tedious.

After taking a short detour to build my event-driven portfolio with Hugo and Supabase, I returned to QM2 to solve the content problem. Today, I’m excited to announce QM2 v1.1.0. I’ve officially added a "brain" to the engine by integrating Google Gemini AI.

The Vision: Zero-Friction Learning

The mission was simple: Go from a blank screen to a 20-question, high-quality quiz in under 10 seconds. By leveraging the Gemini 1.5 & 2.0 Flash models, QM2 can now generate comprehensive study materials on any topic instantly, directly from your terminal.

New Tech in the Stack

To support AI generation without compromising the "brutalist" speed of the CLI, I added:

Google GenAI SDK: For seamless communication with Gemini models.
Exponential Backoff Logic: Ensuring the app handles API rate limits gracefully.
Advanced JSON Sanitization: A custom module that strips AI "chatter" and extracts pure, valid quiz schemas.

Engineering for Reliability (Part 2)

Adding AI shouldn't mean breaking the 84% test coverage. I had to solve two main challenges:

Mocked AI Testing: I used unittest.mock to simulate Gemini API responses. This allows the CI/CD pipeline to verify JSON parsing and fallback logic without needing a real API key or spending tokens.

The Fallback Chain: Reliability is key. If the Gemini 2.0 Flash model is busy or hits a limit, QM2 automatically retries with 1.5 Flash or 1.5 Pro. The user experience remains uninterrupted.

New AI Features

Topic-to-Quiz: Just enter a topic like "Advanced Python Decorators" or "World War II History".

Multi-Type Support: Unlike simple AI wrappers, QM2 forces the AI to generate all 4 supported types: Multiple Choice, True/False, Fill-in-the-blank, and even complex Matching pairs.

Smart Retries: Built-in logic to handle network jitters and API quotas.

Quick Start with AI

If you already have QM2, just upgrade:

pip install --upgrade qm2

Set your key and run:

export GEMINI_API_KEY="your_google_ai_key"
qm2

Fulfilling the Roadmap

In my previous QM2 deep dive, I promised AI integration. With v1.1.0, that promise is kept. The core engine is now more than just a player; it's a creator. This bridges the gap between a simple CLI tool and a complete educational platform.

Links & Support

If you're a CLI enthusiast, I'd love for you to try it out and give me your feedback!

📦 PyPI: pypi.org/project/qm2
💻 GitHub: ahalvadzija/qm2
📖 Docs: ahalvadzija.github.io/qm2

QM2 is now officially AI-powered. If you find it useful for your study sessions, a ⭐ on GitHub would be the best way to support the project!

What's your take on AI-generated educational content? Is it the future of personalized learning? Let's talk in the comments!

Building a High-Performance Full-Stack Portfolio: Hugo, Supabase & Deno Edge Functions

Adnan Halvadžija — Sun, 08 Mar 2026 14:48:58 +0000

When engineers build their portfolios, they often choose between two extremes: a simple static page or an over-engineered Single Page Application (SPA). For my portfolio, I chose a third path: a modular, event-driven architecture that combines the speed of a static site with the power of a serverless backend.

Architectural Philosophy

The primary goal was to achieve a 100/100 Lighthouse score while maintaining dynamic features such as a newsletter system and automated reporting.

Tech Stack:

Frontend: Hugo (Static Site Generator) + Tailwind CSS 4.0.
Search: Pagefind (static search on the client side).
Backend-as-a-Service: Supabase (PostgreSQL + Edge Functions).
Runtime: Deno (TypeScript) for serverless business logic.
Automation: GitHub Actions (CI/CD + Cron jobs).

Engineering Highlights

1. Event-Driven Newsletter System

Instead of a traditional API server, I utilized Supabase Edge Functions built on the Deno runtime.

The Workflow:

User submits an email via a custom HTML form (zero-dependency JS).
The Edge Function validates the payload and communicates with the Resend API.
Subscriber data is stored in PostgreSQL with Row Level Security (RLS) policies enabled, ensuring user data is protected even if the anonymous API key is exposed.

2. Hybrid CI/CD Pipeline

My GitHub Actions workflow manages three different runtimes in a single pass, demonstrating a highly flexible deployment strategy:

Node.js: Compiles Tailwind CSS and generates the Pagefind search index.
Python: Executes a newsletter.py script to generate reports directly from the database.
Hugo: Generates the final static production build.

# Snippet from the deployment workflow
- name: Run Newsletter Report
  env:
    SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
    RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
  run: python newsletter.py

3. Resource Optimization (The "Keep-Alive" Pulse)

Free-tier cloud services often "pause" databases after a period of inactivity. To prevent this, I implemented a Pulse workflow using a GitHub Action cron job (every day at midnight) to perform a small PATCH request to the database, keeping the Supabase instance active.

# GitHub Action ping (Keep-Alive)
curl -f -X PATCH "${{ secrets.SUPABASE_URL }}/rest/v1/keep_alive?id=eq.1" \
     -H "apikey: ${{ secrets.SUPABASE_ANON_KEY }}" \
     -H "Authorization: Bearer ${{ secrets.SUPABASE_ANON_KEY }}" \
     -H "Content-Type: application/json" \
     -d "{\"last_ping\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\"}"

Design & Performance

Tailwind 4.0: Utilizing the latest @tailwindcss/cli for ultra-fast builds and a minimal CSS footprint.
Zero-Flash Theme Switching: A custom JavaScript implementation prevents the "white flash" during page loads if a user prefers Dark Mode.
Asset Pipeline: Hugo handles minification and fingerprinting for all resources, allowing for aggressive caching on the CDN (GitHub Pages).

Local Development

The project is designed to be deterministic. By using npm ci, I ensure that all dependencies (such as Lucide icons or Swup for smooth transitions) are identical in both local and production environments.

# Clone the repository
git clone https://github.com/ahalvadzija/ahalvadzija.github.io.git

# Install dependencies
npm ci

# Run the Hugo development server
npm run dev

Conclusion

This portfolio is not just a showcase of my work; it is proof that modern web tools allow for the creation of complex, full-stack systems without the need for expensive infrastructure. The focus on Type Safety (TypeScript), Automation (Python/Actions), and Performance (Hugo) forms the core of my engineering approach.

View the full source code: ahalvadzija.github.io

Building QM2: A Modern, Dockerized CLI Quiz Engine with 330+ Tests

Adnan Halvadžija — Tue, 17 Feb 2026 15:15:51 +0000

🚀 The Mission

Most quiz applications are web-based, but I wanted something that lives where I spend most of my time: the terminal. I built QM2 — a robust, interactive quiz engine designed for developers and power users who value speed, efficiency, and a clean "brutalist" UI.

🛠️ The Tech Stack

To make a CLI feel like a professional product, I relied on some of the best libraries in the Python ecosystem:

Rich: For the beautiful, colored interface and real-time feedback.
Questionary: To handle complex interactive prompts and menus.
Platformdirs: Ensuring data is stored correctly whether you are on Windows, macOS, or Linux.
Docker: For those who want to run the engine in a completely isolated environment.

🏗️ Engineered for Reliability

As a developer, I believe that if it's not tested, it's broken.

330 Individual Tests: Ensuring the core logic remains rock-solid as the project grows.
86% Coverage: Backed by a strict CI/CD pipeline.
OIDC Publishing: Secure, token-less deployment to PyPI via GitHub Actions.

✨ Key Features

4 Question Types: Multiple Choice, True/False, Fill-in-the-blank, and Matching.
Flashcards Mode: Stress-free learning without the pressure of a timer.
Data Portability: Full support for bidirectional CSV ↔ JSON conversion. You can even import quizzes directly from a URL!
Category Management: Organize your learning into hierarchical structures (e.g., programming/python/basics).

📦 Installation & Quick Start

You can get up and running in seconds:
pip install qm2 qm2

Or via Docker to keep your system clean:

docker build -t qm2 . docker run -it -v qm2_data:/root/.local/share/qm2 qm2

📖 Deep Dive into Data

I designed the question format to be as human-readable as possible. Whether you prefer JSON for precision or CSV for bulk editing in Excel, QM2 handles both:
JSON

{ "type": "match", "question": "Match programming languages with their types", "pairs": { "left": ["Python", "C++"], "right": ["Interpreted", "Compiled"], "answers": { "a": "1", "b": "2" } } }

🗺️ What's Next?

"With the release of v1.0.25, QM2 has officially moved out of beta. The core is now stable, and I am shifting focus towards expanding the ecosystem."

AI Integration: Generating quizzes automatically from your documentation.
Plugin System: Allowing the community to build their own extensions.

🔗 Links & Support

If you're a CLI enthusiast, I'd love for you to try it out and give me your feedback!

📦 PyPI: pypi.org/project/qm2
💻 GitHub: ahalvadzija/qm2
📖 Docs: ahalvadzija.github.io/qm2

If you find this useful, a ⭐ on GitHub would mean a lot!

I’m curious — what is your favorite library for building CLI tools in Python? Let's discuss in the comments!

Hello World!

Adnan Halvadžija — Fri, 28 Jul 2023 04:43:49 +0000

Hello DEV! 👋

Finally decided to join the community instead of just lurking.

I’m Adnan, a Backend Engineer who loves building CLI tools and messing around with DevOps pipelines. I’ve spent a lot of time in the terminal lately, and I’m excited to start sharing some of the things I’ve been working on.

Looking forward to connecting with you all. What's everyone building today? 👇