Tutorial for Python developers interested in AI for healthcare. About 12 minutes to read.

Please note: This article is about building software. The tool described here helps people discover research studies. It does not diagnose, treat, or give medical advice, and it cannot decide whether anyone qualifies for a study. Always talk with a doctor before joining a clinical trial.

Polycystic ovary syndrome (PCOS) is one of the most common hormonal conditions. The World Health Organization estimates it affects 8 to 13 percent of women of reproductive age, and that up to 70 percent of cases are undiagnosed. Yet PCOS research still has many open questions, and one of the quiet reasons is that studies struggle to find participants.

On the other side, people living with PCOS often never hear about studies they could join. The information is public, but it's written for researchers: long eligibility lists, medical terms, and hundreds of studies to sort through.

That gap is a perfect job for a recommender. In this article we'll build a tool that takes a person's own description of their situation and finds PCOS studies that may be worth asking their doctor about. We'll use real, live data from ClinicalTrials.gov, the US National Library of Medicine's public registry.

If you read my earlier post on building an AI recommender for national parks, you'll recognize the pattern: hard rules first, then semantic matching, and finally a language model that explains results without inventing anything.

The plan

1. Download recruiting PCOS studies from the ClinicalTrials.gov API.

2. Flatten the nested data into a simple table.

3. Apply hard filters: age, sex, and location.

4. Rank the remaining studies by meaning using AI embeddings.

5. Use an LLM to explain each study in plain language, grounded only in its official text.

6. Wrap it in a small web app.

7. Design it responsibly.

Install the libraries:

pip install requests pandas sentence-transformers anthropic streamlit

Step 1: Download PCOS studies

The ClinicalTrials.gov API v2 is free and needs no API key. We ask for studies about PCOS that are recruiting now or will be soon. Results come in pages, so we follow the nextPageToken until there are no more.

import re
import requests
import pandas as pd

API_URL = "https://clinicaltrials.gov/api/v2/studies"

def fetch_pcos_trials(max_pages=5): 
    """Download recruiting PCOS studies from ClinicalTrials.gov.""" \
    params = { "query.cond": "polycystic ovary syndrome",              "filter.overallStatus": "RECRUITING|NOT_YET_RECRUITING", "pageSize": 100, } 
    studies = []
    for _ in range(max_pages):
        response =     requests.get(API_URL, params=params, timeout=30)
        response.raise_for_status()
        data = response.json()
        studies.extend(data.get("studies", []))
        token = data.get("nextPageToken")
        if not token:
            break
        params["pageToken"] = token
    return studies

studies = fetch_pcos_trials()
print(f"Downloaded {len(studies)} studies")

Be a good API citizen: the API is shared public infrastructure. Keep requests modest and save results locally instead of downloading on every run.

Step 2: Flatten the data

Each study comes back as deeply nested JSON, split into modules like identificationModule, eligibilityModule, and contactsLocationsModule. We pull out only what we need. Ages arrive as text like "18 Years", so a small helper converts them into numbers.

def parse_age(text):
    """Turn '18 Years' or '6 Months' into years. Missing means no limit."""
    if not text:
        return None
    number, unit = re.match(r"(\d+)\s*(\w+)", text).groups()
    number = float(number)
    unit = unit.lower()
    if unit.startswith("month"):
        return number / 12
    if unit.startswith("week"):
        return number / 52
    if unit.startswith("day"):
        return number / 365
    return number

