DEV Community: Fahad Ali Khan

Building an AI-Generated Text Detector: A Full-Stack NLP Project Guide

Fahad Ali Khan — Sat, 14 Mar 2026 09:42:40 +0000

The line between human and machine writing is blurring fast. This guide walks through building a complete AI-text detection system from scratch — from classical ML baselines to transformer fine-tuning, wrapped in a production API and interactive demo.

This isn't a toy notebook. By the end, you'll have a modular codebase with an ensemble model, REST API, Gradio UI, Docker deployment, CI/CD, and a test suite. Let's break down each commit.

Commit 1: The Foundation — Clean Init

2a66fcb Clean init (no large data/models/outputs)

Every good project starts with structure. The initial commit sets up a config-driven architecture where nothing is hardcoded:

configs/config.yaml centralizes every hyperparameter — TF-IDF feature counts, learning rates, batch sizes, file paths. This means you never dig through scripts to change a setting.

src/ holds reusable library modules. scripts/ holds runnable entry points. This separation matters: your training logic lives in importable functions, not buried inside if __name__ == "__main__" blocks.

src/data.py handles schema normalization. Datasets from Kaggle have inconsistent column names — "text" vs "content" vs "essay", "label" vs "generated" vs "is_gpt". The normalize_schema() function maps all variants to a canonical (text, label) format with binary labels (0=human, 1=AI). This is the kind of defensive data engineering that saves hours of debugging later.

src/baseline.py implements the classical ML pipeline: TF-IDF vectorization (200K features, unigrams + bigrams) piped into Logistic Regression. The entire pipeline is a single scikit-learn Pipeline object, which means the vectorizer and classifier are serialized together — no risk of train/serve skew.

src/transformer.py fine-tunes DistilBERT for binary classification using HuggingFace's Trainer API. Key design decisions:

Automatic validation split creation if one isn't provided
Null/empty text filtering before tokenization (prevents cryptic errors)
Mixed-precision training (fp16) and gradient checkpointing for memory efficiency
Offline-friendly model loading (checks if model_name is a local directory)

.gitignore excludes data/, models/, and outputs/ — keeping the repo lightweight. Large binary files don't belong in git.

Commit 2: Linguistic Feature Extraction

0c716b4 Add linguistic feature extraction module

Raw text classification is powerful, but interpretability matters. The src/features.py module extracts stylometric signals — measurable properties of writing style that differ between humans and language models.

What gets extracted:

Feature	Why It Matters
Type-Token Ratio (TTR)	AI text tends toward lower vocabulary diversity — it reuses common words more
Hapax Legomena Ratio	Words used exactly once. Humans use more rare/unique words
Flesch Reading Ease	AI-generated text often clusters in a narrow readability band
Sentence Length Variation	Humans write with more variable sentence structure
Word Entropy	Shannon entropy of the word distribution — higher means more varied word choice
Punctuation Rates	AI text has distinctive punctuation patterns (fewer semicolons, more consistent comma usage)

The implementation uses zero external NLP libraries — just regex and math. The syllable counter uses a vowel-group heuristic (_syllable_count()), which is fast and accurate enough for readability formulas.

The key design choice: extract_features() returns a flat dictionary, and extract_features_df() wraps it for batch processing. This makes the features usable both in the API (single predictions) and in training pipelines (DataFrame operations).

Commit 3: Ensemble Model

b8b8911 Add weighted soft-voting ensemble model

Neither model alone is optimal. The baseline is fast but misses nuance. The transformer is accurate but slow. The ensemble combines them through weighted probability averaging.

How it works:

P_ensemble = 0.3 × P_baseline + 0.7 × P_transformer

Both models output class probabilities (not just labels). The EnsembleDetector class:

Runs TF-IDF + LogReg to get P(human) and P(AI) from the baseline
Runs DistilBERT inference in batches to get transformer probabilities
Computes the weighted average
Returns the argmax as the final prediction

Why soft voting over hard voting? Hard voting (majority rule) throws away confidence information. If the baseline says 51% human and the transformer says 95% AI, hard voting sees a tie. Soft voting correctly favors AI because the transformer's high-confidence signal dominates.

The weights (0.3/0.7) are configurable via CLI args or environment variables. You could tune them on a validation set, but 0.3/0.7 is a reasonable default given the transformer's higher accuracy.

scripts/run_ensemble.py evaluates the ensemble on both validation and test splits, saving JSON metrics for comparison.

Commit 4: FastAPI REST API

c130c05 Add FastAPI REST API for inference

A model without an API is a notebook. The api/app.py module wraps the ensemble detector in a production-grade FastAPI service.

Three endpoints:

GET /health — Returns model load status. Essential for container orchestration (Docker health checks, Kubernetes liveness probes).
POST /predict — Single-text classification. Returns the label, confidence, per-class probabilities, all linguistic features, and inference latency in milliseconds. The latency field is useful for monitoring performance degradation.
POST /predict/batch — Classify up to 64 texts in one request. Batch inference is significantly faster than 64 individual calls because the transformer processes them in GPU-friendly batches.

Design decisions:

Pydantic models for request/response validation. PredictRequest enforces min_length=1 so empty strings are rejected at the schema level, not in model code.
Lifespan context manager for model loading. The detector loads once at startup and stays in memory — no per-request loading overhead.
Environment variable configuration (BASELINE_WEIGHT, TRANSFORMER_WEIGHT, CONFIG_PATH) so the API is configurable without code changes in deployment.

Run it with:

uvicorn api.app:app --host 0.0.0.0 --port 8000

FastAPI auto-generates interactive Swagger docs at /docs.

Commit 5: Gradio Interactive Demo

ebf7183 Add Gradio interactive demo with feature analysis

APIs are for machines. Demos are for humans. The app.py file creates a web interface where anyone can paste text and see results instantly.

The UI has three output components:

