HEARTREAD

• 

  homescreen for heartread

Inspiration

I'm going to be honest about where this idea actually came from, because it's the real reason I built it. I met a girl during orientation in my first year at campus. At first, she liked me _ but I wasn't serious about it back then. By the time we reached second semester, things had flipped. She used to hug me a lot, and somewhere in there I ended up falling for her _ right around the time I think she'd already started losing interest. What confused me wasn't a clear rejection. It was the mixed signals. Physically, she still gave me attention _ initiating hugs, holding my arm when we walked. But online, she'd ignore my texts and barely pick my calls. I cared about her, but she never seemed to take that seriously. And I kept going back and forth in my head: does she like me or not? I'd replay every hug, every ignored text, trying to find an answer that never came. I never really got clarity. I just had a lot of confusion and no one objective to ask. That's where HeartRead came from _ not a hackathon brainstorm, but an actual situation I was stuck in and wished I had something to help me make sense of.

What it does

HeartRead asks you five honest questions about your situation _ who the person is, what signs made you think they liked you, what's making you doubt it, and how your last interaction felt. Then it gives you a real verdict: Likely Interested, Mixed Signals, Probably Just Friendly, or Hard to Tell _ along with a breakdown of the good signs, the confusing ones, and anything you should be careful about. It also has a Signal Tracker, so you can log interactions over time and see if things are actually warming up or cooling down instead of just guessing. And a "What to Say" feature, because half the time the hardest part isn't understanding the situation _ it's knowing what to actually type back.

How we built it

we used Streamlit for the app itself and the Groq API running Llama 3.3 70B for the AI analysis, mainly because it's free and fast. Getting the AI to return clean, structured JSON every time took a lot of trial and error _ it kept adding extra text or breaking the format in ways that crashed the app. we deployed it on Streamlit Cloud so anyone can actually use it, not just me on my laptop.

Challenges we ran into

Honestly, a lot of the hardest parts weren't even the AI _ they were the basics. we are still learning Git and GitHub properly, and we ran into real trouble with API keys getting exposed, GitHub blocking my pushes because of leaked secrets, and just generally fumbling through the terminal. It was frustrating, but I learned more from fixing those mistakes than I would have from a tutorial.

Accomplishments that we're proud of

But honestly, what we most proud of is that it came from something real. we built something useful out of my own confusion instead of just picking a random problem to solve. If even one person uses HeartRead and feels a bit more clarity instead of lying awake overthinking a text that never came _ like I did _ then this project already did what I wanted it to do.

What we learned

we learned that you don't need a complicated idea to build something people actually need — you just need to pay attention to your own life. The confusion I felt with that girl is something almost everyone has felt at some point. I also learned a lot of practical skills I didn't have before: working with APIs, managing environment variables, deploying an app, and just being more comfortable in the terminal.

What's next for HEARTREAD

I still think about that situation sometimes _ the hugs that meant attention but the texts that meant distance. I'd like to build HeartRead out further so it can track multiple people at once, since most people aren't just confused about one person at a time. we also want to make the tracker smarter, so it can pick up on patterns over weeks instead of just single moments.

Built With

• github
• groq
• python
• streamlit
• streamlitcloud