def to_table(studies):
    """Flatten the nested API response into one row per study."""

    rows = []

    for study in studies:
        p = study.get("protocolSection", {})

        ident = p.get("identificationModule", {})
        desc = p.get("descriptionModule", {})
        elig = p.get("eligibilityModule", {})
        locs = p.get("contactsLocationsModule", {}).get("locations", [])

        rows.append({
            "nct_id": ident.get("nctId"),
            "title": ident.get("briefTitle", ""),
            "status": p.get("statusModule", {}).get("overallStatus"),
            "summary": desc.get("briefSummary", ""),
            "conditions": ", ".join(
                p.get("conditionsModule", {}).get("conditions", [])
            ),
            "min_age": parse_age(elig.get("minimumAge")),
            "max_age": parse_age(elig.get("maximumAge")),
            "sex": elig.get("sex", "ALL"),
            "criteria": elig.get("eligibilityCriteria", ""),
            "states": sorted({
                l.get("state")
                for l in locs
                if l.get("country") == "United States"
                and l.get("state")
            }),
            "url": f"[https://clinicaltrials.gov/study/{ident.get(](https://clinicaltrials.gov/study/{ident.get\()'nctId')}",
        })

    return pd.DataFrame(rows)


trials = to_table(studies)

Step 3: Apply hard filters first

Some rules are not a matter of opinion. If a study only accepts people aged 12 to 17, it should never be shown to a 28-year-old, no matter how well the description matches. So we remove those studies before any AI ranking happens.

def basic_filter(trials, age, state=None):
    """Keep studies whose age range fits, that accept women,
    and (optionally) have a site in the user's state."""
    ok_age = (trials["min_age"].isna() | (trials["min_age"] <= age)) & \
             (trials["max_age"].isna() | (trials["max_age"] >= age))
    ok_sex = trials["sex"].isin(["FEMALE", "ALL"])
    result = trials[ok_age & ok_sex]
    if state:
        result = result[result["states"].apply(lambda s: state in s)]
    return result.reset_index(drop=True)

candidates = basic_filter(trials, age=28, state="Texas")

Here's how the filter behaves on a small test set shaped like real API data:

Study                          Ages    Site       age=28   age=28, Texas
Sleep and Metabolism in PCOS   18-40   Texas      kept     kept
Teen PCOS Study                12-17   Colorado   removed  removed
Online Support Program         18+     (none)     kept     removed

Notice the last row: some studies are fully remote and list no physical site, so a strict state filter hides them. A nice improvement is to keep those and label them "remote or site not listed".

Step 4: Rank by meaning with embeddings

Now the AI part. A person might write "I have irregular cycles and I'm worried about my blood sugar". A study might describe itself as "insulin resistance and metabolic outcomes in PCOS". They share almost no words, but they clearly belong together.

Just like the "Milky Way" example in my national parks post, embeddings capture meaning instead of exact words, so these two texts end up close together.

from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")


def rank_studies(candidates, user_text, top_n=5):
    if candidates.empty:
        return candidates

    docs = (
        candidates["title"] + ". " + candidates["summary"]
    ).tolist()

    doc_emb = model.encode(
        docs,
        normalize_embeddings=True
    )

    query_emb = model.encode(
        [user_text],
        normalize_embeddings=True
    )

    scores = (doc_emb @ query_emb.T).flatten()

    return (
        candidates
        .assign(score=scores)
        .sort_values("score", ascending=False)
        .head(top_n)
    )


user_text = "I have irregular cycles and I'm worried about my blood sugar"

top = rank_studies(
    candidates,
    user_text
)

print(
    top[
        ["nct_id", "title", "score"]
    ]
)

Step 5: Explain each study in plain language

Eligibility criteria are written for researchers. A language model can translate them into everyday words. But in healthcare, grounding is not optional. The model must only use the study's official text, must not guess whether the person qualifies, and should turn uncertainty into questions for their doctor.

import anthropic

client = anthropic.Anthropic()
# reads the ANTHROPIC_API_KEY environment variable


