I had just finished building a mental health text classifier and wanted to build something completely different. Not another model. Something more practical.

I had never worked with PDF documents programmatically before, and that gap bothered me. Almost every hospital gives patients their lab reports as PDFs. They're easy to download and share, but most people can't make sense of what's actually written inside them.

I wanted to understand how applications read PDFs. So I picked a project that would force me to learn.

The result was an AI-powered web application that takes a digitally generated medical report, extracts its contents, and explains the results in plain language using Google's Gemini API.

It started as an excuse to learn PDF parsing. It ended up teaching me quite a bit more.

Why This Project

Medical reports are interesting documents.

Unlike essays or articles, they're packed with structured information: test names, measured values, reference ranges, units, and patient details. To a person without a medical background, most of it looks intimidating. To a computer, it's simply text inside a PDF.

I wasn't trying to build a medical product or solve healthcare problems. I simply wanted a real-world problem that would push me to learn document processing, REST APIs, and AI integration.

Medical reports turned out to be a perfect fit. Structured, real-world, and actually useful to people.

What the Application Does

The application accepts a digitally generated PDF lab report uploaded by the user.

The backend extracts the report text using PyMuPDF, sends that text to Google Gemini, and asks the model to return a structured JSON response instead of a paragraph. The frontend then presents that information in a cleaner format, highlighting abnormal values, displaying gender-appropriate reference ranges where applicable, explaining each parameter in plain language, and suggesting a few questions the patient could discuss with their doctor.

It isn't designed to diagnose conditions or replace medical advice. The goal is simply to make medical reports easier to understand.

Learning Objective: PDF Parsing

Before starting this project, PDF parsing felt almost magical.

You upload a document, call a library function, and somehow all the text appears.

I quickly learned it isn't that simple.

The biggest realization was that not all PDFs are actually text documents.

Digitally generated PDFs contain selectable text, which libraries like PyMuPDF can extract quite reliably.

Scanned reports are completely different.

They're just images embedded inside a PDF file. There's no text to extract, which means OCR becomes a completely separate problem.

That single distinction ended up defining the scope of the project. Rather than trying to solve both problems at once, I decided to support only digitally generated reports and mention that limitation clearly in the README.

Sometimes understanding what not to build is just as useful as understanding what to build.

How Everything Fits Together

The overall architecture stayed surprisingly simple.

User uploads PDF  →  FastAPI receives the file  →  PyMuPDF extracts text → Gemini analyzes the report  → Returns structured JSON → React renders the results

Each part has one responsibility.

FastAPI handles the upload.

PyMuPDF extracts the raw report text.

Gemini converts that text into structured information that the frontend can easily display.

React simply focuses on presenting the results in a readable way.

Keeping each component responsible for one job made debugging much easier later on.

I chose Gemini because it offered a free tier. Most other options required payment upfront, which wasn't practical for a learning project.

The Debugging

Like every project I've built so far, the interesting part wasn't writing the code.

It was figuring out why the code wasn't working.

The Wrong Model

The first API call returned a 404 error.

At first I assumed something was wrong with authentication or my request format. After checking the documentation more carefully, I realized I was trying to use a model that wasn't actually available for the API version I was calling.

The fix took seconds.

Finding the real cause took much longer.

The Free Tier Reminder

Once the requests finally started working, I immediately ran into another error.

429 : Resource Exhausted.

I'd simply reached the free-tier quota.

There wasn't a clever engineering solution here.

I had to wait for the quota to reset before continuing development.

It was a useful reminder that building with cloud AI APIs also means understanding their usage limits.

JSON That Wasn't Really JSON

The last issue was probably my favorite.

I asked Gemini to return JSON.

It did.

Sort of.

Instead of returning raw JSON, it wrapped everything inside markdown code fences.

Perfectly readable for a human.

Not valid input for json.loads().

The backend kept failing until I stripped those wrappers before parsing the response.

It was a small bug, but one that taught me an important lesson: when another system generates your data, never assume the format is exactly what you requested.

Prompt Engineering Was More Important Than I Expected

Initially, I wrote prompts the way I would talk to ChatGPT.

"Explain this medical report."

The responses were well written.

They were also completely unusable.

Every response had a different structure, different formatting, and different wording. That made building the frontend almost impossible.