Classification label with color-coded probabilities (Gradio's Label component handles this natively)
Verdict text — a plain-English summary like "Prediction: AI-generated (confidence: 94.2%)"
Feature analysis table — the linguistic breakdown rendered as a markdown table

Why Gradio over Streamlit? Gradio is purpose-built for ML demos. A gr.Interface or gr.Blocks app can be shared with a public URL via share=True, embedded in HuggingFace Spaces, and requires zero frontend code.

The demo includes pre-loaded examples so users can test immediately without typing.

Commit 6: Unit Tests

347fdbc Add unit test suite for features, data, utils, and API

Tests are non-negotiable for a serious project. The tests/ directory covers four modules:

test_features.py (22 tests) — The most comprehensive. Tests every feature function individually (vocabulary richness, sentence stats, readability, punctuation, entropy) plus integration tests for the full extract_features() pipeline. Key edge cases: empty strings, single-word inputs, all-identical words.

test_data.py — Tests schema normalization with different column name variants (text/content/essay, label/generated/is_gpt), string label mapping, NaN handling, and the split creation function (verifies CSVs are created and row counts sum correctly).

test_utils.py — Tests seed reproducibility (set seed, generate random numbers, reset seed, verify identical output), directory creation, metric computation (perfect/zero/partial accuracy), and JSON serialization.

test_api.py — Tests Pydantic schemas without loading actual models. Validates that empty text is rejected, batch requests parse correctly, and response models serialize properly.

The test structure uses pytest classes to group related tests, making the output easy to scan.

Commit 7: Docker Support

2c75827 Add Dockerfile and docker-compose for containerized deployment

Dockerfile builds a slim Python 3.10 image with CPU-only PyTorch (the full CUDA torch is 2GB+; CPU-only is ~200MB). Models are not baked into the image — they're mounted as volumes at runtime. This keeps the image small and lets you swap models without rebuilding.

docker-compose.yml orchestrates two services:

api on port 8000 — the FastAPI service with a health check
demo on port 7860 — the Gradio UI, depending on the API service

Both mount models/ and configs/ as read-only volumes. Environment variables control ensemble weights.

.dockerignore excludes data, outputs, git history, and the presentation/recording files — keeping the Docker build context small.

Deploy with one command:

docker-compose up --build

Commit 8: GitHub Actions CI

e8abcfa Add GitHub Actions CI pipeline

The CI pipeline (.github/workflows/ci.yml) runs on every push and PR to main:

Matrix testing — Python 3.10 and 3.11 on Ubuntu
Linting — Ruff checks for syntax errors and style issues (E, F, W rules, ignoring line length)
Testing — Full pytest suite
Docker build — Validates the Dockerfile builds successfully (runs after tests pass)

CPU-only PyTorch is installed from the PyTorch index URL to keep CI fast.

Commit 9: README and License

34953ee Overhaul README and add MIT license

The README is your project's landing page. The final version includes:

CI badge — Green checkmark shows the project builds and tests pass
Architecture diagram — ASCII art showing the ensemble data flow
Project structure — Every file explained with one-line descriptions
Quick start — Four numbered steps from clone to running inference
API reference — curl examples with sample JSON responses
Docker deployment — One-command setup
Model details table — Hyperparameters at a glance
Feature documentation — What each linguistic feature measures
Tech stack table — Every technology organized by category
Ethical considerations — Bias risks and usage caveats

The MIT license makes the project freely usable.

What Makes This Resume-Worthy

This project demonstrates competence across the ML engineering stack:

Skill	Evidence
NLP/ML	TF-IDF, transformer fine-tuning, ensemble methods, feature engineering
Software engineering	Modular architecture, config-driven design, type hints
API development	FastAPI with Pydantic schemas, batch endpoints, health checks
Testing	Pytest suite with edge cases and integration tests
DevOps	Docker, docker-compose, GitHub Actions CI
Documentation	Comprehensive README with architecture diagrams and API reference
Data engineering	Schema normalization, stratified splitting, null handling

It's not just a Jupyter notebook with model.fit(). It's a deployable system with multiple entry points (CLI scripts, REST API, web demo), proper error handling, and automated quality checks.

The full source code is available on GitHub. Clone it, train the models, and try the demo yourself.

Building an Animated Portfolio Hero with GSAP, SplitText, and a Canvas Particle Background

Fahad Ali Khan — Tue, 10 Feb 2026 10:58:24 +0000

Modern portfolio sites aren’t just about listing projects anymore. They’re an opportunity to demonstrate polish, motion design, and engineering decisions — all in one place.

Recently, I built an animated hero section that combines:

Character-by-character text reveal using GSAP SplitText
Liquid morph social icons with hover physics
A canvas particle background reacting to cursor movement
Responsive layout that works across devices

This article walks through the architecture, animation patterns, and lessons learned — so you can build something similar without fighting your layout or performance.

Here is the final Product: https://fahadalikhan.vercel.app/

The goal

I wanted a hero section that feels alive without being distracting:

Headline text animates in smoothly
Social icons pop into view and morph on hover
A particle field subtly reacts to cursor movement
Everything stays responsive and performant

The key was orchestrating multiple animation layers without turning the component into chaos.

Layer 1 — Character-by-character text animation

GSAP’s SplitText plugin makes it trivial to animate individual characters. Instead of animating the entire headline block, we split it into spans and animate each char with a stagger.

const split = new SplitText(TextRef.current, { type: "chars" });

timeline.from(split.chars, {
  opacity: 0,
  x: 50,
  duration: 0.9,
  stagger: 0.05,
  ease: "power3.out",
});

This produces a cinematic reveal:

Characters slide in
Opacity fades up
Timing feels intentional

Important cleanup:

split.revert();

Without this, repeated renders stack nested spans and break your DOM.

Layer 2 — Social icons with liquid morph hover

Instead of static icons, I wanted something tactile. The trick is animating:

scale
rotation
border-radius

Border-radius is what creates the organic “blob” shape.

Hover enter:

gsap.to(icon, {
  scale: 1.2,
  rotation: 180,
  borderRadius: "30% 70% 70% 30% / 30% 30% 70% 70%",
  ease: "elastic.out(1, 0.3)",
});

Hover exit:

gsap.to(icon, {
  scale: 1,
  rotation: 0,
  borderRadius: "50%",
});

The elastic easing gives the impression of physical bounce instead of mechanical motion.

Layer 3 — Entrance timeline orchestration

One common mistake is running separate animations independently. Instead, everything is sequenced on a GSAP timeline:

const tl = gsap.timeline();

tl.from(textChars, {...})
  .from(iconLinks, {...}, "-=0.3");

This gives:

predictable timing
overlap control
easier debugging

You get a cohesive entrance instead of disconnected animations firing randomly.

Layer 4 — Canvas particle background

The particle system runs in a <canvas> behind the hero content:

particles arranged in a grid
mouse proximity drives wave distortion
rotation aligns particles toward the cursor

The canvas is positioned absolutely with a negative z-index:

canvas {
  position: absolute;
  inset: 0;
  z-index: -1;
}

Key performance notes:

Use requestAnimationFrame
Reuse particle objects
Avoid layout reads inside the loop

This keeps animation smooth even on mid-range devices.

Responsiveness challenges

Animation-heavy layouts often break at medium breakpoints. A few practical fixes:

Constrain large media with max-width
Maintain aspect ratios with Tailwind utilities
Avoid fixed heights where possible

Example:

md:max-w-[450px]
aspect-[4/3]
mx-auto

This prevents oversized visuals while preserving composition.

UX lessons learned

Motion should guide attention

Animations should reinforce hierarchy, not steal focus.

Physics > gimmicks

Elastic easing feels natural. Linear motion feels robotic.

Cleanup matters

Event listeners and SplitText wrappers must be reverted to avoid bugs.

Performance first

Canvas and GSAP can coexist — but avoid unnecessary recalculations.

Final thoughts

This hero section isn’t about flashy animation. It’s about layering:

typography motion
interactive affordances
subtle background energy

Together they create a polished first impression while staying performant and maintainable.

If you’re building a portfolio, landing page, or interactive UI, these techniques scale surprisingly well — and GSAP makes complex motion approachable once you understand timelines and sequencing.

Happy building.

Trying to blog again...

Fahad Ali Khan — Mon, 24 Nov 2025 08:29:33 +0000

Hi, guys, I've been away for a long time, mainly because I've been studying full-time and working. With 6 courses each semester at Seneca and a part-time j*b, I felt like I didn't have the time to do anything (except waste time on Apex Legends). So now I've finally graduated from Seneca. Proud to say I've successfully completed my Bachelors of Engineering Software Engineering. These past 4 years haven't been the kindest, but I'm hoping for better opportunities now. So seeing I have some extra time, I've decided to focus on my personal projects. Ideally, I would like to build the next-gen AI model from scratch from the start, but I know I'm not that good (YET!). So I will start a little slow, doing things I like but also focusing on my five-year plan. Stay tuned for exciting projects to come!

Delivering a Production-Ready Timesheet Automation and Emailing Solution

Fahad Ali Khan — Fri, 13 Dec 2024 10:51:52 +0000

Introduction

I began this project to strengthen my Python skills, contribute to an open-source automation tool, and learn to communicate my progress openly. After several weeks of incremental improvements—amid five other courses and internship interviews—I’m proud to release the final version of my contributions to the Academic-Learning-Centre-Admin-Scripts project.

This post summarizes what I’ve achieved, how I tackled technical and time challenges, and what I learned about producing useful, high-quality open-source contributions in a busy environment.

What’s New in the Final Release?

Weekly Automated Emailing:

The script now not only fetches appointment data, updates an Excel timesheet, and saves it with a dynamic filename, but it also sends that timesheet out via email on a predefined schedule (e.g., every Monday). This feature closes the loop, ensuring that the admin office doesn’t need to manually retrieve or request these files.
User Guide for Deployment:

I’ve added a comprehensive USER_GUIDE.md that details how to:
- Install dependencies
- Configure paths, tutor IDs, and endpoints
- Manage email credentials securely (e.g., environment variables)
- Set up automated scheduling with cron or Windows Task Scheduler This documentation should make it straightforward for others to adopt and deploy the script in their own environments.
Refactored and Maintainable Code:

Before merging, I refactored the code into cleaner, smaller functions and modules. Now there’s a clear separation of concerns:
- timesheet.py handles the main workflow.
- email_generator.py creates structured email data.
- email_sender.py handles the actual sending of emails.

Constants are clearly defined, date calculations are isolated, and error handling is more graceful. This should pave the way for future contributors to build upon my work.

Measuring My Goals and Success

Initially, I set out to:

Add email generation and sending features.
Produce documentation and improve code quality.
Work in the open (GitHub issues, PRs), write blog posts, and manage time responsibly.

I can confidently say I’ve met these goals:

Email Features: Implemented and tested. Emails now go out automatically.
Documentation: The user guide and updated README clearly explain setup and usage.
Code Quality: The refactoring improved readability and modularity.
Open Communication & Time Management: I wrote blog posts reflecting on my progress and final output. Although I was pressed for time, breaking the work into smaller chunks and documenting it kept me aligned with my goals.

Lessons Learned

Technical Skills:

I revisited Python’s datetime handling, file manipulations with openpyxl, and BeautifulSoup parsing. I also got hands-on with smtplib for emailing—learning how to secure credentials and attach files.
Open-Source Collaboration:

Even without extensive back-and-forth from maintainers, I treated this project as if I were part of a larger community—writing clear commit messages, PR descriptions, and linking issues properly. This discipline will serve me well in future projects.
Dealing with Constraints:

Balancing five courses and internship prep was tough. However, setting achievable weekly goals, documenting my progress, and reflecting via blog posts helped me remain productive and not get lost in complexity.

Future Potential

There’s room for more improvements:

Integrating better error handling and logging frameworks.
Adding automated tests.
Enabling more dynamic scheduling (e.g., sending emails on multiple days or triggered events).
Encouraging feedback from the open-source community and possibly mentoring new contributors on the project.

Conclusion

As I reach the conclusion of this effort, I can say I’ve delivered a valuable feature set to an existing open-source project. The script is now not only an automated timesheet updater but also a weekly emailing assistant. The documentation ensures that others can deploy it easily, and the refactoring makes maintenance and extension simpler.

This was more than a coding exercise: it was an exercise in time management, communication, technical writing, and project stewardship. I’m now more confident in my ability to contribute meaningfully to open-source software, even amidst a heavy personal workload.

The final result stands as a testament to what careful planning, incremental progress, and open communication can achieve. I look forward to seeing the script help others and potentially collaborating on further enhancements.

Finding My Footing in Open-Source Timesheet Automation

Fahad Ali Khan — Tue, 10 Dec 2024 08:03:25 +0000

Blog Post 1: Progress Update

Introduction

A few days ago, I embarked on contributing to the Academic-Learning-Centre-Admin-Scripts—a Python project that automates the creation and maintenance of weekly timesheets. My ultimate goal was to add new features (like sending the updated Excel timesheets via email), improve documentation, and enhance the overall code quality. Along the way, I’ve also been juggling a heavy workload: I’m taking five other courses and actively preparing for internship interviews, which means every hour spent on this project needed to count.

Despite these constraints, I’ve made meaningful progress. This update reflects on what I’ve accomplished so far, the challenges I’ve tackled, and how I’ve measured my progress against my initial goals.

What I’ve Accomplished So Far

Email Data Generation:

I started by implementing emailDataGenerator, a function that returns a structured array of email details (recipient, subject, current date, formatted week range, and salutations). Creating this helped me understand Python’s datetime handling more deeply and forced me to pay attention to code structure.
Integrating Email Sending Functionality:

After generating data, I implemented sendEmail to actually dispatch emails. This involved using smtplib and email.message.EmailMessage to connect to an SMTP server, format the email, and send it out. The initial attempts led to some trial and error—authenticating with SMTP, managing credentials, and ensuring the email rendered correctly were all new challenges for me.
Refactoring the Codebase:

As I introduced new features, I realized the importance of clean, modular code. I refactored timesheet.py to break logic into smaller functions, used constants for configuration, and set up separate modules (email_generator.py, email_sender.py). This not only made the code more maintainable but also helped me clarify my own understanding of the workflow.
Creating a User Guide (Planned):

Although I haven’t fully finished this part, I’ve started outlining a USER_GUIDE.md that will describe how to deploy the project, configure it, and even schedule it to run automatically. The guide will be the next big step, ensuring that anyone can use or adapt this script without struggling through trial and error.

Challenges and Solutions

Time Management:

With five other courses on my plate and ongoing internship interviews, finding time for open-source contributions was tough. I overcame this by:
- Setting small, achievable milestones each week.
- Writing down what I accomplished in blog posts and PR comments, creating a record that motivated me to keep going.
Technical Hurdles:
- SMTP & Email Attachments: Understanding how to attach the Excel file and handle credentials took some research. I read through Python’s official docs and tested locally until the feature worked reliably.
- Refactoring: Improving code structure required me to understand every part of the script. By separating logic into functions and modules, I can now navigate the code more easily and add new features without chaos.
Open-Source Etiquette:

I learned to write meaningful commit messages, describe PRs thoroughly, and make my branches and merges cleaner. While I haven’t had much direct feedback from maintainers yet, I’m preparing my contributions as if a reviewer is watching carefully.

Adjusting Course for the Final Release

Now that the emailing logic is in place and the code is refactored, I’m focusing on:

Finalizing the user guide with deployment instructions and examples.
Adding a weekly emailing schedule so that the admin office receives timesheets automatically every Monday (or another chosen day).
Polishing code style and ensuring I meet PEP 8 guidelines.

My final blog post will detail the completed features, what I learned, how close I came to my initial goals, and how I overcame time constraints.

Conclusion

I’m halfway through my planned tasks and feeling more confident than when I started. Working in Python after a year-long hiatus was challenging, but creating these features and writing about them has solidified my understanding. By my next update, I aim to have the project fully ready for others to adopt, with a user guide and a clean, professional codebase. Despite my busy schedule, I’m making steady, visible progress.

My Release 0.4 Open-Source Journey - From Planning to Delivery

Fahad Ali Khan — Tue, 10 Dec 2024 07:56:32 +0000

Introduction

At the start of this journey, I knew I wanted my last project of opensource to be something meaningful, educational, and technically rich. The plan was to contribute to an open-source project—in my case, the Academic-Learning-Centre-Admin-Scripts—by adding new features, documenting the process thoroughly, and engaging with the community. The goal was not simply to open a PR and be done, but to do the work in the open, interact on GitHub, refine my changes based on feedback, and ultimately have my contributions accepted and merged.

This was my first real engagement with a Python-based codebase beyond a basic course I took a year ago. Plus, I’m currently juggling five other courses and navigating internship interviews, which made time management a significant challenge. I needed to set realistic goals, approach them systematically, and track my progress over several weeks.

Setting the Stage (Week 1 Plans)

In the first phase, I planned out what I wanted to accomplish:

Why Choose This Project?

The Academic-Learning-Centre-Admin-Scripts caught my interest because it automates tedious timesheet generation from tutor appointment data. This felt like a genuinely useful automation that could be extended and improved. I chose it because:
- It involves Python scripting and automation (areas I need more real-world practice in).
- It’s already somewhat functional, but clearly has room for enhancements (like automated emailing, documentation improvements, and better deployment instructions).
- Contributing here would let me leave behind a helpful tool.
What Did I Plan to Do?

I decided on a set of tasks:
- Improve and modularize email functionality: first generate email data, then send emails automatically each week.
- Enhance the existing documentation by adding a detailed user guide for deployment.
- Eventually refine coding style and structure (PEP 8 compliance, better variable names, etc.).
- Write blog posts and actively use GitHub issues, PRs, and discussions to collaborate in the open.
Approach and Goals:
- Allocate a few hours each week specifically to coding and community interaction.
- Keep an eye on the calendar to ensure I finish the core contributions on time.
- Communicate openly: ask questions on GitHub issues, explain what I’m doing in PR descriptions, and write weekly blog posts to reflect on progress.

By the end of this initial planning phase, I felt confident but cautious—I remembered that I had those five other courses and ongoing internship interviews. Time management was crucial. The plan was to incrementally build my solution and share each step publicly, ensuring I wouldn’t overcommit and lose track.

Mid-Project Progress (Week 2 Update)

After about a week, it was time to assess what I had done and where I stood:

What I Managed to Complete:
- I integrated an emailDataGenerator function and tested it. This function returned structured email data, including the weekly date range and a friendly closing.
- I implemented a sendEmail function capable of dispatching the updated timesheet as an attachment to the admin office. This involved diving into SMTP details, handling attachments, and testing the workflow end-to-end.
Sticking Points:
- Handling credentials securely and deciding on which day to send the email was trickier than expected. I learned about environment variables for storing email passwords and considered using cron jobs for scheduling.
- Balancing this work with my other obligations was tough. I found myself working late at night to implement and test features. However, explaining my work in blog posts and PR descriptions helped clarify my thoughts and keep me motivated.
Adjusting the Plan:
With less time than anticipated, I decided to focus on making sure the main features (weekly emailing, user guide) were solid rather than rushing to do everything at once. I communicated any trade-offs on the GitHub issue trackers and in my mid-week blog updates. This open communication might have helped if anyone had feedback or suggestions.

By this midpoint, I had a working solution that fetched data, updated timesheets, and could now email them automatically (on a chosen weekday, like Monday). I also committed to writing a USER_GUIDE.md explaining how to deploy and run the script in different environments. The knowledge that I was improving an actual tool was gratifying, even though my schedule was tight.

Final Results (Consolidated Outcomes)

Now that the work is completed:

Achievements:
- Successfully integrated the weekly emailing feature. The script not only generates a timesheet but also attaches and emails it on schedule.
- Wrote a comprehensive user guide (USER_GUIDE.md) detailing setup, configuration, scheduling, and secure credential handling.
- Refactored the code to be cleaner, more modular, and easier to maintain. This included adopting a clearer coding style and reorganizing logic into functions and separate files (email_generator.py, email_sender.py).
- Followed through on the open-source etiquette: made branches, opened PRs, wrote detailed commit messages, and documented the process in blog posts and PR descriptions.
Measuring Success:
- The PRs were successfully created, well-described, and reviewed.
- I learned how to handle date ranges, manipulate Excel files using openpyxl, parse HTML with BeautifulSoup, and integrate SMTP emailing.
- My confidence in Python went from “rusty and unsure” to “capable and resourceful.” I can now handle not only the coding but also explain it clearly to others.
Lessons Learned:
- Technical Growth: Improving code architecture and adding new features taught me how to read documentation and implement library functions effectively.
- Open-Source Process: Working in the open, writing technical blog posts, and creating PRs helped me understand the importance of communication and transparency.
- Time Management & Priorities: Despite five other courses and ongoing internship interviews, breaking the project down into smaller tasks and writing weekly blog updates helped maintain steady progress. Setting realistic goals and adjusting them mid-course was critical.
Community Interaction:
- Although I had limited direct feedback from maintainers, writing PR descriptions, linking issues, and documenting changes thoroughly meant that if maintainers or other contributors arrived, they could understand my changes quickly.
- If there were community Slack channels, Discord groups, or GitHub Discussions, I would have participated there as well. The instructions highlighted that being active in community channels and discussions is part of the open-source ethos. Even if minimal feedback came back, the openness and clarity of my workflow prepared me for future collaboration.

Conclusion

What started as a plan to improve a Python script and document my journey ended in a successful completion of all core objectives. I created blog posts (rolled into this single long-form summary), contributed meaningful features, wrote comprehensive documentation, and maintained a professional Git workflow. The experience gave me confidence in my technical and communication skills.

If anyone else stumbles upon this project looking for guidance on automating timesheets or sending weekly reports via email, I hope my contributions and documentation will help them. Despite my heavy workload—juggling five courses and preparing for internship interviews—I’ve shown that with careful planning, incremental progress, and open communication, one can make a substantial and high-quality contribution to an open-source project.

This final retrospective closes out my 0.4 journey, capturing the entire arc: from initial planning and goal-setting, through mid-project adaptation and problem-solving, to delivering a polished, documented solution ready to be merged and used.

Implementing and Integrating Email Automation in a Python Timesheet Project

Fahad Ali Khan — Sun, 08 Dec 2024 04:28:05 +0000

Below is the updated blog post with the links you’ve provided integrated into the discussion. You can adjust formatting as needed.

Blog Post: Implementing and Integrating Email Automation in a Python Timesheet Project

Date: December 8, 2024

Author: Your Name

Introduction

This past week, I took on my first real contribution to a Python-based codebase. Although I’ve done a Python course about a year ago, my skills were quite rusty. Before jumping into this project, I spent about 10 hours on a quick Python crash course from FreeCodeCamp (link) just to refresh my memory on the basics—control structures, data types, standard libraries, and best practices. This preparatory work was necessary because I was about to dive into a code repository that automated certain administrative tasks, and I needed to ensure I was up to speed.

Context and Challenges

I’ve been juggling multiple commitments: I’m taking 5 other courses and currently going through internship interviews, so time management has been extremely tough. My goals with these PRs (pull requests) were initially modest—just build a strong foundational understanding of the project’s architecture, and then make incremental contributions. In the spirit of continuous improvement and measuring my progress from my initial baseline (“0.2” confidence level), I set out to do the following:

Understand the existing timesheet automation code.
Add a module that generates email data (emailDataGenerator).
Integrate a new module to send automated emails upon completing the timesheet updates (sendEmail).

This blog post focuses on detailing my contributions for each PR, the process I followed, what I learned, and how I measured my progress in terms of complexity and comfort working with Python code.

Issue #2 and #3: Foundations for Email Data Generation and Sending

These two issues defined the scope of what I needed to achieve: first, create and integrate an email data generator, and second, actually send emails after the timesheet updates.

PR #4: Introducing Email Data Generation

Link to PR: PR #4

My first PR involved creating a function emailDataGenerator that returns a structured list containing email details such as the recipient email, subject line, current date, and week range. Before starting, I had limited knowledge of Python’s datetime module and date handling. I spent a couple of hours experimenting with datetime, trying to figure out how to compute weekly date ranges (e.g., from Monday to Sunday) and formatting dates using strftime.

What I Did:

Created a separate file email_generator.py.
Implemented emailDataGenerator(receiver, subject, sender) which returns [receiverEmail, subject, current_date, current_week_range, salutations].
Used datetime.now(), timedelta, and strftime to produce human-readable date formats.

What I Learned:

How to modularize Python code: Separating logic into multiple files makes it cleaner and more maintainable.
Gained confidence in handling date operations in Python.
This boosted my comfort from a self-assessed “0.2” (very unsure) to about “0.5” (somewhat confident) with Python, as I had successfully written and integrated a non-trivial function.

Measuring Success:

The PR was merged without major requests for changes.
I was able to run the script and see the generated email data printed out, confirming correctness.

PR #5: Sending Automated Emails After Timesheet Updates

Link to PR: PR #5

The second PR involved more complexity: actually sending emails. I introduced sendEmail(emailData, receiverEmail) using Python’s smtplib and email.message.EmailMessage. This required understanding SMTP, configuring an email server (e.g., Gmail SMTP), and handling authentication. Since this was my first time doing anything email-related in Python, I did the following:

Created a new module email_sender.py.
Implemented sendEmail that took the structured emailData from emailDataGenerator and dispatched an email via SMTP.
Handled errors by returning "email not sent" if any exceptions occurred, or True if the sending was successful.
Integrated this into timesheet.py so that after the Excel timesheet is generated and saved, the script calls emailDataGenerator, then passes that data to sendEmail.

What I Learned:

How to work with smtplib to establish a secure connection using starttls().
The importance of securing credentials. I learned that hardcoding passwords isn’t ideal and considered environment variables or other credential stores for a more secure approach.
Improved confidence in debugging since my first attempts at sending emails failed due to authentication errors, and I learned to read stack traces and documentation carefully.
This experience bumped my comfort from “0.5” to about “0.7”. I’m not a Python guru yet, but I’m a lot more comfortable troubleshooting issues and reading official Python documentation now.

Measuring Success:

After merging the PR, I tested the workflow end-to-end: update timesheet, generate data, send email.
Verified that an actual email landed in the test recipient’s inbox. That felt incredibly rewarding and concrete.

Process and Time Management Reflections

Time management was a big challenge. I’m juggling multiple courses and internship interviews. However, I managed to be more structured this time:

Block scheduling: Dedicated a 3-hour block specifically for Python work on weekends.
Small milestones: First, just make sure emailDataGenerator worked independently. Next, ensure sendEmail worked with dummy data before integrating with the main code.
Continuous Review: Writing about my process in blog posts helped me clarify my thoughts. Explaining things often reveals gaps or suggests improvements.

By writing this progress report, I’ve recognized how explaining the code and process forced me to better understand it. Every difficulty I faced became clearer once I wrote it down.

How I Measured My Progress from 0.2

Initially, I considered myself at a 0.2 comfort level with Python because I had little recent hands-on experience. After these PRs:

Comfort with Python syntax & structures: Moved from uncertain to fairly confident.
Using third-party libraries: I learned to integrate smtplib, email.message, datetime, and openpyxl more seamlessly.
Contributing to a codebase with specific domain logic: I now know how to do weekly date calculations and integrate them into a workflow.

Overall, I’ve gone from 0.2 to about 0.7 in terms of confidence. I’m still not an expert, but I’m significantly more comfortable than before, especially with debugging, modular code design, and handling external libraries.

Links and References

Conclusion

This series of PRs taught me that incremental learning and improvement, combined with reflective writing, can significantly accelerate skill development. I’m pleased with how I integrated emailDataGenerator and sendEmail into the timesheet automation pipeline, and I know that as I take on more complex features, I’ll continue to measure and celebrate my progress—one PR at a time.

Streamlining C++ Project Releases with CMake and Vcpkg

Fahad Ali Khan — Sat, 23 Nov 2024 18:21:47 +0000

Releasing software can often feel like navigating a labyrinth of tools, configurations, and best practices. As a C++ developer, ensuring that your project is easily accessible and installable for users across different platforms is paramount. In this blog post, I'll walk you through the process I undertook to release my C++ project, EnglishFormatter, using CMake and Vcpkg. I'll share the tools I chose, the step-by-step release process, the lessons learned, the adjustments made to my project, insights from user testing, and comprehensive instructions for users to install and utilize the tool.

Choosing the Right Tools
Process for Creating a Release
- 1. Setting Up the Project with CMake
- 2. Managing Dependencies with Vcpkg
- 3. Configuring Git for Releases
- 4. Building and Testing
- 5. Publishing the Release on GitHub
Lessons Learned
Adjustments Made to the Project
User Testing with macOS
Installing and Using EnglishFormatter
- Installation Steps
- Usage Instructions
Conclusion
Resources and Links

Choosing the Right Tools

Selecting the appropriate tools is crucial for a smooth release process. For EnglishFormatter, I opted for:

CMake: A versatile build system generator that simplifies the build process across different platforms.
Vcpkg: A C++ library manager that handles dependencies efficiently, ensuring reproducible builds.
GitHub Releases: Leveraging GitHub's built-in release management to distribute binaries and source code.

Links:

Process for Creating a Release

1. Setting Up the Project with CMake

CMake was chosen as the build system due to its cross-platform capabilities and seamless integration with various package managers. Here's how I configured CMake for EnglishFormatter:

CMakeLists.txt: Defined the project, set the C++ standard to C++20, and specified the toolchain file for Vcpkg.

  cmake_minimum_required(VERSION 3.20)

  # Enable Vcpkg manifest mode before the project command
  set(VCPKG_MANIFEST_MODE ON CACHE BOOL "Enable Vcpkg manifest mode")

  project(EnglishFormatter VERSION 1.0.0 LANGUAGES CXX)

  # Set C++ standard to C++20
  set(CMAKE_CXX_STANDARD 20)
  set(CMAKE_CXX_STANDARD_REQUIRED ON)

  # ------------------------
  # Core Library Configuration
  # ------------------------

  # Collect all source files for the core library, excluding cli.cpp
  file(GLOB CORE_SOURCES CONFIGURE_DEPENDS cli_app/src/*.cpp)

  # Exclude cli.cpp from CORE_SOURCES to prevent multiple main definitions
  list(FILTER CORE_SOURCES EXCLUDE REGEX ".*/cli\\.cpp$")

  # Define the core library
  add_library(core_lib STATIC ${CORE_SOURCES})

  # Include directories for the core library
  target_include_directories(core_lib PUBLIC cli_app/include)

  # Find and link CURL and fmt libraries
  find_package(CURL REQUIRED)
  find_package(fmt REQUIRED)
  target_link_libraries(core_lib PUBLIC CURL::libcurl fmt::fmt)

  # ------------------------
  # GoogleTest and GoogleMock Configuration
  # ------------------------
  include(FetchContent)

  # Fetch GoogleTest (which includes GoogleMock)
  FetchContent_Declare(
    googletest
    URL https://github.com/google/googletest/archive/refs/tags/release-1.12.1.zip
    DOWNLOAD_EXTRACT_TIMESTAMP ON
  )

  # Prevent overriding the parent project's compiler/linker settings
  if(MSVC)
    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
  endif()

  # Enable building GMock and GTest
  set(BUILD_GMOCK ON CACHE BOOL "" FORCE)
  set(BUILD_GTEST ON CACHE BOOL "" FORCE)

  FetchContent_MakeAvailable(googletest)

  # Enable testing before defining tests
  enable_testing()

  # ------------------------
  # Main Executable Configuration
  # ------------------------

  # Define the main executable and link it against the core library
  add_executable(EnglishFormatter cli_app/src/cli.cpp)
  target_link_libraries(EnglishFormatter PRIVATE core_lib)

  # ------------------------
  # Test Executable Configuration
  # ------------------------

  # Collect all test source files
  file(GLOB TEST_SOURCES CONFIGURE_DEPENDS cli_app/tests/*.cpp)

  # Define the test executable
  add_executable(EnglishFormatterTests ${TEST_SOURCES})

  # Include directories for tests
  target_include_directories(EnglishFormatterTests PRIVATE cli_app/include)

  # Link test executable against GMock, GTest, GTest main, and the core library
  target_link_libraries(EnglishFormatterTests 
      PRIVATE 
          gmock 
          gtest 
          gtest_main
          core_lib
  )

  # Register the tests
  add_test(NAME EnglishFormatterTests COMMAND EnglishFormatterTests)

2. Managing Dependencies with Vcpkg

Vcpkg was instrumental in managing the project's dependencies, ensuring that all required libraries were correctly installed and linked. Here's how I integrated Vcpkg:

Installing Vcpkg:

  git clone https://github.com/microsoft/vcpkg.git
  cd vcpkg
  ./bootstrap-vcpkg.sh

Installing Dependencies:

  ./vcpkg install curl fmt

Using Vcpkg with CMake:

When configuring the project with CMake, I specified the toolchain file provided by Vcpkg:

  cmake .. -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Note: Replace path/to/vcpkg with the actual path to your Vcpkg installation.

3. Configuring Git for Releases

Git tags are pivotal in marking specific points in the project's history, such as releases. Here's how I managed Git tags:

Committing Changes:

  git add .
  git commit -m "Prepare for release 1.0.0"

Creating an Annotated Tag:

  git tag -a v1.0.0 -m "Release version 1.0.0"

Pushing Tags to GitHub:

  git push origin main
  git push --follow-tags

This approach ensures that the release is clearly marked in the project's history and is easily accessible for future reference.

4. Building and Testing

With the project configured, the next step was to build and test it to ensure everything functioned as expected.

Building the Project:

  mkdir build
  cd build
  cmake .. -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake
  cmake --build . --config Release

Running Tests:

  ctest --output-on-failure

This process verified that the core library and executables were correctly built and that the tests passed, ensuring the reliability of the release.

5. Publishing the Release on GitHub

Publishing the release on GitHub made it accessible to users and integrated with the project's version control.

Creating a Release on GitHub:

Navigate to the GitHub repository.
Click on the "Releases" tab.
Click "Draft a new release".
Select the tag v1.0.0.
Provide a release title and description.
Attach any build artifacts if necessary (e.g., binaries for different platforms).
Click "Publish release".

This step officially marks the version 1.0.0 of EnglishFormatter as available for users to download and install.

Lessons Learned

Embarking on this release journey was both enlightening and challenging. Here are some key takeaways:

Importance of Proper Configuration Order: Setting variables like CMAKE_TOOLCHAIN_FILE and VCPKG_MANIFEST_MODE before the project() command in CMakeLists.txt was crucial. Misplacing these led to initial configuration issues.
Managing Dependencies: Vcpkg simplified dependency management, but ensuring all dependencies were correctly listed in vcpkg.json prevented potential build issues.
Git Tagging Best Practices: Using annotated tags with clear messages aids in maintaining a clean project history and facilitates easier rollbacks if needed.
Documentation is Key: Clear and comprehensive documentation in README.md ensures users can install and use the tool without hiccups.
User Testing Insights: Real-world testing highlighted areas where documentation could be improved, emphasizing the need for user-centric documentation.

Adjustments Made to the Project

To accommodate the release process using CMake and Vcpkg, several modifications were necessary:

Integration of Vcpkg: Added vcpkg.json to manage dependencies and adjusted CMakeLists.txt to enable Vcpkg manifest mode.
Build Configuration: Configured output directories in CMake to organize binaries systematically.
Testing Setup: Incorporated GoogleTest and GoogleMock for unit testing, ensuring the core functionalities were reliable.
Documentation Enhancements: Expanded README.md with detailed installation, configuration, and usage instructions to guide users effectively.

These changes streamlined the build process, ensured dependency consistency, and enhanced the overall usability of EnglishFormatter.

User Testing with macOS

To validate the installation and usage instructions, I enlisted the help of a friend who uses macOS. Here's how the session unfolded:

Setup

Preparation: Shared the updated README.md with my friend, highlighting the installation steps.
Environment: My friend ensured they had CMake, Vcpkg, and a C++20-compatible compiler installed on their macOS system.

Testing Process

Cloning the Repository:

   git clone https://github.com/yourusername/EnglishFormatter.git
   cd EnglishFormatter

Setting Up Vcpkg:

   git clone https://github.com/microsoft/vcpkg.git
   cd vcpkg
   ./bootstrap-vcpkg.sh
   ./vcpkg install curl fmt
   cd ..

Configuring and Building the Project:

   mkdir build
   cd build
   cmake .. -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake
   cmake --build . --config Release

Running the Application:

   ./EnglishFormatter

Observations and Feedback

Smooth Installation: The installation steps were clear, and my friend was able to set up the environment without issues.
Execution Clarity: Running the executable and navigating the interactive menu was straightforward.
Minor Confusion: Initially, my friend was unsure about specifying the path to the Vcpkg toolchain file. Clarifying this step helped resolve the confusion.
Documentation Improvements: Based on the feedback, I added more explicit instructions regarding the toolchain file path and included troubleshooting tips for common issues.

Corrections Made

Toolchain File Path: Provided a clearer explanation of how to locate and specify the Vcpkg toolchain file during the CMake configuration.
Environment Setup: Included additional details on ensuring that Vcpkg is correctly set up before building the project.

This user testing session was invaluable in refining the documentation, ensuring that users across different platforms can effortlessly install and utilize EnglishFormatter.

Installing and Using EnglishFormatter

With the release now live, users can easily install and use EnglishFormatter on their systems. Here's a comprehensive guide to get you started.

Installation Steps

Install Vcpkg

Vcpkg is essential for managing dependencies. Follow these steps to install it:

   git clone https://github.com/microsoft/vcpkg.git
   cd vcpkg
   ./bootstrap-vcpkg.sh

For detailed instructions, refer to the Vcpkg Quick Start Guide.

Clone the EnglishFormatter Repository

   git clone https://github.com/yourusername/EnglishFormatter.git
   cd EnglishFormatter

Set Up the .env File

Create a .env file in the project's root directory to store your API key:

   API_KEY=your_api_key_here

Replace your_api_key_here with your actual API key from your language model provider (e.g., OpenAI).

Build the Project

   mkdir build
   cd build
   cmake .. -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake
   cmake --build . --config Release

Note: Ensure that the path to vcpkg in the CMAKE_TOOLCHAIN_FILE flag is correct based on your system setup.

Usage Instructions

Once built, you can use EnglishFormatter to format, summarize, or paraphrase your text documents.

Running via Command-Line Options

./EnglishFormatter [options]

Available Options:

-h, --help : Show help message and exit.
-v, --version : Show the tool's version and exit.
-m, --model MODEL : Specify the language model to use (default: gpt-3.5-turbo).
-o, --output SUFFIX : Specify the output file suffix (default: _modified).
-t, --token-usage : Show token usage and exit.

Example:

Formatting documents with a specific model and output suffix:

./EnglishFormatter --model gpt-4 --output _formatted

Using the Interactive Menu

Simply run the executable without any arguments to access the interactive menu:

./EnglishFormatter

Menu Options:

Format document: Improve the readability and structure of your text files.
Summarize document: Generate concise summaries of your documents.
Paraphrase document: Rephrase your text while retaining the original meaning.
Exit: Close the application.

Navigation:

Use the Up and Down arrow keys to navigate through the menu.
Press Enter to select an option.

Processing Files:

Select the desired action from the menu.
When prompted, enter the names of the files you wish to process, separated by spaces.
The tool will process each file and save the output with the specified suffix.

Conclusion

Releasing EnglishFormatter was a rewarding experience that underscored the importance of structured build systems, efficient dependency management, and comprehensive documentation. By leveraging CMake and Vcpkg, I ensured that the project is easily buildable across different platforms, making it accessible to a broader user base. The user testing session highlighted the significance of clear instructions, prompting necessary refinements to the documentation. As a result, users can now seamlessly install and utilize EnglishFormatter, enhancing their text processing tasks with advanced language models.

Resources and Links

- Github Repo

Feel free to reach out via the GitHub Issues page or contact me directly for any questions, suggestions, or support regarding EnglishFormatter.

Happy Formatting!

Continuous Integration with GitHub Actions

Fahad Ali Khan — Thu, 21 Nov 2024 11:05:03 +0000

Introduction

In Lab 8 of DPS909, I explored the power of Continuous Integration (CI), specifically through GitHub Actions. This lab was a great opportunity to enhance my project by automating tests, ensuring quality control, and learning to integrate workflows into real-world development practices.

CI ensures that code remains functional and bug-free with every change. It prevents breaking the default branch by continuously running tests. For this lab, I not only integrated CI into my own project but also contributed tests to my partner’s project. This blog post reflects on my journey through these tasks.

Setting Up GitHub Actions for My Project

To set up CI in my project, I created a GitHub Actions Workflow. This workflow was triggered whenever:

A push was made to the main branch.
A pull request was created targeting the main branch.

YAML Workflow Configuration

Below is the YAML file I used for my GitHub Actions workflow:

name: CI Workflow

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up C++
        uses: actions/setup-cpp@v1
        with:
          compiler: gcc

      - name: Build the project
        run: |
          mkdir build
          cd build
          cmake ..
          make

      - name: Run Tests
        run: |
          cd build
          ctest

This workflow checks out my repository, builds the project using CMake, and runs the tests I wrote in Lab 7.

Testing CI with a Pull Request

To ensure the workflow was working as expected, I:

Created a new branch, add-more-tests.
Added new tests for a different function in my project.
Pushed the branch to my repository and opened a pull request targeting the main branch.

The CI workflow ran as expected:

Initially, I broke one of the tests intentionally to observe a failure. The logs clearly showed the issue, which made debugging straightforward.
After fixing the test, the CI passed, confirming the workflow's success.

Merging this pull request into the main branch gave me confidence that my project was protected from unintentional bugs.

Contributing Tests to a Partner’s Project

In the second part of the lab, I collaborated with my classmate, Inder Parmar, and contributed tests to their repository, Tailor4Job.

My Pull Request: #11

Task: I added a test case for their jobFilter function to ensure it handles edge cases correctly.
Challenges: Their repository used a different framework and setup than mine. Understanding their testing tools and project structure took some time.
Outcome: My pull request passed their CI workflow successfully. This experience taught me the importance of writing tests that align with a project’s existing structure and guidelines.

Reflection on Continuous Integration

Setting up CI was a game-changer for my development workflow. Here are some key takeaways:

Proactive Bug Prevention: CI ensures bugs are caught early, reducing the risk of breaking the default branch.
Ease of Collaboration: Automated tests give confidence when merging code from multiple developers.
Improved Debugging: CI logs provided detailed insights into test failures, making debugging faster and more efficient.

Collaborating on a partner's repo was an enriching experience, as it gave me exposure to a different codebase, testing environment, and workflow.

Optional Challenges

While I didn’t fully implement the optional challenges, I explored:

Adding a Linter: Automating linting as part of CI helps catch style and syntax issues early.
Development Containers: I experimented with setting up a reproducible development environment using Docker and Codespaces.

These steps can further enhance project quality and ease of onboarding for new contributors.

Conclusion

Lab 8 taught me the importance of integrating CI workflows into development projects. CI ensures consistent quality control and fosters collaboration, making it an invaluable tool in modern software development.

You can check out my project’s successful CI run and the pull request to my partner’s project below:

CI Workflow Run: GitHub Actions
Partner's Repo PR: Pull Request #11

This lab has truly enhanced my understanding of automation, testing, and collaboration in open-source development.

Testing Frameworks in Action: A Deep Dive into Automated Testing for EnglishFormatter

Fahad Ali Khan — Wed, 20 Nov 2024 02:51:54 +0000

Automated testing is an essential part of any robust software development workflow. It ensures code quality, minimizes regressions, and provides confidence in the software’s behavior. In this blog, I’ll share my journey through Lab 7, which revolved around incorporating testing into my EnglishFormatter project. From selecting tools to mocking responses and uncovering bugs, here’s how it all unfolded.

1. Choosing the Testing Framework

For this project, I chose Google Test (GTest) and Google Mock (GMock) as my testing framework. These tools are the gold standard in the C++ world for writing unit tests and mocking dependencies.

Why GTest and GMock?
- GTest provides a simple and powerful framework for writing tests with descriptive assertions.
- GMock enables mocking of external dependencies, which is crucial for testing interactions with APIs or other services.
- Both are well-documented and actively maintained, with a vibrant community for support.
Links:
- Google Test
- Google Mock

2. Setting Up the Framework

Setting up GTest and GMock in my project involved the following steps:

Installing GTest and GMock

Linux:

  sudo apt-get install libgtest-dev
  cd /usr/src/gtest
  sudo cmake .
  sudo make
  sudo cp *.a /usr/lib

Windows: I downloaded the source code from GitHub and built the libraries using CMake.

Adding Tests

Created a tests.cpp file to house all test cases.
Linked GTest and GMock during compilation:

   g++ -std=c++17 -I<gtest-include-path> -I<project-include-path> tests.cpp -o tests -lgtest -lgmock -lpthread

Running Tests

After building, I ran the tests:

./tests

The output showed which tests passed or failed, with detailed information for debugging.

3. Mocking LLM Responses

One of the challenges in this project was testing the interaction with an external Language Model (LLM) API. Since relying on a live API during testing is impractical, I mocked the responses using GMock.

Approach to Mocking

I created a MockApiClient class that inherited from api_client.
Using MOCK_METHOD, I defined mock behaviors for the make_api_call method.
Example:

  class MockApiClient : public api_client {
  public:
      MOCK_METHOD(std::string, make_api_call, (const std::string& prompt), (override));
  };

  TEST(MockApiClientTests, MockedApiResponse) {
      MockApiClient mockClient;
      EXPECT_CALL(mockClient, make_api_call)
          .WillOnce(::testing::Return(R"({"choices": [{"message": {"content": "Mock Response"}}]})"));

      std::string response = mockClient.make_api_call("Test Prompt");
      EXPECT_EQ(response, R"({"choices": [{"message": {"content": "Mock Response"}}]})");
  }

This allowed me to simulate different API responses (e.g., success, errors) without making actual network calls.

4. Learning Through Test Case Writing

Writing tests was an enlightening experience, filled with both challenges and "aha!" moments. Here’s what I learned:

Lessons Learned

Testing Forces Better Code:
Writing tests made me realize areas where my code was tightly coupled or lacked error handling. Refactoring for testability improved the overall design.
Mocking Simplifies Complex Testing:
Mocking external dependencies like the LLM API allowed me to focus on testing my code rather than external services.

Challenges and "Aha!" Moments

Initially, setting up Google Mock felt intimidating due to its many features. However, once I understood the syntax, it became straightforward and incredibly powerful.
I realized the importance of edge cases—what happens when the API returns an unexpected JSON format? This led to more robust parsing logic.

5. Bugs and Edge Cases

Bugs Uncovered

Empty Environment Variables:
A missing API_KEY or API_URL caused runtime errors. Adding unit tests for these scenarios led to meaningful error messages instead of crashes.
Invalid API Responses:
Parsing logic failed on API responses missing the choices field. Tests caught this, prompting me to add error handling.

Edge Cases

Responses with empty or malformed JSON.
Unexpected data types in the JSON response (e.g., choices being a string instead of an array).

6. Reflections and Future Plans

This lab reinforced the value of testing in software development. Before this project, I had limited experience with formal testing frameworks. Now, I feel confident in my ability to write meaningful test cases and mock external dependencies.

Future Testing Plans

Continuous Integration: I plan to integrate automated testing into a CI/CD pipeline using GitHub Actions.
Code Coverage: Analyzing code coverage will ensure all critical paths are tested.
More Mocks: Expanding mocks to simulate other parts of the system.

Conclusion

Automated testing is not just about catching bugs—it's a mindset shift that promotes better design and maintainability. Tools like GTest and GMock make testing in C++ approachable and effective. This lab was a fantastic opportunity to sharpen my testing skills, and I’m excited to apply these practices to future projects.

If you're working on a project and haven't tried automated testing yet, I encourage you to start. Your future self (and your users) will thank you!

Your Thoughts?

Have you used Google Test or similar frameworks in your projects? What challenges have you faced in testing? I’d love to hear about your experiences!

Improving Documentation in Theoretica

Fahad Ali Khan — Tue, 12 Nov 2024 03:23:47 +0000

In my latest contribution to the open-source library Theoretica, I tackled Issue #81 focused on refining and enhancing the inline documentation for two central components: mat (the matrix class) and vec (the vector class). This issue was raised to improve the readability and usability of these classes, which are essential in mathematical computations and commonly used across various areas in the library. Proper documentation is key to making complex code accessible to other developers and contributors.

Issue Summary

The main goal of the issue was to update and improve the existing documentation for mat and vec classes. This involved:

Adding clear, concise explanations for each function in both classes.
Using consistent language and structure throughout.
Removing redundancies and improving clarity, especially in cases where documentation was minimal or missing.

For anyone unfamiliar with these classes, mat represents an N x K matrix with templated types, while vec represents an N-dimensional vector. Both classes support various mathematical operations, such as addition, subtraction, scalar multiplication, and vector transformations.

Preparation for the Fix

Before diving into the documentation, I took time to thoroughly understand the structure of the mat and vec classes. This was essential because the codebase for these classes is quite extensive and contains advanced template programming techniques. Each function’s purpose, inputs, and outputs needed to be understood to accurately document them.

One of the initial challenges was ensuring I had a local development environment set up to properly view, test, and verify changes. I cloned the repository, configured the project, and set up Doxygen to generate HTML documentation to visualize changes effectively.

Learning Curve

Working on this documentation required understanding some complex aspects of C++ template programming. Since the library uses advanced C++ techniques such as templates, inline functions, and recursive function calls for implementing mathematical operations, I reviewed the theory and usage of these constructs to confidently write documentation that would be both accurate and clear for other developers.

I also had to familiarize myself with Doxygen conventions, as these would be used to generate structured documentation for the library. Specifically, I focused on how to organize documentation comments effectively without using @brief for this issue, as I aimed for a more descriptive style in line with the existing documentation.

Implementing the Documentation

The documentation process involved updating each function’s comment to ensure it provided value to the reader. Here’s a breakdown of some key elements of the update:

`mat` Class Documentation

In the mat class, I documented functions that dealt with:

Matrix Operations: Functions such as operator+, operator-, and operator* which handle addition, subtraction, and multiplication of matrices and scalars.
Vector Transformation: Methods like transform and cross that apply matrix transformations to vectors.
Iterator Support: Functions like begin and end that enable iteration over matrix elements.

For each function, I included a description of the operation, the expected input types, and the output. For example, the documentation for transform reads as follows:

/// Transforms a vector by applying this matrix to it. 
/// @param v The vector to transform, whose size must match the matrix column count.
/// @return A new vector resulting from the transformation.
/// Raises an error if the vector size does not match the column count of the matrix.

`vec` Class Documentation

For the vec class, the focus was on:

Basic Vector Operations: Addition, subtraction, and scalar multiplication functions.
Dot and Cross Products: I documented the mathematical implications of these functions and how they are computed internally.
Normalization: I clarified the purpose of the normalize and normalized functions and explained how they can be used to obtain unit vectors.

Here is an example of the normalize function’s documentation:

/// Normalizes the vector in place, adjusting it to have a magnitude of 1.
/// This changes the vector’s direction without altering its direction.
/// Throws an error if the vector’s magnitude is zero.

Highlights of the Fix

The Pull Request #92 includes detailed comments on each function, designed to make Theoretica’s core classes more accessible to users. By structuring the comments consistently, I ensured that users would find it easier to understand both the functionality and usage of mat and vec.

An interesting part of this PR was adding documentation for recursive functions like make_vec, which constructs vectors from multiple elements by using variadic templates. I provided clear explanations for how each argument in the parameter pack is assigned to successive elements in the vector.

Challenges and Overcoming Obstacles

The main challenge was understanding the nuances of each mathematical operation within the mat and vec classes. Each function had subtle requirements and constraints, especially when dealing with template parameters and generic data types. I overcame this by diving into each function’s implementation, running sample cases, and referencing C++ template programming guides.

Additionally, understanding the project maintainer’s preferences around documentation style was crucial. For example, they preferred that @brief not be used, so I adapted the documentation style to fit the existing codebase conventions.

Interaction with Project Maintainers

Working with the project maintainers was smooth. They provided helpful feedback regarding documentation style preferences, which helped refine the PR. This feedback loop ensured that the final submission met the maintainers' standards.

Final Thoughts and Next Steps

Working on this documentation update gave me valuable insights into advanced C++ programming and the importance of clear documentation in open-source projects. As next steps, I’d like to contribute more to Theoretica’s documentation efforts, potentially expanding documentation coverage across other classes and modules.

You can view my contributions in Issue #81 and Pull Request #92. If you're interested in contributing to Theoretica, there are plenty of opportunities for improving documentation and testing across the codebase, so consider jumping in!

Enhancing the Shortlist Modal in Recruitify

Fahad Ali Khan — Fri, 08 Nov 2024 23:24:31 +0000

Issue Overview

I recently worked on an issue in the Recruitify project that focused on enhancing the appearance and usability of the Shortlist Modal. The goal was to improve the user experience by updating the styling, layout, and visual effects within the modal. You can find the original issue here: Recruitify Issue #41.

What Was the Issue About?

The issue requested improvements to the modal's UI, specifically asking for:

Consistent padding and spacing between elements
Better button styling with hover effects
Enhanced modal appearance with shadow/blur effects and rounded corners
A more vibrant color scheme with high contrast

The objective was to make the modal look cleaner and more accessible, while also improving its interactivity and focus.

Preparing for the Fix

Before jumping into the fix, I needed to set up the Recruitify project on my local machine and ensure both the frontend and backend components were running smoothly. This involved configuring MongoDB, Redis, and other dependencies in .env files. Setting up the project took a bit of time as I encountered some issues with MongoDB authentication and Redis connection, which I managed to resolve after a few trials.

Learning Requirements

To complete this fix, I needed to:

Familiarize myself with Recruitify’s existing code structure, especially how modals were implemented.
Understand CSS modules and how to create modular styling in React applications.
Apply knowledge of UX/UI principles to improve accessibility and visual appeal.
Learn about React Router for adding a test route (/modal-sandbox) to easily access and test the modal changes.

Code Explanation and Fix

The main changes were made in modal.module.css, which styles the ShortlistModal component. Here’s a breakdown of the improvements:

Overlay Styling:
- I added a semi-transparent background overlay with a slight blur effect to make the modal stand out and provide a clearer focal point.

   .modalOverlay {
     background: rgba(0, 0, 0, 0.7);
     backdrop-filter: blur(3px);
   }

Modal Content Box:
- To give the modal a more professional look, I applied rounded corners, a subtle shadow, and a smooth fade-in animation. This makes the modal appear less rigid and more approachable.

   .modalContent {
     background: #ffffff;
     padding: 30px;
     border-radius: 12px;
     box-shadow: 0px 8px 16px rgba(0, 0, 0, 0.3);
     animation: fadeIn 0.3s ease;
   }

Button Styling:
- The "Submit" button was given a vibrant blue color, while the "Cancel" button was styled with a soft grey. Hover effects were added to make the buttons more interactive, scaling them up slightly when hovered.

   button[type="submit"] {
     background-color: #4A90E2;
     color: #ffffff;
   }
   button[type="button"] {
     background-color: #CCCCCC;
     color: #333333;
   }

Input Field:
- I styled the input field with consistent padding, a soft border, and a focus effect. This makes it more accessible and visually pleasing.

Before and After

Before:

The modal had minimal styling, with no shadow or rounded corners. Buttons lacked hover effects, and the overall look was plain.

After:

Consistent spacing between elements makes the layout cleaner.
Shadow and rounded corners give the modal a polished look.
Button hover effects improve interactivity.
Color scheme enhances accessibility, with vibrant colors and good contrast.

Research and Challenges

I did some research on modal accessibility, specifically how to create a visually appealing modal that remains functional and accessible. I also reviewed CSS best practices for animations and hover effects.

The biggest challenge was configuring the Recruitify project locally, as it required connecting to both MongoDB and Redis services. MongoDB’s authentication errors initially prevented me from running the backend, but I resolved this by checking the database credentials and permissions.

Another challenge was ensuring the modal looked good across different screen sizes. I added responsive adjustments and tested the modal on various devices.

Interaction with Project Maintainers

Since I was delayed in responding to the issue due to midterms, I posted an update apologizing for the delay and notifying the maintainer about my PR. They were understanding and provided positive feedback on my progress.

Difficulties and Solutions

The most difficult part was configuring the project environment to run smoothly. By reading MongoDB and Redis documentation and experimenting with different configurations, I was able to resolve the issues. I also added a test route (/modal-sandbox) to make it easier to access the modal without needing the full backend setup.

Link to Pull Request

Here’s the link to my pull request, which contains the updated modal styling: Recruitify PR #67

Overall, this issue helped me improve my CSS skills and learn about modal accessibility. It was a valuable experience, and I’m looking forward to making more contributions in the future!

DEV Community: Fahad Ali Khan

Building an AI-Generated Text Detector: A Full-Stack NLP Project Guide

Commit 1: The Foundation — Clean Init

Commit 2: Linguistic Feature Extraction

Commit 3: Ensemble Model

Commit 4: FastAPI REST API

Commit 5: Gradio Interactive Demo

Commit 6: Unit Tests

Commit 7: Docker Support

Commit 8: GitHub Actions CI

Commit 9: README and License

What Makes This Resume-Worthy

Building an Animated Portfolio Hero with GSAP, SplitText, and a Canvas Particle Background

The goal

Layer 1 — Character-by-character text animation

Layer 2 — Social icons with liquid morph hover

Layer 3 — Entrance timeline orchestration

Layer 4 — Canvas particle background

Responsiveness challenges

UX lessons learned

Motion should guide attention

Physics > gimmicks

Cleanup matters

Performance first

Final thoughts

Trying to blog again...

Delivering a Production-Ready Timesheet Automation and Emailing Solution

Introduction

What’s New in the Final Release?

Measuring My Goals and Success

Lessons Learned

Future Potential

Conclusion

Finding My Footing in Open-Source Timesheet Automation

Blog Post 1: Progress Update

Introduction

What I’ve Accomplished So Far

Challenges and Solutions

Adjusting Course for the Final Release

Conclusion

My Release 0.4 Open-Source Journey - From Planning to Delivery

Introduction

Setting the Stage (Week 1 Plans)

Mid-Project Progress (Week 2 Update)

Final Results (Consolidated Outcomes)

Conclusion

Implementing and Integrating Email Automation in a Python Timesheet Project

Blog Post: Implementing and Integrating Email Automation in a Python Timesheet Project

Introduction

Context and Challenges

Issue #2 and #3: Foundations for Email Data Generation and Sending

PR #4: Introducing Email Data Generation

PR #5: Sending Automated Emails After Timesheet Updates

Process and Time Management Reflections

How I Measured My Progress from 0.2

Links and References

Conclusion

Streamlining C++ Project Releases with CMake and Vcpkg

Table of Contents

Choosing the Right Tools

Process for Creating a Release

1. Setting Up the Project with CMake

2. Managing Dependencies with Vcpkg

3. Configuring Git for Releases

4. Building and Testing

5. Publishing the Release on GitHub

Lessons Learned

Adjustments Made to the Project

User Testing with macOS

Setup

Testing Process

Observations and Feedback

Corrections Made

Installing and Using EnglishFormatter

Installation Steps

Usage Instructions

Running via Command-Line Options

Using the Interactive Menu

Conclusion

Resources and Links

`mat` Class Documentation

`vec` Class Documentation