def explain_study(study, user_text):
    prompt = f"""
    You help people understand clinical studies in plain language.

    A person described their situation as:
    "{user_text}"

    Official study information:

    Title:
    {study.title}

    Summary:
    {study.summary}

    Eligibility criteria:
    {study.criteria}

    Write three short parts:

    1. What this study is about, in simple words.
    2. The main eligibility requirements, in simple words.
    3. Two or three questions this person could ask their doctor or the study team.

    Rules:
    use ONLY the official information above.
    Do not say whether the person qualifies.
    Do not give medical advice.
    If something is unclear, say so.
    """

    message = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=600,
        messages=[
            {
                "role": "user",
                "content": prompt
            }
        ],
    )

    return message.content[0].text


for study in top.head(3).itertuples():
    print(study.title, study.url)
    print(explain_study(study, user_text))

Why this design matters: the code decides which studies to show, using strict rules and official data. The LLM only explains them. It never picks studies, never invents new ones, and never decides eligibility. That separation is what makes an AI tool trustworthy in a sensitive area like health.

Step 6: Build a simple web app

Save the functions above in trials.py, then create app.py:

import streamlit as st
from trials import fetch_pcos_trials, to_table, basic_filter, rank_studies, explain_study

st.title("PCOS Research Study Finder")

st.caption(
    "For discovery only. This is not medical advice. "
    "Talk with your doctor before joining any study."
)


@st.cache_data(ttl=24 * 3600)
# download once a day, not on every click
def load_trials():
    return to_table(fetch_pcos_trials())


age = st.number_input(
    "Your age",
    min_value=12,
    max_value=80,
    value=28
)

state = st.text_input(
    "US state (optional, full name)",
    ""
)

user_text = st.text_area(
    "In your own words, what would you like help with?",
    "irregular cycles and questions about my metabolism"
)


if st.button("Find studies"):
    candidates = basic_filter(
        load_trials(),
        age,
        state or None
    )

    top = rank_studies(
        candidates,
        user_text
    )

    if top.empty:
        st.info(
            "No matching recruiting studies right now. "
            "Try removing the state filter."
        )

    for study in top.itertuples():
        st.subheader(study.title)

        st.markdown(
            f"View official study page"
        )

        with st.spinner("Explaining in plain language..."):
            st.markdown(
                explain_study(study, user_text)
            )

Run it with streamlit run app.py.

Step 7: Designing responsibly

Building for health is different from recommending movies. These are the principles I followed, and I'd suggest them for any similar project:

• Discovery, not decisions. The tool points people to studies and questions. The doctor and the study team make every decision.

• Rules before AI. Hard requirements like age are applied by plain code, so the AI can't override them.

• Grounded explanations. The LLM only sees official study text and is told not to judge eligibility.

• Privacy by design. The app doesn't store what people type. If you deploy it, avoid logging user text, since health details are sensitive. Also be aware that user text is sent to the LLM provider, so say so clearly in your app.

• Always link the source. Every result links to the official ClinicalTrials.gov page, where the full details and contacts live.

• Respectful language. PCOS is a medical condition, not a personal failing. The app never mentions weight or blame, and it speaks to the person, not about them.

How to measure if it works

For this kind of tool, the most important measure is safety: no result should ever break a hard rule like the age range, so write automated tests for the filters. Beyond that, check relevance (do people find the top studies worth reading?) and clarity (can a non-expert understand the explanation?). Asking a few people with PCOS to try the app and share honest feedback is more valuable than any metric.

Ideas to take it further

You could use the API's location filter to search by distance from the user's city, show which studies are remote-friendly, support other languages, or send a gentle alert when a new matching study starts recruiting. The same design also works for other conditions where research needs more participants, such as endometriosis.

Conclusion

We built a tool that turns hundreds of technical research listings into a short, understandable list of studies worth discussing with a doctor. It uses live public data, strict rules for safety, embeddings to understand what people mean, and an LLM that explains without inventing.

Most of all, it shows that recommendation systems can do more than suggest the next video to watch. Pointed at the right problem, they can connect people with research that may one day improve care for millions.

Data source: ClinicalTrials.gov, U.S. National Library of Medicine. This project is for educational purposes only and is not medical advice.

