ASSESSMENT.md

Apollo MIS — LLM Internship Assessment

Candidate: Kshamaa Suresh Date: March 2026 Time Spent: ~5 hours

Task	Time
Data exploration + DB setup	30 min
Retrieval (BM25)	45 min
Re-ranking (Claude API)	1 hr
Streamlit frontend	1 hr
System design write-up	1 hr
Onboarding proposal	45 min

---

1. Data Setup

What's in the dataset

60 exercises with the following fields: id, title, description, tags, body_part, difficulty, equipment, injury_focus, intensity.

One trailing empty column (Unnamed: 9) was dropped. One bad value in difficulty ("body") was noted — treated as-is since it only affects one row and doesn't break any logic.

Why SQLite instead of PostgreSQL

The assessment suggests PostgreSQL, but SQLite is a better fit here for a few practical reasons:

• No server to spin up — the database is a single file, which means the app works the same locally and on HuggingFace Spaces without any additional setup
• 60 rows is well within SQLite's range; it handles hundreds of thousands of rows without issue
• All queries are standard SQL, so migrating to PostgreSQL later would just be a connection string change

Schema decision

I added a search_text column that pre-concatenates all the text fields used in retrieval (title, description, tags, body_part, equipment, injury_focus, intensity, difficulty). This avoids rebuilding the string at query time and makes the BM25 index straightforward to build.

# setup_db.py — key logic
search_text = " ".join([title, description, tags, body_part,
                        equipment, injury_focus, intensity, difficulty]).lower()

---

2. Query → Recommendations Pipeline

The pipeline has two clearly separated stages:

User query
    │
    ▼
Stage 1: BM25 Retrieval
    │  Tokenises the query and scores all 60 exercises
    │  Returns top 15 candidates with score > 0
    │  (falls back to top 15 regardless if fewer than 3 match)
    ▼
Stage 2: Claude Re-ranking
    │  Sends query + 15 candidates to Claude
    │  Claude scores and orders by relevance, returns JSON
    │  Returns top 5 with a one-sentence reason each
    ▼
Top 3–5 recommendations shown in UI

Why two stages?

Sending all 60 exercises to Claude on every query would work at this size, but it's the wrong pattern:

• At 100k+ exercises, sending everything to an LLM is not feasible
• BM25 quickly filters to a relevant subset — Claude only needs to reason over 15 candidates, not the full corpus
• This separation also makes each stage independently testable

Stage 1 — BM25 Retrieval

BM25 (Best Match 25) is a standard keyword ranking algorithm. It scores each exercise by how well its text matches the query tokens, accounting for term frequency and document length.

Why BM25 and not embeddings?

• No model to download or host
• Works well for domain terms like "knee rehab", "plyometric", "no weights"
• Fast — scores all 60 docs in milliseconds
• At larger scale, a hybrid approach (BM25 + vector search) would be better

# retrieval.py — core logic
corpus = [tokenize(ex["search_text"]) for ex in exercises]
bm25 = BM25Okapi(corpus)
scores = bm25.get_scores(tokenize(query))

Stage 2 — LLM Re-ranking (Mistral-7B via HuggingFace free Inference API)

The LLM receives the query and the 15 BM25 candidates and is asked to return a ranked JSON array of the top 5 with a one-sentence reason for each.

Why re-rank with an LLM?

• BM25 is purely lexical — it can miss a great match if the words don't overlap. An LLM understands intent: "low-impact" implies avoiding jumps and heavy loading even if those words don't appear in an exercise title.
• The LLM can reason about constraints: "no weights" should filter out barbell and dumbbell exercises even if they ranked highly on BM25.

Why Mistral-7B via HuggingFace Inference API?

• Completely free — requires only a free HuggingFace account token
• Strong instruction-following, handles JSON output reliably
• No local GPU or model download needed — the model runs on HF's servers
• Works natively on HuggingFace Spaces (the token is available as a built-in secret HF_TOKEN)

