Skip to content

Turn a project into a portfolio-ready GitHub repo

Beginner · 20 min · no code required

A recruiter spends about 30 seconds on your repository. An interviewer might spend five minutes before the call. In that time they need to see: what it does, that it works, that you made real engineering decisions, and that your code is tidy. Most student repos fail the first test: the README is the default template or a single line.

1. The README is the product page

Open with what a busy reader needs, in this order:

README.md
# PolicyPal: RAG assistant for insurance policy documents

Ask questions about long insurance PDFs and get answers with page-level citations.

**[Live demo](https://policypal.streamlit.app)** · [Architecture](#architecture) · [Results](#results)

![Demo: asking about a claim waiting period and getting a cited answer](docs/demo.gif)

## Why
Policy documents run to 80+ pages; customers and agents can't find clauses quickly.
PolicyPal answers in seconds and shows exactly which page each answer comes from.

## Features
- Upload a PDF and ask questions in plain English (or Hindi)
- Answers cite page numbers; refuses when the document doesn't contain the answer
- Hybrid search (BM25 + vectors) with reranking
- Streaming responses, chat history

## Architecture
```mermaid
flowchart LR
    U[User] --> UI[Streamlit] --> API[FastAPI]
    API --> R[Hybrid retriever<br/>BM25 + pgvector] --> RR[Reranker]
    RR --> LLM[LLM] --> API
```

## Results
Evaluated on 60 hand-written questions over 5 real policy documents:

| Version | Answer correctness | Faithfulness | p95 latency |
|---|---|---|---|
| Vector search only | 0.71 | 0.84 | 2.1 s |
| + hybrid search | 0.80 | 0.88 | 2.3 s |
| + reranking | **0.87** | **0.93** | 2.6 s |

## Tech stack
Python 3.12 · FastAPI · Streamlit · PostgreSQL + pgvector · OpenAI / Claude · RAGAS · Docker · GitHub Actions

## Run locally
```bash
git clone https://github.com/<you>/policypal && cd policypal
cp .env.example .env            # add your API key
docker compose up --build       # app on http://localhost:8501
```

## What I learned / next steps
- Chunking by clause headings beat fixed-size chunks by 9 points on correctness.
- Next: table extraction for premium schedules; evaluation in CI.

What makes it work:

  • One-line pitch under the title: what it does and for whom.
  • Live demo link and a GIF at the top: proof it works, before any reading. Record 10-20 seconds with ScreenToGif (Windows), Kap (macOS) or Peek (Linux); keep it under ~5 MB.
  • An architecture diagram. GitHub renders Mermaid code blocks automatically, so no image tools needed.
  • Numbers. A results table with an evaluation, even a small one, puts you ahead of most candidates. It shows you measure instead of guess.
  • Decisions and trade-offs ("why hybrid search", "what I'd do next"). This is what interviewers ask about.
  • Setup that actually works from a fresh clone.

2. A repo structure that looks professional

policypal/
├── app/                    # application code, split into modules
│   ├── api.py
│   ├── retrieval.py
│   └── prompts/
├── ui/streamlit_app.py
├── evals/                  # eval questions and the script that scores them
├── tests/                  # at least a few real tests
├── docs/demo.gif
├── .env.example            # every variable, no secrets
├── .gitignore
├── compose.yaml / Dockerfile
├── pyproject.toml or requirements.txt (pinned)
├── LICENSE
└── README.md

Remove leftovers before you share: test2_final.py, commented-out blocks, notebooks full of errors, print debugging, hard-coded paths like C:\Users\you\Desktop. Run a formatter (ruff format .) once over everything.

3. Small things reviewers notice

Item Why
LICENSE (MIT is the common choice) Without one, nobody may legally reuse your code
Topics (repo About → gear icon: rag, llm, fastapi, langgraph) Makes the repo discoverable
About description and website field = live demo URL Shows on the repo card and your profile
Meaningful commit history feat: add reranking (+7 pts correctness) beats 40 commits called update
A green CI badge A GitHub Actions workflow running tests shows engineering discipline
No secrets in history Reviewers do look; a leaked key is a red flag (see API keys)
Issues for known limitations Shows you know what's missing and how you'd fix it

4. Your GitHub profile

  1. Pin your best 4-6 repositories (profile → Customize your pins). Put the deployed GenAI projects first.

  2. Create a profile README: a repository named exactly like your username, with a README.md. It appears at the top of your profile. Keep it short:

    ### Hi, I'm Asha: GenAI engineer building RAG and agent systems

- 🔭 Building **PolicyPal**, a cited-answer RAG assistant ([demo](https://policypal.streamlit.app))
- 🧠 Stack: Python, FastAPI, LangGraph, pgvector, Claude/OpenAI, Docker
- ✍️ Notes on what I learn: [your blog or notes site]
- 📫 [LinkedIn](https://linkedin.com/in/...) · asha@example.com

  3. Use the same photo and headline as on LinkedIn, and link your GitHub from your resume and LinkedIn.

Two or three finished, deployed, documented projects beat fifteen half-done tutorials. A recruiter can't tell a cloned course project from your own work unless the README shows your decisions and results.

Checklist

  • README: pitch, live demo, GIF, architecture, results, stack, setup, learnings.
  • The setup instructions work from a fresh clone.
  • .env.example, .gitignore, LICENSE, pinned dependencies, a few tests.
  • No secrets, junk files or hard-coded local paths.
  • Topics and About set; repo pinned on your profile; profile README written.

Next: Demo your GenAI project in an interview →