Tutorial for beginners and intermediate Python developers. About 12 minutes to read.

There are 63 national parks in the United States, and hundreds more around the world. Most travelers only hear about the same five or six. A recommendation system can change that by asking a simple question: what do you actually enjoy outdoors? Then it suggests parks you may never have considered, like a quiet desert under dark skies instead of a crowded valley in peak season.

In this article we will build one step by step. We start with a small dataset, add classic recommendation techniques, then use AI embeddings and a large language model to make the results smarter and easier to understand.

What is a recommendation system?

A recommendation system predicts which items a person is likely to enjoy. Netflix recommends shows, Spotify recommends songs, and our system will recommend parks. There are three main approaches, and good systems usually combine them.

Content-based: Compares the features of parks, such as waterfalls, desert or wildlife, with what the user likes.

Collaborative: Learns from other travelers: people who loved Zion also loved the Grand Canyon.

AI and hybrid: Uses embeddings to understand meaning, and a language model to explain each pick in plain words.

The plan

1. Build a dataset that describes each park.

2. Recommend similar parks with TF-IDF and cosine similarity.

3. Recommend parks from a user's own words, with filters for season and crowds.

4. Add collaborative filtering from traveler ratings.

5. Upgrade to semantic search with AI embeddings.

6. Use a language model to explain the recommendations.

7. Turn it into a simple web app.

Install the libraries first:

pip install pandas scikit-learn sentence-transformers anthropic streamlit

Step 1: Create the park dataset

Every recommender starts with data. For this tutorial we write a small dataset by hand. Each park has a short description, the best season to visit, and a crowd level from 1 (very quiet) to 5 (very busy).

import pandas as pd

parks = pd.DataFrame([
    {"name": "Yellowstone", "state": "WY", "best_season": "summer", "crowd_level": 5,
     "description": "geysers hot springs wildlife bison wolves hiking camping volcanic plateau"},
    {"name": "Yosemite", "state": "CA", "best_season": "spring", "crowd_level": 5,
     "description": "granite cliffs waterfalls rock climbing giant sequoias hiking valley"},
    {"name": "Grand Canyon", "state": "AZ", "best_season": "spring", "crowd_level": 5,
     "description": "canyon views rim hiking rafting Colorado River desert sunsets"},
    {"name": "Zion", "state": "UT", "best_season": "spring", "crowd_level": 5,
     "description": "slot canyons river hiking red rock cliffs desert canyoneering"},
    {"name": "Acadia", "state": "ME", "best_season": "fall", "crowd_level": 4,
     "description": "rocky coastline ocean sunrise mountains biking carriage roads fall colors"},
    {"name": "Great Smoky Mountains", "state": "TN/NC", "best_season": "fall", "crowd_level": 5,
     "description": "misty forests wildflowers black bears waterfalls hiking fall colors"},
    {"name": "Glacier", "state": "MT", "best_season": "summer", "crowd_level": 4,
     "description": "alpine lakes glaciers mountains scenic drive mountain goats hiking"},
    {"name": "Everglades", "state": "FL", "best_season": "winter", "crowd_level": 2,
     "description": "wetlands alligators kayaking birdwatching mangroves wildlife"},
    {"name": "Olympic", "state": "WA", "best_season": "summer", "crowd_level": 3,
     "description": "temperate rainforest moss beaches ocean mountains hiking quiet forests"},
    {"name": "Great Basin", "state": "NV", "best_season": "summer", "crowd_level": 1,
     "description": "dark skies stargazing ancient bristlecone pines caves quiet mountains"},
    {"name": "Big Bend", "state": "TX", "best_season": "winter", "crowd_level": 1,
     "description": "desert river canyons hot springs stargazing dark skies remote hiking"},
    {"name": "Denali", "state": "AK", "best_season": "summer", "crowd_level": 2,
     "description": "tundra wildlife grizzly bears moose mountains remote wilderness"},
])