The prompt uses Mistral's [INST] format and asks for a JSON array only, which makes parsing reliable. A regex fallback extracts the JSON if the model adds any preamble text.

---

3. Backend Design

How the backend handles each step

1. User submits query via Streamlit text input
2. retrieve(query, top_k=15) called → BM25 scores exercises → returns list of dicts
3. rerank(query, candidates, top_n=5) called → Claude API call → parses JSON → returns ranked list
4. Streamlit renders results with title, description, difficulty, reason

All of this runs in a single Python process in the Streamlit app. For a production backend, this would be a FastAPI endpoint:

@app.post("/recommend")
async def recommend(query: str):
    candidates = retrieve(query, top_k=15)
    results    = rerank(query, candidates, top_n=5)
    return {"results": results}

How this scales to 100k+ exercises

Problem	Solution
BM25 over 100k docs is slow in memory	Move to Elasticsearch or a vector store (FAISS/pgvector) with an index
Claude can't receive 100k candidates	BM25/vector search still returns only 15–20 candidates for re-ranking — this step doesn't change
Multiple simultaneous users	FastAPI handles async requests natively; Claude API calls are already I/O-bound so they work well with async/await
DB connection pooling	Use SQLAlchemy with a connection pool instead of raw sqlite3
Cold start on DB index	Pre-build the BM25 index at startup and cache it in memory instead of rebuilding on every request

---

4. Frontend

Built with Streamlit. The user can:

• Type a free-text query
• Click one of 4 example queries to pre-fill the input
• See the top 5 results with title, description, difficulty, body part, equipment, intensity, injury focus, and Claude's reason for ranking it

Hosting on HuggingFace Spaces (fully free):

1. Create a new Space with the Streamlit SDK
2. Push all project files
3. HF_TOKEN is automatically available in Spaces as a built-in secret — no manual configuration needed for the re-ranking step
4. HuggingFace handles the rest — free tier is sufficient

Cost breakdown: $0

• SQLite — free, no server
• BM25 — free, runs in memory
• Mistral-7B via HF Inference API — free tier
• Streamlit on HuggingFace Spaces — free tier

---

5. Onboarding Proposal — Personalisation

What data to collect

During onboarding I'd ask users 4–5 quick questions:

Question	Options	Why it matters
What's your main goal?	Rehab, strength, endurance, sport performance	Determines which exercises to prioritise
Any injuries or areas to avoid?	Knee, back, shoulder, groin, none	Hard filters retrieval — don't recommend knee exercises to someone with knee pain
What equipment do you have?	None, bands, dumbbells, barbell, full gym	Filters by equipment field
How would you rate your fitness level?	Beginner, intermediate, advanced	Maps to difficulty field
How intense do you want sessions to be?	Low, medium, high	Maps to intensity field

How it influences retrieval and ranking

At retrieval time: apply hard filters in the SQL query before BM25. For example, a user who said "no equipment" gets a WHERE clause:

WHERE equipment IN ('none', 'bodyweight', 'band')

This reduces the candidate pool before BM25 even runs.

At re-ranking time: inject the user's profile into the Claude prompt:

User profile: rehab goal, knee injury, no equipment, beginner, low intensity
Query: "strengthen my legs"

Claude can then deprioritise any high-intensity or equipment-dependent exercises even if they scored well on BM25.

Inspiration from Spotify / Netflix

• Spotify's Discover Weekly builds a taste profile from listening history and uses it to weight recommendations. The equivalent here is tracking which exercises a user completes or skips — over time, the system learns their preferences without them having to re-answer onboarding questions.

• Netflix's contextual recommendations change based on time of day and recently watched content. A coaching app could similarly adapt — if a user just logged a hard leg session, the next session recommendation should shift toward upper body or recovery work.

• Cold start problem: Both Spotify and Netflix use onboarding to handle new users who have no history. The 4–5 question onboarding above serves the same purpose — it gives the system enough signal to make useful recommendations from day one.