The project became much simpler once I stopped asking for explanations and started asking for structured data.

Instead of requesting a paragraph, I asked Gemini to return only valid JSON matching a predefined schema.

That single change made the entire application much more reliable.

It also changed how I think about prompt engineering. Good prompts aren't just about getting better answers. Sometimes they're about getting answers your software can actually work with.

Small Design Decisions That Mattered

There are a few features I'm particularly happy with, not because they're complicated, but because they were intentional.

Rather than simply labeling values as "normal" or "abnormal," I highlighted abnormal parameters visually so they stand out immediately. Where medical reference ranges differ by gender, I asked the model to account for that instead of assuming one universal range.

One feature I especially liked was generating a few suggested questions patients could ask their doctor. The application shouldn't replace professional advice, but helping someone understand what they might want to ask felt genuinely useful without crossing that line.

Responsible AI, Again

If you've read my previous post about the Mental Health Classifier, this section will probably sound familiar.

Whenever I build something involving health-related information, I try to be explicit about what the application is and what it isn't.

This project simplifies reports.

It does not diagnose illnesses.

It does not replace a doctor.

It does not provide medical advice.

That disclaimer isn't there because it looks professional.

It's there because I think setting the right expectations is part of building software responsibly, especially in domains where incorrect information could affect someone's health.

What I Learned

This project started because I wanted to learn PDF parsing, but that's only a small part of what I ended up taking away from it.

I learned that extracting text is usually the easy part; getting reliable, structured information from that text takes much more thought. I learned that prompt engineering often has more to do with software design than with writing clever prompts. I also realized that integrating an LLM into an application isn't really about AI , it's about building a reliable pipeline around it, handling unexpected outputs, validating responses, and making sure every component has a single responsibility.

Perhaps the biggest lesson, though, is that projects become much more enjoyable when they're driven by curiosity rather than by trying to build the biggest thing possible. I started this project because I wanted to understand how PDFs work. Everything else grew naturally from that.

Where It Lives Now

The application is deployed with a React frontend on Vercel and a FastAPI backend on Render.

At the moment, it supports only digitally generated PDFs. Supporting scanned reports would require adding an OCR pipeline, which is something I'd like to explore in a future version.

Like my previous projects, it's not perfect.

But it's deployed, it works, and it taught me far more than I expected when I first decided to learn how to read a PDF.

Frontend: https://medical-report-simplifier-eta.vercel.app

GitHub: https://github.com/ishwarimulye/medical-report-simplifier

If you're also building ML projects as a student and want to talk about it, find me on GitHub or LinkedIn.

In my last post, I wrote about building a mental health text classifier ,starting with TF-IDF and XGBoost, then fine-tuning DistilBERT to get from 74% to 81% accuracy. If you haven't read it yet, you can find it here: [From TF-IDF to Transformers: Rebuilding My Mental Health Classifier]

This post isn't about model accuracy or transformers. It's about a feature I almost added to my app, removed within seconds, and have thought about ever since.

The feature was a list of mental health helpline numbers.

The decision seemed minor, but the more I thought about it, the more I realized it carried real consequences. 

The Suggestion That Made Sense on Paper

When I was designing the Gradio interface for the app, adding helpline numbers came up as a UI suggestion. On the surface, it made complete sense, having a helpline number after putting lines of assurance for people using the assistant.  The app classifies mental health-related text. Some of those categories like  suicidal ideation, severe depression, are serious. If someone is using the app and sees a concerning result, having a helpline number right there feels responsible,caring and thoughtful.

It was a good UI decision.

And my immediate reaction was: no. This doesn't feel right.

Why It Didn't Feel Right

I didn't have a long internal debate about it. The instinct was immediate, and when I sat down to think through why, a few things became clear.

The tool is educational, not clinical.

I built this as a learning project. It is not a diagnostic tool. It is not built or validated to the standard that would make it appropriate for someone in crisis to rely on. Adding helpline numbers would imply a level of responsibility and seriousness that the app simply does not have, at least at that moment. It would make a student project look like a mental health resource, and those are very different things.

Inaccurate or outdated numbers could cause real harm.

Helpline numbers change. Organizations shut down. Numbers get reassigned. If someone really needs help and they call a number from my app that no longer works, that moment of failed connection could matter in a way that's hard to overstate.