For a real project, use the free National Park Service API. It returns official descriptions, activities, topics and alerts for every park, which gives your recommender much richer data.

Step 2: Find similar parks with TF-IDF

Computers cannot compare sentences directly, so we turn each description into numbers. TF-IDF gives each word a weight: words that are common in one park but rare across all parks get a high score. "Stargazing" says more about a park than "hiking", because almost every park has hiking.

Then cosine similarity measures how close two parks are, from 0 (nothing in common) to 1 (identical).

from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity

vectorizer = TfidfVectorizer(stop_words="english")
park_matrix = vectorizer.fit_transform(parks["description"])
similarity = cosine_similarity(park_matrix)

def similar_parks(park_name, top_n=3):
    idx = parks.index[parks["name"] == park_name][0]
    result = parks.assign(score=similarity[idx]).drop(index=idx)
    return result.sort_values("score", ascending=False).head(top_n)[["name", "state", "score"]]

print(similar_parks("Zion"))

        name state  score
    Big Bend    TX   0.32
    Yosemite    CA   0.24
Grand Canyon    AZ   0.20

If you loved Zion, the system suggests Big Bend: another desert park with canyons and a river, but far fewer visitors.

Step 3: Recommend from the user's own words

Travelers do not always have a favorite park. They have wishes. We can put their wishes through the same vectorizer and compare them to every park, then apply filters for season and crowd level.

def recommend_for_user(preferences, season=None, max_crowd=5, top_n=3):
    query_vec = vectorizer.transform([preferences])
    scores = cosine_similarity(query_vec, park_matrix).flatten()
    result = parks.assign(score=scores)
    if season:
        result = result[result["best_season"] == season]
    result = result[(result["crowd_level"] <= max_crowd) & (result["score"] > 0)]
    return result.sort_values("score", ascending=False).head(top_n)

picks = recommend_for_user("quiet hiking, stargazing and dark skies", max_crowd=2)
print(picks[["name", "state", "score"]])

       name state  score
Great Basin    NV   0.61
   Big Bend    TX   0.54

Step 4: Learn from other travelers

Content-based filtering only knows what is written in the descriptions. Collaborative filtering learns hidden patterns from behavior. If many people rate Zion and the Grand Canyon highly, those parks are related, even if their descriptions look different.

ratings = pd.DataFrame({
    "user":   ["ana", "ana", "ana", "ben", "ben", "cara", "cara", "cara", "dev", "dev"],
    "park":   ["Zion", "Big Bend", "Grand Canyon", "Zion", "Grand Canyon",
               "Acadia", "Olympic", "Glacier", "Olympic", "Big Bend"],
    "rating": [5, 4, 5, 4, 5, 5, 4, 5, 5, 3],
})

# Rows are users, columns are parks, missing ratings become 0
user_park = ratings.pivot_table(index="user", columns="park", values="rating").fillna(0)

# Compare parks by how the same users rated them
park_sim = pd.DataFrame(cosine_similarity(user_park.T),
                        index=user_park.columns, columns=user_park.columns)

def fans_also_liked(park, top_n=3):
    return park_sim[park].drop(park).sort_values(ascending=False).head(top_n)

print(fans_also_liked("Zion"))

Grand Canyon    0.99
Big Bend        0.62
Acadia          0.00

With real data you would have thousands of users. At that scale, libraries such as surprise or implicit use matrix factorization, which handles large, sparse rating tables much better.

Step 5: Add AI with semantic embeddings

TF-IDF has a weakness: it only matches exact words. If a user types "I want to see the Milky Way", TF-IDF finds nothing, because no description contains "Milky Way". A person would instantly know this means stargazing.

Embeddings fix this. A neural network turns each text into a list of numbers that captures its meaning. Texts with similar meanings end up close together, even when they share no words.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")   # small, fast, free, runs on a laptop
park_embeddings = model.encode(parks["description"].tolist(), normalize_embeddings=True)

