Humanity Passport

We ignite purpose in open-source. Our AI instantly identifies and honors GitHub projects profoundly impacting humanity, awarding a vital recognition badge. Discover code that truly changes the world.

Comment

Inspiration

We've seen a lot in our time, and one thing that always stands out is folks pouring their hearts into open-source projects, truly trying to make the world a bit better. But in that vast, bustling online world of code, those truly special efforts, the ones helping people, solving real problems often just get lost in the shuffle. It always felt a bit wrong to us, like those good deeds weren't getting the notice they deserved.

That feeling, that quiet wish we had to shine a light on the best in us, that's where the Humanity Passport was born. When this Hackathon called for projects "For Humanity," it just clicked for our team. We asked ourselves: What if we could create a simple way to point to those good projects? A clear sign that says, 'Here's something truly helpful, something built with care for others'.

We didn't just want a fancy digital sticker. We wanted to start something bigger. A clear signal that cuts through all the noise online, showing everyone the projects built with kindness and hope. The Humanity Passport is our way of doing just that—a smart little helper that gives a nod to those earnest developers. It's a way for all of us, judges and coders alike, to see and celebrate the good work, to feel proud of what people can do when they set their minds to helping. It's not just about the code; it's about saying, "We see your good heart."

What it does

Humanity Passport is a Next.js web application designed to identify, evaluate, and publicly recognize open-source software projects that contribute positively to humanity.

Users submit a public GitHub repository URL. Our system then:

  1. Analyzes: Uses OpenAI's gpt-oss-20b model (via Groq API) to assess the project's humanitarian value. This involves analyzing repository metadata, READMEs, and selected code files.
  2. Generates: Creates a dynamic SVG "Humanity+ Passport" badge for approved projects.
  3. Showcases: Publishes a unique "passport page" for each approved project, detailing the AI's rationale for the award.

In essence, it turns socially responsible open-source development into a visible and celebrated achievement, encouraging discovery and contribution to impactful projects.

How we built it

We constructed Humanity Passport using a robust and efficient modern tech stack:

  • Frontend & Backend Framework: Built on Next.js 14 (App Router) for a seamless full-stack experience.
  • AI Core: Powered by OpenAI's gpt-oss-20b model for advanced reasoning and evaluation.
  • Inference Speed: Leveraged the Groq API to achieve exceptional inference speeds (over 1000 tokens/second), ensuring rapid analysis.
  • GitHub Integration: Used Octokit to fetch repository metadata quickly. For deeper content analysis, we integrated LangChain's GitHub repository loader to access relevant files within the repo, paired with LangChain's text splitters to manage document size for AI processing.
  • Data Persistence: Employed Postgres with Prisma ORM for efficient and lightweight storage of project data and analysis results.
  • User Interface: Designed a clean, responsive, and intuitive UI using TailwindCSS and shadcn/ui.

Our development approach was iterative, starting with architectural design, moving through API integrations, prompt engineering, and UI development, all while focusing on performance and security.

Challenges we ran into

  1. Nuanced Prompt Engineering: Defining and consistently evaluating "humanitarian value" is inherently subjective. Crafting the gpt-oss-20b prompt to elicit reliable, well-reasoned, and unbiased verdicts from the AI was our most significant intellectual challenge, requiring many iterations and fine-tuning.
  2. Efficient Repository Data Handling: While LangChain streamlined repository content loading, effectively managing and splitting potentially massive codebases into AI-digestible chunks without exceeding token limits or sacrificing performance proved tricky.
  3. Balancing Speed and Depth: Achieving sub-10-second analysis times while ensuring the AI performed a sufficiently deep evaluation of complex projects was a constant balancing act. The Groq API was a game-changer here, but optimizing every step of the data pipeline was critical.
  4. Security & Content Validation: Protecting against malicious input (e.g., extremely large repos designed to crash the system) and ensuring the AI's output was safe for public display (sanitizing potential XSS vectors).

Accomplishments that we're proud of

  • Rapid AI-Powered Analysis: Delivering a comprehensive AI-driven assessment and a dynamic badge in under 10 seconds, thanks to the synergy of gpt-oss-20b and Groq.
  • Holistic Repository Understanding: Successfully integrating Octokit and LangChain to move beyond mere metadata, allowing our AI to grasp the essence of a project from its actual files and documentation.
  • Intuitive User Experience: Building a polished, easy-to-use web application with Next.js, TailwindCSS, and shadcn/ui that makes the submission and discovery process seamless.
  • Meaningful Impact Potential: Creating a system that directly aligns with the hackathon's "For Humanity" category, with the potential to genuinely amplify and reward socially conscious development.
  • Robust Security Measures: Implementing effective safeguards against common web vulnerabilities, ensuring the platform remains safe and reliable for users.

What we learned

This hackathon was a masterclass in applying AI to real-world problems. We gained profound insights into:

  • The Art of Prompt Engineering: How nuanced phrasing and contextual framing are paramount to guiding powerful LLMs like gpt-oss-20b toward complex, ethical judgments.
  • Intelligent Data Pipeline Design: The critical importance of tools like LangChain for intelligently interacting with and preparing unstructured data (like code repositories) for AI consumption.
  • Performance at Scale: How strategic API choices (like Groq) and careful system design can dramatically impact the perceived responsiveness and utility of an AI-powered application.
  • Full-Stack Agility: The power of a modern stack (Next.js, Prisma, Tailwind) to rapidly prototype and deploy a sophisticated application from concept to execution.

Above all, we learned that technology, when wielded with purpose, can illuminate and elevate the human efforts that truly strive for a better world.

What's next for Humanity Passport

The Humanity Passport is just beginning its journey. Our vision for the future includes:

  • Category Expansion: Introducing more specific "Humanity+" categories (e.g., Environment+, Education+, Health+) for even more granular recognition.
  • Community Curation: Implementing a system for community review or appeals for AI decisions, fostering transparency and human oversight.
  • Enhanced Discovery: Developing advanced search and filtering capabilities to help users find impactful projects by category, technology, or social goal.
  • Integration with Developer Platforms: Exploring deeper integrations with GitHub and other developer platforms for more seamless badge display and project submission.
  • Monetization for Good: Investigating sustainable models (e.g., sponsored categories for NGOs or impact investors) that could further fund and promote humanitarian open-source efforts.
  • AI Feedback Loop: Continuously refining our AI's judgment by incorporating feedback and expanding its training data to include a broader spectrum of "good" projects.

Built With

Share this project:

Updates