A broken link in a portfolio project is an inconvenience. A broken helpline number in a crisis is something else entirely.

 I had no way to guarantee those numbers would stay accurate. I had no system to update them. I had no organization behind me validating them.

One more thing to note here is that HuggingFace Spaces is accessible to anyone, anywhere. A helpline number that works in India means nothing to someone in another country. And thus discovering that a number doesn't work isn't just unhelpful, it could make things worse, for a person in crisis. 

This information should come from proper organizations.

There are government portals, established mental health organizations, and verified platforms whose entire purpose is to maintain accurate, up-to-date crisis resources. That responsibility belongs with them, not with a third-year student's ML project. 

It felt wrong to take on that responsibility casually, just because it looked like a good feature to add. 

What I Did Instead

I kept the disclaimer visible in the app and in the GitHub README:

"This tool is for educational purposes only and is NOT a substitute for professional mental health care."

That felt honest. It sets the right expectation without overstepping.

Anyone who needs real help should be directed to real resources. But I wasn't equipped to maintain or verify crisis resources myself, and I didn't want my project to imply a level of authority or responsibility that it didn't have.

Organizations dedicated to mental health support have the systems and expertise to keep this information accurate and up to date. As a student project, my app simply wasn't the right place to take on that responsibility.

What This Taught Me

I didn't know the term "responsible AI design" when I made this decision. I just knew something felt off.

But looking back, that instinct was about something real: the gap between what a feature looks like and what it actually does. Adding helpline numbers would have looked caring. But without accuracy, without maintenance, without the right organizational backing, it could have done more harm than good.

Building AI for sensitive domains means asking not just "does this feature make sense?" but "what happens if this feature fails?" For most features, failure is a minor inconvenience. For some, it isn't.

Every feature should be thought through carefully. User experience matters, but so does responsibility as a developer. 

A Note to Other Student Developers

If you're building something that touches mental health, medical information, financial advice, or any other sensitive domain — pause before you add features that look helpful on the surface. Ask who is responsible for keeping that information accurate. Ask what happens if it's wrong. Ask whether your project is the right place for that responsibility.

That's something I'll carry into every project I build from here. Sometimes the most responsible thing you can do is leave something out. 

Find me on GitHub or LinkedIn

I finished a supervised machine learning course a few months ago and immediately wanted to build something with it. Not a tutorial project. Something that felt real.

I am a third-year Computer Engineering student, and I was always fascinated by how large language models like ChatGPT are able to detect emotion through text. Using that curiosity, I decided to build a model that could classify mental health-related text. Not because it was assigned. Not because it was easy. Because I wanted to see if I could.

Why This Project

Mental health conversations online are everywhere: Reddit posts, anonymous forums, support communities, Twitter. I wanted to explore whether a model could understand the emotional weight behind someone's words, what that person could be going through, whether that's anxiety, depression, stress, or something more serious like suicidal ideation, and categorize them meaningfully.

It felt important and exciting at the same time. And honestly, that feeling kept me going when things broke.

Version 1: TF-IDF + XGBoost

I started by reading about TF-IDF. This concept was completely new to me, and after reading about it I wanted to try everything I had just learned.

I used a publicly available mental health dataset from Kaggle: Sentiment Analysis for Mental Health by Suchintika Sarkar. The categories for classification were anxiety, bipolar, depression, normal, personality disorder, stress, and suicidal.

The preprocessing pipeline alone taught me more than I expected. I had to handle HTML tags, URLs, contractions, stopwords, and numeric tokens. Each one is a small decision that affects what the model actually sees. I used TF-IDF vectorization with unigrams and bigrams, capped at 5000 features, which gives the model some sense of two-word phrases like "feeling hopeless" rather than just individual words.

For modeling, I went with Logistic Regression first as a baseline, then added class weighting to handle the imbalance in the dataset, and finally trained XGBoost. I evaluated everything with accuracy, macro F1, precision, recall, and 5-fold cross-validation to make sure results were stable and not just lucky splits.

Here's how they compared:

XGBoost won, particularly on minority classes, which matters in a mental health dataset where underrepresented categories are often the most clinically important ones. I also ran a small experiment removing numeric tokens entirely, which slightly hurt performance. A concrete reminder that "clean the numbers" isn't always the right call.