def semantic_search(query, top_n=3, max_crowd=5):
    query_emb = model.encode([query], normalize_embeddings=True)
    scores = (park_embeddings @ query_emb.T).flatten()   # cosine similarity
    result = parks.assign(score=scores)
    result = result[result["crowd_level"] <= max_crowd]
    return result.sort_values("score", ascending=False).head(top_n)

picks = semantic_search("I want to see the Milky Way far away from city lights")
print(picks[["name", "state", "score"]])

Now the search understands meaning, and dark-sky parks like Great Basin and Big Bend rise to the top. For hundreds of thousands of items you can store embeddings in a vector database such as FAISS, Chroma or pgvector.

Combining the signals (hybrid)

The strongest systems blend several scores. A simple and effective formula is a weighted sum, for example 0.6 × semantic score + 0.3 × collaborative score + 0.1 × (1 − crowd level / 5). Tune the weights by testing what your users actually click and save.

Step 6: Explain the picks with a language model

People trust recommendations more when they understand why. A large language model can turn a list of scores into a friendly, personal explanation. Here is an example with the Anthropic Python SDK. Any modern LLM API works the same way.

import anthropic

client = anthropic.Anthropic()   # reads the ANTHROPIC_API_KEY environment variable

def explain_picks(user_wishes, picks):
    park_list = "\n".join(
        f"- {row.name} ({row.state}), best in {row.best_season}: {row.description}"
        for row in picks.itertuples()
    )
    prompt = f"""A traveler said: "{user_wishes}"

Our recommender chose these national parks:
{park_list}

For each park, write two friendly sentences explaining why it fits this traveler.
Only use the facts given above. Do not invent details."""

    message = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=500,
        messages=[{"role": "user", "content": prompt}],
    )
    return message.content[0].text

wishes = "I want to see the Milky Way far away from city lights"
print(explain_picks(wishes, semantic_search(wishes)))

Notice the design: the recommender chooses the parks, and the language model only explains them. This keeps results consistent and stops the model from inventing parks or facts. This pattern is often called retrieval-augmented generation (RAG).

Step 7: Turn it into a web app

With Streamlit you can give your recommender a simple interface in a few lines. Save this as app.py together with the code above, then run streamlit run app.py.

import streamlit as st

st.title("Find your next national park")

wishes = st.text_area("What do you love outdoors?", "quiet forests, waterfalls and wildlife")
max_crowd = st.slider("Maximum crowd level", 1, 5, 5)

if st.button("Show recommendations"):
    picks = semantic_search(wishes, max_crowd=max_crowd)
    for row in picks.itertuples():
        st.subheader(f"{row.name}, {row.state}")
        st.caption(f"Best season: {row.best_season} | Crowd level: {row.crowd_level}/5")
        st.write(row.description)
    with st.spinner("Writing explanations..."):
        st.markdown(explain_picks(wishes, picks))

How to measure if it works

A recommender is only good if people like its suggestions. Common ways to measure that include precision at k (how many of the top k picks the user actually saved or visited), diversity (are the picks all the same kind of park?), and novelty (does it suggest parks beyond the famous ones?). Also plan for the cold start problem: new users have no ratings, so start with content-based and semantic search, and blend in collaborative filtering as ratings arrive.

Ideas to take it further

Once the basics work, you can add live weather and park alerts from the NPS API, distance from the user's home city, accessibility information, trip length, or photo-based search where users upload a picture of a landscape they love. Each new signal is one more feature your hybrid score can use.

Conclusion

We started with twelve short descriptions and ended with an AI-powered system that understands what travelers mean, learns from other visitors, and explains its choices in plain language. The same pattern works for hotels, hiking trails, books or restaurants. The best part of a park recommender is its purpose: helping people discover quiet, wonderful places they would never have found on their own.

Try the code, swap in real data from the NPS API, and share which park your recommender suggested for you.