So the results were decent. And for about a week, I thought I was done. But at the same time I felt something was missing, that there must be something that could be improved.

Then I started looking at what the model got wrong.

The problem was fundamental. TF-IDF treats every word as an independent feature. It has no concept of meaning or context. Consider these two sentences:

"I feel empty" and "I feel hollow inside"

To TF-IDF, these share almost no features. To a human, they're saying the same thing. That gap, between surface-level pattern matching and actual semantic understanding, is what pushed me to start over.

Version 2: Fine-tuning DistilBERT

That gap pushed me to look for something better. I started researching what else could be used for text classification and came across transformers. Reading about attention mechanisms for the first time felt like a light switching on. The original transformer paper genuinely excited me, and it was enough to make me want to dive back into the project.

DistilBERT is a lighter, faster version of BERT that still captures contextual meaning. When it reads a sentence, it understands each word in relation to the words around it, not in isolation. For a dataset where categories like depression, stress, and anxiety overlap heavily in language, that distinction matters enormously.

The workflow looked like this: I used DistilBERT's subword tokenizer with a max length of 128 tokens, built a custom PyTorch Dataset class with attention masks, and fine-tuned for 3 epochs using AdamW optimizer with a linear learning rate scheduler. Nothing exotic, but every piece had to be wired together correctly, and that wiring is where the real learning happened.

The results were a significant jump:

But the number I'm most proud of isn't the accuracy jump. It's what happened after the first training run.

Error Analysis

After initial training, I noticed the model was over-predicting Normal for statements that were actually depression or stress-related. At first I thought the model was just confused. Then I realized it was consistently wrong in the same direction, and that's a different problem entirely.

This wasn't random noise. It was a pattern, rooted in how the dataset was labeled.

Instead of retraining blindly, I did error analysis: looked at which cases were failing and why, then manually adjusted class weights based on observed failure patterns and applied weighted CrossEntropy loss based on those observations.

This is a standard real-world ML debugging technique, but it rarely shows up in beginner projects because it requires you to actually understand your model's mistakes, not just its metrics. That extra step pushed the model from "decent results" to results I could actually stand behind.

The Debugging

Here are the actual things that broke, in no particular order:

token_type_ids incompatibility — DistilBERT doesn't use token type IDs, but the newer tokenizer version was returning them anyway.

The error was TypeError: DistilBertForSequenceClassification.forward() got an unexpected keyword argument 'token_type_ids'.

The fix was one line, filter out token_type_ids before passing inputs to the model. The hour spent figuring it out was not.

Gradio version conflicts — Deploying to HuggingFace Spaces seemed straightforward until it wasn't. Different Gradio versions have different APIs, and the error messages don't always tell you which version is the problem. Each of these felt like a wall when I hit it.

In hindsight, they were the actual education.

I used AI tools throughout this project, not to write code for me, but to understand why things were breaking and what to try next. Every fix still had to make sense to me before I used it. That's a different thing from copy-pasting, and it changed how much I actually retained.

What I Learned

1. Version 1 wasn't a failure, it was a baseline. Starting simple gave me something to compare against. Without v1, I wouldn't have been able to articulate why v2 was better. Build the simple thing first, gain a little confidence in yourself, and then go for the next version.

2. Debugging is a skill, not a sign you're bad at this. Every senior engineer spends most of their time debugging. The difference is they've learned to read errors calmly. I'm still learning this.

3. Deploying is a completely different problem from training. Getting a model to work in a Colab notebook and getting it to work for someone else are two different jobs. Plan for deployment from the start.

4. Error analysis is not optional. If you skip it, you're optimizing a number. If you do it, you're building something trustworthy. Especially for sensitive domains, that distinction matters.

5. The model is only one part of the product. Which brings me to a decision I made near the end, one I want to talk about in a separate post entirely.

Where It Lives Now

The final model is hosted on HuggingFace Hub (ishwarimulye03/mental-health-support-assistant) with a Gradio UI on HuggingFace Spaces. It's not perfect. But it's real, it's deployed, and someone other than me can use it.

That still feels kind of unbelievable.

But before I fully close the chapter on this project, there's one decision I made that I haven't talked about yet. It has nothing to do with accuracy or loss functions. I'll cover it in the next post.

If you're also building ML projects as a student and want to talk about it, find me on GitHub or LinkedIn.