diff --git a/SKILL.md b/SKILL.md
index 699ffc7..7782750 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -12,7 +12,7 @@ description: >
 
 ## What Is DocumentDB?
 
-DocumentDB is the engine powering [Azure DocumentDB](https://learn.microsoft.com/en-us/azure/documentdb/). It is a
+DocumentDB is the engine powering [Azure DocumentDB](https://learn.microsoft.com/azure/documentdb/). It is a
 **fully open-source** (MIT license), document-oriented NoSQL database engine built
 natively on PostgreSQL. It exposes a MongoDB-compatible API while storing BSON documents
 inside a PostgreSQL framework.
@@ -88,7 +88,57 @@ mongosh localhost:10260 \
   --tlsAllowInvalidCertificates
 ```
 
-### Option B — Prebuilt Docker Image (PostgreSQL/psql access only)
+### Option B — Docker Compose (Recommended for Sample Projects)
+
+The cleanest way to run DocumentDB alongside your app in a sample. Create a
+`docker-compose.yml` at the root of your project:
+
+```yaml
+version: "3.8"
+
+services:
+  documentdb:
+    image: ghcr.io/microsoft/documentdb/documentdb-local:latest
+    ports:
+      - "10260:10260"
+    environment:
+      - USERNAME=docdbuser
+      - PASSWORD=Admin100!
+    restart: unless-stopped
+
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    env_file:
+      - .env
+    depends_on:
+      - documentdb
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+```
+
+Start everything together:
+
+```bash
+docker compose up -d
+```
+
+Stop and remove containers:
+
+```bash
+docker compose down
+```
+
+If your sample is app-only (DocumentDB runs separately), include just the `documentdb`
+service and omit the `app` service. Your connection string should then point to
+`host.docker.internal:10260` from inside other containers, or `localhost:10260` from
+the host machine.
+
+---
+
+### Option C — Prebuilt Docker Image (PostgreSQL/psql access only)
 
 ```bash
 # Pull image (Ubuntu 22.04, PostgreSQL 16, AMD64, version 0.103.0)
@@ -117,42 +167,55 @@ External psql connection:
 psql -h localhost --port 9712 -d postgres -U documentdb
 ```
 
-### Option C — Build from Source (Ubuntu/Debian)
+### Option D — Build from Source (Ubuntu/Debian)
 
-```bash
-# 1. Clone
-git clone https://github.com/microsoft/documentdb.git
-cd documentdb
+If you want to build and run DocumentDB from source (instead of using Docker), follow these steps. This guide is designed for beginners and works best on Ubuntu/Debian. For other operating systems, package names may differ.
+
+**Prerequisites**
 
-# 2. Build Docker dev image
-docker build -f .devcontainer/Dockerfile -t documentdb .
+*Recommended:* use the provided devcontainer for VSCode which contains all the dependencies pre-installed.
 
-# 3. Run container (mounts local repo inside)
-docker run -v $(pwd):/home/documentdb/code -it documentdb /bin/bash
-cd code
+Or install the required dependencies manually:
 
-# 4. Build and install PostgreSQL extensions
-make
+```bash
+sudo apt update
+sudo apt install build-essential libbson-dev postgresql-server-dev-all pkg-config rustc cargo
+```
+
+**Step 1: Build PostgreSQL Extensions**
+
+```bash
 sudo make install
+```
+
+**Step 2: Build the Gateway**
+
+```bash
+scripts/build_and_install_with_pgrx.sh -i -d pg_documentdb_gw_host/
+```
+
+**Step 3: Start PostgreSQL and the Gateway**
 
-# 5. Start PostgreSQL + Gateway together
+```bash
 scripts/start_oss_server.sh -c -g
 ```
 
-Connect via MongoDB client:
+**Step 4: Connect and Test**
+
+Using a MongoDB client:
 
 ```bash
 mongosh --host localhost --port 10260 --tls --tlsAllowInvalidCertificates \
-  -u docdb_user -p Admin100
+  -u docdbuser -p Admin100!
 ```
 
-Connect via psql:
+Using the PostgreSQL shell:
 
 ```bash
 psql -p 9712 -d postgres
 ```
 
-### Option D — Build Custom Debian/Ubuntu Packages
+### Option E — Build Custom Debian/Ubuntu Packages
 
 ```bash
 # Build packages for Debian 12, PostgreSQL 16
@@ -560,6 +623,46 @@ users.update_one({'name': 'Alice'}, {'$set': {'age': 31}})
 users.delete_one({'name': 'Alice'})
 ```
 
+### Python `get_client()` — safe pattern for samples
+
+Always read the connection URI from an environment variable and exit with a clear
+message if it is missing. Only enable `tlsAllowInvalidCertificates` when an explicit
+env flag is set — do not default it to `True`, as that encourages insecure defaults
+if the code is reused against a real deployment.
+
+The connection string itself must always include `tls=true` and
+`tlsAllowInvalidCertificates=true` (for the local container) as query parameters so
+the intent is visible and auditable at the call site.
+
+```python
+import os
+import sys
+from pymongo import MongoClient
+
+
+def get_client() -> MongoClient:
+    uri = os.getenv("DOCUMENTDB_URI")
+    if not uri:
+        sys.exit(
+            "Error: DOCUMENTDB_URI environment variable is not set.\n"
+            "Copy .env.example to .env and fill in your connection string."
+        )
+    # tlsAllowInvalidCertificates is only safe for the local dev container.
+    # Never enable this against a real deployment — use a valid certificate instead.
+    allow_invalid_certs = os.getenv("DOCUMENTDB_ALLOW_INVALID_CERTS", "false").lower() == "true"
+    return MongoClient(uri, tlsAllowInvalidCertificates=allow_invalid_certs)
+```
+
+`.env.example` for the local container (sets the flag explicitly):
+
+```
+DOCUMENTDB_URI=mongodb://<username>:<password>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256
+DOCUMENTDB_ALLOW_INVALID_CERTS=true
+```
+
+For a real deployment, omit `DOCUMENTDB_ALLOW_INVALID_CERTS` (it defaults to `false`)
+and use a connection string without `tlsAllowInvalidCertificates=true`.
+
 ### Connecting via psql (Direct SQL)
 
 ```bash
@@ -595,7 +698,7 @@ SELECT * FROM documentdb_api.create_indexes_background(
       "name": "idx_vector",
       "cosmosSearchOptions": {
         "kind": "vector-ivf",
-        "numLists": 100,
+        "numLists": 1,
         "similarity": "COS",
         "dimensions": 1536
       }
@@ -607,6 +710,87 @@ SELECT * FROM documentdb_api.create_indexes_background(
 LangChain and Semantic Kernel both support MongoDB-compatible vector stores and work
 with DocumentDB through the Gateway without code changes.
 
+### Similarity metrics — `COS`, `L2`, `IP`
+
+Set via the `similarity` field in `cosmosSearchOptions`. Choose based on how your
+embedding model was trained:
+
+| Metric | Value | When to use |
+|---|---|---|
+| Cosine similarity | `COS` | Default choice for most text and multimodal embeddings. Measures the angle between vectors, ignoring magnitude. Use when vectors may not be normalised. |
+| Euclidean distance | `L2` | Use when absolute distance in vector space matters — e.g. image embeddings or models explicitly trained with L2 loss. |
+| Inner product | `IP` | Use only when vectors are already unit-normalised (magnitude = 1). Equivalent to cosine in that case but faster. Incorrect results if vectors are not normalised. |
+
+When in doubt, use `COS`. Most popular embedding models (`nomic-embed-text`,
+`text-embedding-ada-002`, `mxbai-embed-large`) are trained for cosine similarity.
+
+### `numLists` tuning for `vector-ivf`
+
+`numLists` controls how many inverted index partitions IVF builds. The rule of thumb
+is `sqrt(n)` where `n` is the number of documents in the collection.
+
+| Dataset size | Recommended `numLists` |
+|---|---|
+| < 100 documents | `1` |
+| ~1 000 documents | `32` |
+| ~10 000 documents | `100` |
+| ~100 000 documents | `316` |
+| ~1 000 000 documents | `1000` |
+
+Setting `numLists` too high relative to the dataset size **degrades recall** — the
+query probes too few documents per list and misses neighbours. Setting it too low
+reduces the benefit of the index. For development and small samples, always start
+with `numLists: 1`.
+
+### Querying the vector index — `$search` aggregation (MongoDB driver)
+
+Use the `$search` aggregation stage with `cosmosSearch` to run a vector similarity query.
+`returnStoredSource: true` is **required** — without it the stage does not return the
+source document fields, only internal metadata.
+
+```javascript
+const pipeline = [
+  {
+    $search: {
+      cosmosSearch: {
+        vector: queryEmbedding,   // number[] matching the index dimensions
+        path: 'embedding',        // field that holds the stored vector
+        k: 5,                     // number of nearest neighbours to return
+      },
+      returnStoredSource: true,   // REQUIRED — returns the full source document
+    },
+  },
+  // Split into two stages — see projection gotcha below
+  { $addFields: { similarityScore: { $meta: 'searchScore' } } },
+  { $project: { embedding: 0 } },
+];
+
+const results = await collection.aggregate(pipeline).toArray();
+```
+
+### Projection gotcha — never mix inclusion and exclusion in one `$project`
+
+DocumentDB does **not** allow a single `$project` stage to contain both an inclusion
+(e.g. adding a computed field) and an exclusion (e.g. `embedding: 0`).
+
+**This will throw** `Cannot do exclusion on field embedding in inclusion projection`:
+
+```javascript
+// ❌ WRONG — mixes inclusion ({ $meta: ... }) and exclusion (0) in one stage
+{ $project: { similarityScore: { $meta: 'searchScore' }, embedding: 0 } }
+```
+
+**Fix — use two separate stages:**
+
+```javascript
+// ✅ CORRECT
+{ $addFields: { similarityScore: { $meta: 'searchScore' } } },  // add the score
+{ $project: { embedding: 0 } },                                  // then exclude
+```
+
+This pattern applies any time you need both a computed/meta field and an excluded field
+in the same aggregation result.
+
 ---
 
 ## 11. Full-Text Search
@@ -692,10 +876,12 @@ WHERE document @@ '{"$text": {"$search": "retrieval augmented generation"}}';
 - **Discord:** https://aka.ms/documentdb_discord
 - **Docs:** https://documentdb.io/docs
 - **Roadmap:** https://github.com/orgs/microsoft/projects/1407/views/1
+- **File Issues:** https://github.com/documentdb/documentdb/issues?q=is%3Aissue%20state%3Aopen%20label%3Adocumentdb-local
 - **FerretDB integration:** https://github.com/FerretDB/FerretDB (uses DocumentDB as backend)
 - **License:** MIT — https://opensource.org/license/mit
 - **Contributing:** See `CONTRIBUTING.md` in the repo
 
+
 ---
 
 ## Appendix: Troubleshooting
diff --git a/clinical-note-similarity-py/.env.example b/clinical-note-similarity-py/.env.example
new file mode 100644
index 0000000..d02edf7
--- /dev/null
+++ b/clinical-note-similarity-py/.env.example
@@ -0,0 +1,8 @@
+DOCUMENTDB_URI=mongodb://<username>:<password>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256
+DOCUMENTDB_DATABASE=clinicaldb
+DOCUMENTDB_COLLECTION=notes
+OLLAMA_BASE_URL=http://127.0.0.1:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+FLASK_PORT=5001
+NEAREST_NEIGHBORS=5
+EMBEDDING_DIMENSIONS=768
diff --git a/clinical-note-similarity-py/.gitignore b/clinical-note-similarity-py/.gitignore
new file mode 100644
index 0000000..d119d9e
--- /dev/null
+++ b/clinical-note-similarity-py/.gitignore
@@ -0,0 +1,9 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
diff --git a/clinical-note-similarity-py/README.md b/clinical-note-similarity-py/README.md
new file mode 100644
index 0000000..9dcac02
--- /dev/null
+++ b/clinical-note-similarity-py/README.md
@@ -0,0 +1,211 @@
+# Clinical Note Similarity Explorer — Python
+
+> **Important:** All clinical notes in this sample are fictional and de-identified. This tool is for demonstration purposes only and is not intended for use with real patient data.
+
+A Flask web application that stores de-identified clinical notes as documents with vector embeddings in **DocumentDB OSS**. Clinicians and researchers can search for similar cases using natural language descriptions — finding notes by clinical meaning rather than exact keyword matches. Built entirely on open-source tools with no cloud accounts required.
+
+## Use cases
+
+- Search by symptoms: *"patient with acute chest pain radiating to the left arm with ST elevation"*
+- Search by presentation: *"shortness of breath not responding to bronchodilators with wheeze"*
+- Search by findings: *"sudden onset facial droop, arm weakness, and slurred speech"*
+- Research patterns: *"abdominal pain with right lower quadrant tenderness and fever"*
+
+## How it works
+
+```
+Clinician Query (natural language)
+         │
+         ▼
+  Embed with nomic-embed-text (768-dim)
+         │
+         ▼
+  DocumentDB $search ──── cosine similarity ────► Similar Cases
+  (vector-ivf index)      by clinical meaning      ranked by score
+         │
+    optional $match
+    (specialty filter)
+```
+
+At ingest time, each note's chief complaint and clinical text are concatenated and embedded into a 768-dimensional vector using `nomic-embed-text`. At search time, the clinician's query is embedded with the same model and DocumentDB returns the most semantically similar cases — even when different clinical terminology is used.
+
+## Open-source stack
+
+| Component | Tool |
+|---|---|
+| Embedding model | [Ollama](https://ollama.com) `nomic-embed-text` (768 dimensions, runs locally) |
+| Vector database | [DocumentDB OSS](https://github.com/microsoft/documentdb) via Docker |
+| MongoDB driver | [PyMongo](https://pymongo.readthedocs.io/) |
+| Web framework | [Flask](https://flask.palletsprojects.com/) |
+| Language | Python 3.10+ |
+
+## Prerequisites
+
+- **Python 3.10+** — [python.org](https://python.org)
+- **Docker Desktop** — [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
+- **Ollama** — [ollama.com/download](https://ollama.com/download)
+
+After installing Ollama, pull the embedding model:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+## Setup
+
+### 1. Start DocumentDB OSS
+
+**macOS / Linux / Git Bash:**
+```bash
+docker run -dt \
+  -p 10260:10260 \
+  -e USERNAME=docdbuser \
+  -e PASSWORD=Admin100! \
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+```
+
+**Windows PowerShell:**
+```powershell
+docker run -dt `
+  -p 10260:10260 `
+  -e USERNAME=docdbuser `
+  -e PASSWORD=Admin100! `
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+```
+
+### 2. Install dependencies
+
+```bash
+cd clinical-note-similarity-py
+pip install -r requirements.txt
+```
+
+### 3. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your DocumentDB credentials:
+
+| Variable | Default | Description |
+|---|---|---|
+| `DOCUMENTDB_URI` | — | Full MongoDB connection string |
+| `DOCUMENTDB_DATABASE` | `clinicaldb` | Database name |
+| `DOCUMENTDB_COLLECTION` | `notes` | Collection name |
+| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama server URL |
+| `OLLAMA_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model |
+| `FLASK_PORT` | `5001` | Port for the Flask web app |
+| `NEAREST_NEIGHBORS` | `5` | Default number of results |
+| `EMBEDDING_DIMENSIONS` | `768` | Must match the embedding model |
+
+### 4. Upload clinical notes
+
+Embeds all 20 sample notes and stores them in DocumentDB with a vector index:
+
+```bash
+python upload_notes.py
+```
+
+Expected output:
+```
+Loaded 20 clinical notes
+
+Cleared existing collection
+
+Generating embeddings and uploading...
+  [ 1/20] [Cardiology           ] Acute ST-Elevation Myocardial Infarction...
+  [ 2/20] [Cardiology           ] Unstable Angina...
+  ...
+  [20/20] [Gastroenterology     ] Crohn's Disease Flare...
+
+Inserted 20 note documents
+Vector index created (vector-ivf, dimensions: 768, similarity: COS)
+```
+
+### 5. Start the web app
+
+```bash
+python app.py
+```
+
+Open your browser at `http://localhost:5001`.
+
+## Sample queries to try
+
+| Query | Expected specialty |
+|---|---|
+| `Sudden severe chest pain with ST elevation, diaphoresis, left arm radiation` | Cardiology |
+| `Wheezing, dyspnea not responding to albuterol inhaler` | Pulmonology |
+| `Sudden onset facial droop, arm weakness, and speech difficulty` | Neurology |
+| `Abdominal pain migrating to right lower quadrant with fever` | Gastroenterology |
+| `Knee pop after pivoting with immediate swelling and instability` | Orthopedics |
+| `Fatigue, weight gain, cold intolerance, hair thinning, and constipation` | Endocrinology |
+| `Spreading skin redness with warmth and fever after minor skin break` | Dermatology |
+
+## Document schema
+
+Each clinical note document stored in DocumentDB:
+
+| Field | Type | Description |
+|---|---|---|
+| `note_id` | string | Unique identifier (e.g. `CN001`) |
+| `specialty` | string | Medical specialty |
+| `diagnosis` | string | Primary diagnosis |
+| `age_group` | string | `18-35`, `36-50`, `51-65`, `65+` |
+| `sex` | string | `M` or `F` |
+| `chief_complaint` | string | Presenting complaint in one sentence |
+| `clinical_note` | string | De-identified clinical summary (3-5 sentences) |
+| `icd_code` | string | ICD-10 diagnosis code |
+| `outcome` | string | `admitted`, `discharged`, `referred`, `follow-up` |
+| `embedding` | array | 768-dimensional vector (excluded from search results) |
+
+## Specialties covered
+
+The sample dataset includes 20 notes across 7 specialties:
+
+| Specialty | Notes | Diagnoses |
+|---|---|---|
+| Cardiology | 4 | STEMI, Unstable Angina, Atrial Fibrillation, Heart Failure |
+| Pulmonology | 3 | Pneumonia, Asthma Exacerbation, COPD Exacerbation |
+| Neurology | 3 | Migraine, Ischemic Stroke, Seizure |
+| Gastroenterology | 3 | Appendicitis, GERD, Crohn's Disease |
+| Orthopedics | 3 | Distal Radius Fracture, Lumbar Disc Herniation, ACL Tear |
+| Endocrinology | 2 | Type 2 Diabetes, Hashimoto's Thyroiditis |
+| Dermatology | 2 | Cellulitis, Plaque Psoriasis |
+
+## Project structure
+
+```
+clinical-note-similarity-py/
+├── data/
+│   └── clinical_notes.json        # 20 fictional de-identified clinical notes
+├── utils/
+│   ├── __init__.py
+│   ├── db.py                      # MongoDB client factory
+│   └── embeddings.py              # Ollama embedding helper
+├── templates/
+│   ├── index.html                 # Search page
+│   └── note.html                  # Full note detail page
+├── static/
+│   └── style.css                  # Styles
+├── upload_notes.py                # Seeds DocumentDB with embeddings + vector index
+├── cleanup.py                     # Drops the notes collection
+├── app.py                         # Flask web application
+├── requirements.txt
+├── .env.example                   # Template — copy to .env
+├── .gitignore
+└── README.md
+```
+
+## Cleanup
+
+Drop the notes collection when you are done:
+
+```bash
+python cleanup.py
+```
+
+## Disclaimer
+
+This sample uses entirely fictional, de-identified clinical notes generated for demonstration purposes. It is not a medical device, clinical decision support system, or suitable for use with real patient data. Always consult qualified healthcare professionals for medical decisions.
diff --git a/clinical-note-similarity-py/app.py b/clinical-note-similarity-py/app.py
new file mode 100644
index 0000000..ad92a9b
--- /dev/null
+++ b/clinical-note-similarity-py/app.py
@@ -0,0 +1,118 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from flask import Flask, render_template, request
+from utils.db import get_client, get_collection
+from utils.embeddings import get_embedding
+
+app = Flask(__name__)
+
+_client = None
+_col = None
+
+
+def get_col():
+    global _client, _col
+    if _col is None:
+        _client = get_client()
+        _col = get_collection(_client)
+    return _col
+
+
+@app.teardown_appcontext
+def close_mongo_client(exception):
+    global _client, _col
+    if _client is not None:
+        _client.close()
+        _client = None
+        _col = None
+
+
+def similarity_search(query: str, specialty: str, num_results: int) -> list:
+    col = get_col()
+    k = num_results if specialty == "all" else num_results * 4
+
+    embedding = get_embedding(query)
+
+    pipeline = [
+        {
+            "$search": {
+                "cosmosSearch": {
+                    "vector": embedding,
+                    "path": "embedding",
+                    "k": k,
+                },
+                "returnStoredSource": True,
+            }
+        },
+        {
+            "$addFields": {"similarityScore": {"$meta": "searchScore"}}
+        },
+        {
+            "$project": {"embedding": 0}
+        },
+    ]
+
+    if specialty and specialty != "all":
+        pipeline.append({"$match": {"specialty": specialty}})
+
+    pipeline.append({"$limit": num_results})
+
+    return list(col.aggregate(pipeline))
+
+
+def get_specialties() -> list:
+    col = get_col()
+    return sorted(col.distinct("specialty"))
+
+
+@app.route("/")
+def index():
+    specialties = get_specialties()
+    return render_template("index.html", specialties=specialties)
+
+
+@app.route("/search", methods=["POST"])
+def search():
+    query = request.form.get("query", "").strip()
+    specialty = request.form.get("specialty", "all")
+    num_results = int(request.form.get("num_results", 5))
+    specialties = get_specialties()
+
+    results = []
+    error = None
+
+    if query:
+        try:
+            results = similarity_search(query, specialty, num_results)
+        except Exception as e:
+            app.logger.exception("Error during similarity search")
+            error = "An unexpected error occurred while processing your request. Please try again later."
+
+    return render_template(
+        "index.html",
+        query=query,
+        results=results,
+        specialty=specialty,
+        num_results=num_results,
+        specialties=specialties,
+        error=error,
+    )
+
+
+@app.route("/note/<note_id>")
+def note_detail(note_id):
+    col = get_col()
+    doc = col.find_one({"note_id": note_id}, {"embedding": 0})
+    if not doc:
+        return "Note not found", 404
+    return render_template("note.html", note=doc)
+
+
+if __name__ == "__main__":
+    port = int(os.getenv("FLASK_PORT", 5001))
+    print(f"Starting Clinical Note Similarity Explorer on http://localhost:{port}")
+    app.run(debug=True, port=port)
diff --git a/clinical-note-similarity-py/cleanup.py b/clinical-note-similarity-py/cleanup.py
new file mode 100644
index 0000000..0411e16
--- /dev/null
+++ b/clinical-note-similarity-py/cleanup.py
@@ -0,0 +1,17 @@
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from utils.db import get_client, get_collection
+
+
+def main():
+    client = get_client()
+    col = get_collection(client)
+    col.drop()
+    print(f"Dropped collection: {col.full_name}")
+    client.close()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/clinical-note-similarity-py/data/clinical_notes.json b/clinical-note-similarity-py/data/clinical_notes.json
new file mode 100644
index 0000000..d17c2bc
--- /dev/null
+++ b/clinical-note-similarity-py/data/clinical_notes.json
@@ -0,0 +1,222 @@
+[
+  {
+    "note_id": "CN001",
+    "specialty": "Cardiology",
+    "diagnosis": "Acute ST-Elevation Myocardial Infarction",
+    "age_group": "51-65",
+    "sex": "M",
+    "chief_complaint": "Sudden onset severe chest pain radiating to left arm and jaw for 2 hours",
+    "clinical_note": "Patient presents with acute onset substernal chest pressure rated 9/10, radiating to the left arm and jaw, associated with diaphoresis and shortness of breath. ECG demonstrates ST elevations in leads II, III, and aVF consistent with an inferior STEMI. Troponin I markedly elevated at 12.4 ng/mL on initial draw. Patient was emergently taken to cardiac catheterization laboratory where a 100% occlusion of the right coronary artery was identified and successfully treated with primary PCI and drug-eluting stent placement. Patient transferred to cardiac ICU for post-procedural monitoring with plans for dual antiplatelet therapy.",
+    "icd_code": "I21.0",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN002",
+    "specialty": "Cardiology",
+    "diagnosis": "Unstable Angina",
+    "age_group": "51-65",
+    "sex": "F",
+    "chief_complaint": "Recurring chest tightness at rest lasting 10-15 minutes over past 3 days",
+    "clinical_note": "Patient reports worsening episodes of chest tightness occurring at rest over the past three days, each lasting 10-15 minutes with associated dyspnea and mild nausea. Risk factors include hypertension, hyperlipidemia, and a 20 pack-year smoking history. Initial troponin levels are within normal limits but ECG shows transient ST depression in leads V4-V6 during symptomatic episodes. Patient was admitted for continuous cardiac monitoring, started on aspirin and heparin infusion, and cardiology consult obtained for urgent coronary angiography.",
+    "icd_code": "I20.0",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN003",
+    "specialty": "Cardiology",
+    "diagnosis": "Atrial Fibrillation with Rapid Ventricular Response",
+    "age_group": "65+",
+    "sex": "M",
+    "chief_complaint": "Palpitations, shortness of breath, and lightheadedness for 6 hours",
+    "clinical_note": "Patient presents with 6 hours of palpitations described as rapid and irregular, accompanied by exertional dyspnea and lightheadedness. ECG confirms atrial fibrillation with a ventricular rate of 138 bpm. Echocardiogram shows mildly reduced left ventricular ejection fraction at 45%. Patient was given IV metoprolol for rate control achieving adequate rate reduction to 85 bpm. Anticoagulation initiated with apixaban after ruling out intracranial hemorrhage. Patient discharged with cardiology follow-up and recommendation for elective cardioversion.",
+    "icd_code": "I48.0",
+    "outcome": "discharged"
+  },
+  {
+    "note_id": "CN004",
+    "specialty": "Cardiology",
+    "diagnosis": "Congestive Heart Failure with Reduced Ejection Fraction",
+    "age_group": "65+",
+    "sex": "F",
+    "chief_complaint": "Progressive shortness of breath, bilateral leg swelling, and orthopnea for one week",
+    "clinical_note": "Patient presents with one week of progressive exertional dyspnea now present at rest, two-pillow orthopnea, and bilateral lower extremity pitting edema up to the knees. BNP markedly elevated at 1850 pg/mL. Chest X-ray demonstrates cardiomegaly with bilateral pleural effusions and pulmonary vascular congestion. Echocardiogram confirms severely reduced ejection fraction of 25% with global hypokinesis. Patient admitted for IV diuresis, fluid and sodium restriction, and optimization of heart failure medications including ACE inhibitor and beta blocker.",
+    "icd_code": "I50.2",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN005",
+    "specialty": "Pulmonology",
+    "diagnosis": "Community-Acquired Pneumonia",
+    "age_group": "36-50",
+    "sex": "M",
+    "chief_complaint": "Productive cough with yellow sputum, fever to 39.2°C, and right-sided chest pain for 4 days",
+    "clinical_note": "Patient presents with four days of productive cough with purulent yellow sputum, fever to 39.2°C, and pleuritic right-sided chest pain worsening with inspiration. Oxygen saturation 93% on room air. Chest X-ray demonstrates a right lower lobe consolidation consistent with lobar pneumonia. CBC shows leukocytosis at 14,500 with left shift. Sputum culture and blood cultures obtained prior to antibiotic initiation. Patient started on IV ceftriaxone and azithromycin and admitted for monitoring given oxygen requirement.",
+    "icd_code": "J18.9",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN006",
+    "specialty": "Pulmonology",
+    "diagnosis": "Acute Asthma Exacerbation",
+    "age_group": "18-35",
+    "sex": "F",
+    "chief_complaint": "Worsening shortness of breath, wheezing, and chest tightness despite home inhaler use",
+    "clinical_note": "Patient presents with acute worsening of shortness of breath and audible wheezing over the past 12 hours, not responding to multiple doses of home albuterol inhaler. Known history of moderate persistent asthma triggered by seasonal allergens. Respiratory rate 28/min, accessory muscle use noted on exam, and diffuse expiratory wheezes bilaterally. Peak flow 42% of predicted. Patient treated with continuous albuterol nebulization, ipratropium, systemic corticosteroids, and supplemental oxygen with significant improvement in symptoms and peak flow to 78% of predicted within 4 hours. Discharged with steroid taper and controller medication review.",
+    "icd_code": "J45.31",
+    "outcome": "discharged"
+  },
+  {
+    "note_id": "CN007",
+    "specialty": "Pulmonology",
+    "diagnosis": "COPD Exacerbation",
+    "age_group": "65+",
+    "sex": "M",
+    "chief_complaint": "Worsening shortness of breath, increased sputum production, and sputum color change for 5 days",
+    "clinical_note": "Patient with known severe COPD (FEV1 38% predicted) presents with 5-day history of increased dyspnea, sputum production increasing from baseline, and sputum color change from clear to green. Oxygen saturation 88% on home 2L nasal cannula, down from usual 93%. Chest X-ray shows hyperinflation without acute infiltrate. ABG demonstrates hypercapnia with pH 7.32, pCO2 58 mmHg. Patient started on controlled supplemental oxygen targeting SpO2 88-92%, bronchodilators, systemic corticosteroids, and broad-spectrum antibiotics. Respiratory therapy and pulmonology consulted.",
+    "icd_code": "J44.1",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN008",
+    "specialty": "Neurology",
+    "diagnosis": "Migraine with Aura",
+    "age_group": "18-35",
+    "sex": "F",
+    "chief_complaint": "Severe unilateral throbbing headache preceded by visual disturbances for 3 hours",
+    "clinical_note": "Patient presents with a 3-hour history of severe left-sided throbbing headache rated 8/10, preceded by 20 minutes of visual aura described as flickering zigzag lines expanding across the right visual field. Associated symptoms include photophobia, phonophobia, and nausea without vomiting. Neurological examination is normal. No fever, neck stiffness, or papilledema. History of similar episodic headaches since adolescence consistent with prior migraine diagnoses. Patient given IV ketorolac, IV metoclopramide, and IV fluids with significant pain relief within 1 hour. Discharged with triptan prescription and neurology follow-up.",
+    "icd_code": "G43.1",
+    "outcome": "discharged"
+  },
+  {
+    "note_id": "CN009",
+    "specialty": "Neurology",
+    "diagnosis": "Acute Ischemic Stroke",
+    "age_group": "65+",
+    "sex": "M",
+    "chief_complaint": "Sudden onset right-sided facial droop, right arm weakness, and slurred speech",
+    "clinical_note": "Patient presents via EMS with sudden onset of right facial droop, right arm weakness, and dysarthria with last known well time 90 minutes prior to arrival. NIHSS score 12. Non-contrast CT head negative for hemorrhage. CT angiography demonstrates occlusion of the left middle cerebral artery M2 segment. Patient assessed as eligible for IV alteplase and thrombolysis initiated at 110 minutes from last known well. Interventional neurology team activated and patient underwent successful mechanical thrombectomy with TICI 2b reperfusion. Admitted to stroke unit for monitoring and rehabilitation assessment.",
+    "icd_code": "I63.5",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN010",
+    "specialty": "Neurology",
+    "diagnosis": "First Unprovoked Generalized Tonic-Clonic Seizure",
+    "age_group": "18-35",
+    "sex": "M",
+    "chief_complaint": "Witnessed generalized convulsion lasting approximately 2 minutes with post-ictal confusion",
+    "clinical_note": "Patient brought in by family after a witnessed generalized tonic-clonic seizure lasting approximately 2 minutes with post-ictal confusion lasting 30 minutes. Patient has no prior seizure history and denies recent sleep deprivation, alcohol withdrawal, or drug use. Blood glucose, electrolytes, and toxicology screen are within normal limits. MRI brain without contrast shows no structural abnormality. EEG ordered as outpatient demonstrates generalized epileptiform discharges. Neurology consulted and patient counseled regarding driving restrictions and safety precautions. Anti-epileptic therapy deferred pending outpatient EEG results.",
+    "icd_code": "G40.309",
+    "outcome": "referred"
+  },
+  {
+    "note_id": "CN011",
+    "specialty": "Gastroenterology",
+    "diagnosis": "Acute Appendicitis",
+    "age_group": "18-35",
+    "sex": "F",
+    "chief_complaint": "Periumbilical pain migrating to right lower quadrant over 18 hours with nausea and anorexia",
+    "clinical_note": "Patient presents with an 18-hour history of pain beginning periumbilically and migrating to the right lower quadrant, associated with nausea, loss of appetite, and low-grade fever to 38.1°C. Examination reveals point tenderness at McBurney's point with positive Rovsing's and psoas signs. WBC elevated at 13,200 with neutrophilia. CT abdomen/pelvis with contrast demonstrates a distended appendix measuring 10mm in diameter with periappendiceal fat stranding and no perforation. General surgery consulted and patient consented for laparoscopic appendectomy performed without complications.",
+    "icd_code": "K37",
+    "outcome": "admitted"
+  },
+  {
+    "note_id": "CN012",
+    "specialty": "Gastroenterology",
+    "diagnosis": "Gastroesophageal Reflux Disease with Esophagitis",
+    "age_group": "36-50",
+    "sex": "M",
+    "chief_complaint": "Chronic burning epigastric and chest pain worsening after meals and when lying down",
+    "clinical_note": "Patient presents with a 6-month history of burning substernal and epigastric pain occurring daily, worsening 30-60 minutes after meals and when recumbent, with associated regurgitation and hoarseness. Alarm symptoms including dysphagia, weight loss, and melena are absent. Upper endoscopy performed reveals Los Angeles Grade B erosive esophagitis with no Barrett's changes or hiatal hernia. Patient counseled extensively on lifestyle modifications including weight reduction, dietary changes, and elevating the head of the bed. Started on twice-daily proton pump inhibitor therapy with plan for 8-week repeat endoscopy.",
+    "icd_code": "K21.0",
+    "outcome": "follow-up"
+  },
+  {
+    "note_id": "CN013",
+    "specialty": "Orthopedics",
+    "diagnosis": "Displaced Distal Radius Fracture",
+    "age_group": "65+",
+    "sex": "F",
+    "chief_complaint": "Wrist pain and deformity after fall on outstretched hand",
+    "clinical_note": "Patient presents after a ground-level fall on an outstretched hand with immediate onset of right wrist pain, swelling, and visible deformity. Neurovascular examination of the hand is intact. X-rays demonstrate a displaced Colles-type distal radius fracture with dorsal angulation of 25 degrees and 4mm of radial shortening, without intra-articular extension. Patient underwent closed reduction under hematoma block with adequate reduction achieved and confirmed on post-reduction X-ray, and immobilized in a sugar-tong splint. Orthopedic surgery follow-up arranged in 5 days for wound check and definitive management decision between casting and surgical fixation.",
+    "icd_code": "S52.501A",
+    "outcome": "follow-up"
+  },
+  {
+    "note_id": "CN014",
+    "specialty": "Orthopedics",
+    "diagnosis": "Lumbar Disc Herniation with Radiculopathy",
+    "age_group": "36-50",
+    "sex": "M",
+    "chief_complaint": "Low back pain with radiation down the left leg to the foot, worsened by sitting",
+    "clinical_note": "Patient presents with a 3-week history of low back pain with sharp shooting pain radiating down the left leg in an L5 distribution to the dorsum of the foot, worsened by prolonged sitting, coughing, and Valsalva maneuver. Straight leg raise test positive on the left at 40 degrees. Neurological examination reveals mild left great toe extensor weakness and decreased sensation over the left lateral calf. MRI lumbar spine demonstrates a large left paracentral L4-L5 disc herniation with moderate left lateral recess stenosis and nerve root compression. Patient started on NSAIDs, muscle relaxants, and referred for physical therapy and pain management.",
+    "icd_code": "M51.16",
+    "outcome": "referred"
+  },
+  {
+    "note_id": "CN015",
+    "specialty": "Orthopedics",
+    "diagnosis": "Anterior Cruciate Ligament Tear",
+    "age_group": "18-35",
+    "sex": "M",
+    "chief_complaint": "Right knee pain and instability after sudden pivoting injury during soccer match",
+    "clinical_note": "Patient presents with acute right knee pain after a non-contact pivoting injury during a soccer match, reporting a felt pop at the time of injury followed by immediate pain and swelling. Examination reveals a moderate hemarthrosis and positive Lachman test with a soft endpoint, along with a positive pivot shift test. McMurray test mildly positive medially. MRI right knee confirms complete ACL tear with concomitant medial meniscus posterior horn tear and bone bruising of the lateral femoral condyle consistent with the mechanism of injury. Patient referred to orthopedic surgery for discussion of ACL reconstruction and meniscal repair.",
+    "icd_code": "M23.611",
+    "outcome": "referred"
+  },
+  {
+    "note_id": "CN016",
+    "specialty": "Endocrinology",
+    "diagnosis": "Type 2 Diabetes Mellitus with Poor Glycemic Control",
+    "age_group": "51-65",
+    "sex": "F",
+    "chief_complaint": "Increased thirst, frequent urination, fatigue, and blurred vision for several weeks",
+    "clinical_note": "Patient with known type 2 diabetes on metformin presents with worsening polyuria, polydipsia, fatigue, and blurred vision over several weeks. HbA1c markedly elevated at 11.2% compared to prior value of 7.8% six months ago. Fasting blood glucose 284 mg/dL. Review reveals poor medication adherence and significant dietary nonadherence over the past several months. Dilated fundus examination reveals early non-proliferative diabetic retinopathy. Urine microalbumin-to-creatinine ratio elevated at 85 mg/g. Metformin dose adjusted, long-acting insulin initiated, and patient referred to diabetes education program and dietitian.",
+    "icd_code": "E11.65",
+    "outcome": "follow-up"
+  },
+  {
+    "note_id": "CN017",
+    "specialty": "Endocrinology",
+    "diagnosis": "Hashimoto's Thyroiditis with Hypothyroidism",
+    "age_group": "36-50",
+    "sex": "F",
+    "chief_complaint": "Fatigue, weight gain, cold intolerance, constipation, and dry skin over 6 months",
+    "clinical_note": "Patient presents with a 6-month history of progressive fatigue, 8-pound weight gain despite unchanged diet, cold intolerance, constipation, and dry skin with diffuse hair thinning. Thyroid palpation reveals a mildly enlarged, firm, non-tender gland without discrete nodules. TSH markedly elevated at 24 mIU/L with low free T4 at 0.6 ng/dL. Anti-TPO antibodies markedly positive at 1240 IU/mL consistent with autoimmune thyroiditis. Thyroid ultrasound demonstrates heterogeneous echotexture with increased vascularity typical of Hashimoto's thyroiditis. Levothyroxine therapy initiated at 75 mcg daily with follow-up TSH in 6 weeks.",
+    "icd_code": "E06.3",
+    "outcome": "follow-up"
+  },
+  {
+    "note_id": "CN018",
+    "specialty": "Dermatology",
+    "diagnosis": "Cellulitis of the Lower Extremity",
+    "age_group": "51-65",
+    "sex": "M",
+    "chief_complaint": "Rapidly spreading redness, warmth, swelling, and pain of the right lower leg",
+    "clinical_note": "Patient presents with a 2-day history of worsening redness, warmth, swelling, and pain of the right lower leg following a minor abrasion from a gardening tool. Exam reveals a well-demarcated area of erythema measuring 12 x 8 cm over the right anterior shin with associated lymphangitic streaking extending proximally toward the knee. Temperature 38.4°C and WBC 11,800. No crepitus, fluctuance, or bullae to suggest necrotizing fasciitis or abscess formation. Blood cultures drawn. Patient started on IV cefazolin with dramatic improvement in erythema borders over 48 hours, transitioned to oral cephalexin and discharged with wound care instructions.",
+    "icd_code": "L03.115",
+    "outcome": "discharged"
+  },
+  {
+    "note_id": "CN019",
+    "specialty": "Dermatology",
+    "diagnosis": "Plaque Psoriasis",
+    "age_group": "36-50",
+    "sex": "M",
+    "chief_complaint": "Chronic itchy raised scaly plaques on elbows, knees, and scalp with recent flare",
+    "clinical_note": "Patient presents with a 10-year history of plaque psoriasis now experiencing a significant flare following a recent streptococcal upper respiratory infection. Examination reveals extensive erythematous, well-demarcated plaques with silver-white micaceous scale covering elbows, knees, lumbar region, and scalp, involving approximately 25% of body surface area. Auspitz sign positive. No evidence of nail pitting or psoriatic arthropathy. Prior treatments include topical corticosteroids with inadequate control. PASI score calculated at 16. Patient referred to dermatology for discussion of systemic therapy including biologics targeting IL-17 or IL-23 pathways.",
+    "icd_code": "L40.0",
+    "outcome": "referred"
+  },
+  {
+    "note_id": "CN020",
+    "specialty": "Gastroenterology",
+    "diagnosis": "Crohn's Disease Flare",
+    "age_group": "18-35",
+    "sex": "F",
+    "chief_complaint": "Crampy abdominal pain, bloody diarrhea 8-10 times per day, fatigue, and 10-pound weight loss",
+    "clinical_note": "Patient with known Crohn's disease on maintenance azathioprine presents with a 3-week flare of crampy lower abdominal pain, bloody diarrhea occurring 8-10 times daily, severe fatigue, and 10-pound weight loss. Exam reveals right lower quadrant tenderness without peritoneal signs. CRP elevated at 68 mg/L, ESR 82 mm/hr, albumin low at 2.8 g/dL, and hemoglobin 9.4 g/dL consistent with active disease and malnutrition. Fecal calprotectin markedly elevated at 2200 mcg/g. CT enterography demonstrates transmural thickening and hyperenhancement of the terminal ileum and proximal colon with mesenteric adenopathy. Patient admitted for IV corticosteroids, nutritional support, and expedited GI endoscopy.",
+    "icd_code": "K50.1",
+    "outcome": "admitted"
+  }
+]
diff --git a/clinical-note-similarity-py/requirements.txt b/clinical-note-similarity-py/requirements.txt
new file mode 100644
index 0000000..f87b147
--- /dev/null
+++ b/clinical-note-similarity-py/requirements.txt
@@ -0,0 +1,4 @@
+pymongo>=4.6.0
+python-dotenv>=1.0.0
+requests>=2.31.0
+flask>=3.0.0
diff --git a/clinical-note-similarity-py/static/style.css b/clinical-note-similarity-py/static/style.css
new file mode 100644
index 0000000..5ce63aa
--- /dev/null
+++ b/clinical-note-similarity-py/static/style.css
@@ -0,0 +1,315 @@
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: #f0f4f8;
+  color: #1a1a2e;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* ── Header ── */
+header {
+  background: linear-gradient(135deg, #1a5c7a 0%, #0d3d52 100%);
+  color: white;
+  padding: 2rem 1.5rem;
+}
+.header-inner { max-width: 900px; margin: 0 auto; }
+header h1 { font-size: 1.8rem; font-weight: 700; letter-spacing: -0.5px; }
+.subtitle { margin-top: 0.4rem; opacity: 0.85; font-size: 0.9rem; }
+
+/* ── Main ── */
+main {
+  flex: 1;
+  max-width: 900px;
+  margin: 0 auto;
+  width: 100%;
+  padding: 1.5rem;
+}
+
+/* ── Disclaimer ── */
+.disclaimer {
+  background: #fefce8;
+  border: 1px solid #fde68a;
+  color: #78350f;
+  border-radius: 8px;
+  padding: 0.75rem 1.1rem;
+  font-size: 0.85rem;
+  margin-bottom: 1.25rem;
+}
+
+/* ── Search form ── */
+.search-form {
+  background: white;
+  border-radius: 12px;
+  padding: 1.25rem 1.5rem;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+  margin-bottom: 1.5rem;
+}
+.query-row { margin-bottom: 0.85rem; }
+.query-input {
+  width: 100%;
+  padding: 0.75rem 1rem;
+  border: 2px solid #e0e7ef;
+  border-radius: 8px;
+  font-size: 0.95rem;
+  font-family: inherit;
+  resize: vertical;
+  outline: none;
+  transition: border-color 0.2s;
+  line-height: 1.5;
+}
+.query-input:focus { border-color: #1a5c7a; }
+
+.filter-row {
+  display: flex;
+  gap: 1.25rem;
+  align-items: center;
+  flex-wrap: wrap;
+  font-size: 0.9rem;
+  color: #555;
+}
+.filter-select {
+  margin-left: 0.4rem;
+  padding: 0.35rem 0.6rem;
+  border: 1px solid #cdd6e0;
+  border-radius: 6px;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+.search-btn {
+  padding: 0.6rem 1.4rem;
+  background: #1a5c7a;
+  color: white;
+  border: none;
+  border-radius: 8px;
+  font-size: 0.92rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s;
+  margin-left: auto;
+}
+.search-btn:hover { background: #144d68; }
+
+/* ── Results meta ── */
+.results-meta {
+  font-size: 0.88rem;
+  color: #666;
+  margin-bottom: 0.85rem;
+}
+
+/* ── Result card ── */
+.result-card {
+  background: white;
+  border-radius: 12px;
+  padding: 1.25rem 1.5rem;
+  margin-bottom: 1rem;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+  transition: box-shadow 0.2s;
+}
+.result-card:hover { box-shadow: 0 4px 16px rgba(0,0,0,0.11); }
+
+.card-header { margin-bottom: 0.5rem; }
+.card-title-row {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  margin-bottom: 0.35rem;
+}
+.note-id {
+  font-size: 0.78rem;
+  font-weight: 700;
+  color: #888;
+  font-family: monospace;
+}
+.diagnosis {
+  font-size: 1.05rem;
+  font-weight: 600;
+  color: #1a1a2e;
+  line-height: 1.35;
+}
+
+.card-meta {
+  font-size: 0.82rem;
+  color: #777;
+  margin: 0.4rem 0 0.65rem;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.15rem;
+}
+.dot { margin: 0 0.3rem; }
+
+.chief-complaint {
+  font-size: 0.88rem;
+  color: #555;
+  margin-bottom: 0.6rem;
+  line-height: 1.5;
+}
+
+.note-excerpt {
+  font-size: 0.88rem;
+  color: #444;
+  line-height: 1.6;
+  margin-bottom: 0.85rem;
+}
+
+.card-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+/* ── Specialty badges ── */
+.specialty-badge {
+  display: inline-block;
+  padding: 0.18rem 0.6rem;
+  border-radius: 20px;
+  font-size: 0.72rem;
+  font-weight: 600;
+  white-space: nowrap;
+}
+.specialty-cardiology        { background: #fee2e2; color: #991b1b; }
+.specialty-pulmonology       { background: #dbeafe; color: #1e40af; }
+.specialty-neurology         { background: #ede9fe; color: #5b21b6; }
+.specialty-gastroenterology  { background: #ffedd5; color: #9a3412; }
+.specialty-orthopedics       { background: #dcfce7; color: #166534; }
+.specialty-endocrinology     { background: #fef9c3; color: #854d0e; }
+.specialty-dermatology       { background: #fce7f3; color: #9d174d; }
+
+/* ── Outcome badges ── */
+.outcome {
+  display: inline-block;
+  padding: 0.15rem 0.55rem;
+  border-radius: 4px;
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+}
+.outcome-admitted    { background: #fee2e2; color: #991b1b; }
+.outcome-discharged  { background: #dcfce7; color: #166534; }
+.outcome-referred    { background: #dbeafe; color: #1e40af; }
+.outcome-follow-up   { background: #f3f4f6; color: #374151; }
+
+/* ── Similarity score bar ── */
+.score-row {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  font-size: 0.82rem;
+  flex: 1;
+  min-width: 180px;
+}
+.score-label { color: #888; white-space: nowrap; }
+.score-bar-bg {
+  flex: 1;
+  height: 6px;
+  background: #e8edf3;
+  border-radius: 3px;
+  overflow: hidden;
+}
+.score-bar {
+  height: 100%;
+  background: linear-gradient(90deg, #1a5c7a, #38bdf8);
+  border-radius: 3px;
+}
+.score-pct { color: #1a5c7a; font-weight: 600; white-space: nowrap; }
+
+.detail-link {
+  font-size: 0.85rem;
+  color: #1a5c7a;
+  text-decoration: none;
+  white-space: nowrap;
+  font-weight: 500;
+}
+.detail-link:hover { text-decoration: underline; }
+
+/* ── Error ── */
+.error-banner {
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  color: #991b1b;
+  border-radius: 8px;
+  padding: 0.85rem 1.2rem;
+  margin-bottom: 1rem;
+  font-size: 0.9rem;
+}
+
+/* ── Example queries ── */
+.example-queries {
+  background: white;
+  border-radius: 12px;
+  padding: 1.5rem;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+}
+.example-queries h3 {
+  font-size: 1rem;
+  color: #1a5c7a;
+  margin-bottom: 0.85rem;
+}
+.example-queries ul {
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.example-queries li {
+  font-size: 0.9rem;
+  color: #555;
+  padding: 0.5rem 0.75rem;
+  background: #f8fafc;
+  border-radius: 6px;
+  border-left: 3px solid #1a5c7a;
+}
+
+/* ── Note detail ── */
+.back-link {
+  display: inline-block;
+  color: #1a5c7a;
+  font-size: 0.9rem;
+  text-decoration: none;
+  margin-bottom: 1.25rem;
+}
+.back-link:hover { text-decoration: underline; }
+
+.note-detail {
+  background: white;
+  border-radius: 12px;
+  padding: 2rem;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+}
+.note-detail-header { margin-bottom: 1.5rem; }
+.note-detail-title-row {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 0.5rem;
+  flex-wrap: wrap;
+}
+.note-id-large { font-size: 0.85rem; font-weight: 700; color: #888; font-family: monospace; }
+.note-detail-header h2 { font-size: 1.5rem; margin: 0.4rem 0; line-height: 1.35; }
+.note-detail-meta { font-size: 0.85rem; color: #777; }
+
+.note-section { margin-bottom: 1.5rem; }
+.note-section h3 {
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: #1a5c7a;
+  margin-bottom: 0.5rem;
+}
+.note-section p { font-size: 0.95rem; color: #333; line-height: 1.65; }
+.note-full-text { font-size: 0.95rem; color: #333; line-height: 1.75; }
+
+/* ── Footer ── */
+footer {
+  text-align: center;
+  padding: 1.5rem;
+  font-size: 0.82rem;
+  color: #aaa;
+}
+footer a { color: #1a5c7a; text-decoration: none; }
+footer a:hover { text-decoration: underline; }
diff --git a/clinical-note-similarity-py/templates/index.html b/clinical-note-similarity-py/templates/index.html
new file mode 100644
index 0000000..927e686
--- /dev/null
+++ b/clinical-note-similarity-py/templates/index.html
@@ -0,0 +1,134 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Clinical Note Similarity Explorer</title>
+  <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}" />
+</head>
+<body>
+  <header>
+    <div class="header-inner">
+      <h1>Clinical Note Similarity Explorer</h1>
+      <p class="subtitle">Find similar cases using natural language — powered by DocumentDB vector search</p>
+    </div>
+  </header>
+
+  <main>
+    <div class="disclaimer">
+      <strong>Sample Data Only</strong> — All clinical notes are fictional and de-identified. This tool is for demonstration purposes only and is not intended for use with real patient data.
+    </div>
+
+    <section class="search-section">
+      <form method="POST" action="/search" class="search-form">
+        <div class="query-row">
+          <textarea
+            name="query"
+            class="query-input"
+            placeholder="e.g. patient with chest pain radiating to the left arm and ST elevation on ECG, diaphoresis and shortness of breath"
+            rows="3"
+          >{{ query or '' }}</textarea>
+        </div>
+        <div class="filter-row">
+          <label>
+            Specialty:
+            <select name="specialty" class="filter-select">
+              <option value="all" {% if (specialty or 'all') == 'all' %}selected{% endif %}>All Specialties</option>
+              {% for sp in specialties %}
+              <option value="{{ sp }}" {% if specialty == sp %}selected{% endif %}>{{ sp }}</option>
+              {% endfor %}
+            </select>
+          </label>
+          <label>
+            Results:
+            <select name="num_results" class="filter-select">
+              {% for n in [3, 5, 10] %}
+              <option value="{{ n }}" {% if (num_results or 5) == n %}selected{% endif %}>{{ n }}</option>
+              {% endfor %}
+            </select>
+          </label>
+          <button type="submit" class="search-btn">Find Similar Cases</button>
+        </div>
+      </form>
+    </section>
+
+    {% if error %}
+    <div class="error-banner">
+      <strong>Error:</strong> {{ error }}
+    </div>
+    {% endif %}
+
+    {% if query %}
+    <section class="results-section">
+      <p class="results-meta">
+        {% if results %}
+          <strong>{{ results | length }}</strong> similar case{% if results | length != 1 %}s{% endif %} found
+          {% if specialty and specialty != 'all' %}in <strong>{{ specialty }}</strong>{% endif %}
+          for <em>"{{ query[:80] }}{% if query | length > 80 %}…{% endif %}"</em>
+        {% else %}
+          No similar cases found. Try broadening your query or specialty filter.
+        {% endif %}
+      </p>
+
+      {% for note in results %}
+      <div class="result-card">
+        <div class="card-header">
+          <div class="card-title-row">
+            <span class="note-id">{{ note.note_id }}</span>
+            <span class="specialty-badge specialty-{{ note.specialty | lower | replace(' ', '-') }}">
+              {{ note.specialty }}
+            </span>
+          </div>
+          <div class="diagnosis">{{ note.diagnosis }}</div>
+        </div>
+
+        <div class="card-meta">
+          <span>Age group: <strong>{{ note.age_group }}</strong></span>
+          <span class="dot">·</span>
+          <span>Sex: <strong>{{ note.sex }}</strong></span>
+          <span class="dot">·</span>
+          <span>ICD: <strong>{{ note.icd_code }}</strong></span>
+          <span class="dot">·</span>
+          <span class="outcome outcome-{{ note.outcome }}">{{ note.outcome }}</span>
+        </div>
+
+        <p class="chief-complaint"><em>Chief complaint:</em> {{ note.chief_complaint }}</p>
+
+        <p class="note-excerpt">
+          {{ note.clinical_note[:260] }}{% if note.clinical_note | length > 260 %}…{% endif %}
+        </p>
+
+        <div class="card-footer">
+          <div class="score-row">
+            <span class="score-label">Similarity</span>
+            <div class="score-bar-bg">
+              <div class="score-bar" style="width: {{ (note.similarityScore * 100) | round(1) }}%"
+                   data-score="{{ note.similarityScore }}"></div>
+            </div>
+            <span class="score-pct">{{ (note.similarityScore * 100) | round(1) }}%</span>
+          </div>
+          <a href="/note/{{ note.note_id }}" class="detail-link">View full note →</a>
+        </div>
+      </div>
+      {% endfor %}
+    </section>
+    {% else %}
+    <div class="example-queries">
+      <h3>Example queries to try</h3>
+      <ul>
+        <li>Sudden chest pain radiating to the left arm with diaphoresis</li>
+        <li>Patient with wheezing, dyspnea not responding to bronchodilators</li>
+        <li>Sudden onset facial droop and arm weakness with speech difficulty</li>
+        <li>Abdominal pain migrating to right lower quadrant with fever and nausea</li>
+        <li>Fatigue, weight gain, cold intolerance and hair loss</li>
+        <li>Knee injury after pivoting with felt pop and subsequent swelling</li>
+      </ul>
+    </div>
+    {% endif %}
+  </main>
+
+  <footer>
+    <p>Built with <a href="https://github.com/microsoft/documentdb" target="_blank" rel="noopener noreferrer">DocumentDB OSS</a> · Embeddings by <a href="https://ollama.com" target="_blank" rel="noopener noreferrer">Ollama</a> · Sample data only — not for clinical use</p>
+  </footer>
+</body>
+</html>
diff --git a/clinical-note-similarity-py/templates/note.html b/clinical-note-similarity-py/templates/note.html
new file mode 100644
index 0000000..8ba65db
--- /dev/null
+++ b/clinical-note-similarity-py/templates/note.html
@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{{ note.note_id }} — {{ note.diagnosis }}</title>
+  <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}" />
+</head>
+<body>
+  <header>
+    <div class="header-inner">
+      <h1>Clinical Note Similarity Explorer</h1>
+      <p class="subtitle">Find similar cases using natural language</p>
+    </div>
+  </header>
+
+  <main>
+    <div class="disclaimer">
+      <strong>Sample Data Only</strong> — This note is fictional and de-identified. For demonstration purposes only.
+    </div>
+
+    <a href="/" class="back-link">← Back to search</a>
+
+    <div class="note-detail">
+      <div class="note-detail-header">
+        <div class="note-detail-title-row">
+          <span class="note-id-large">{{ note.note_id }}</span>
+          <span class="specialty-badge specialty-{{ note.specialty | lower | replace(' ', '-') }}">
+            {{ note.specialty }}
+          </span>
+          <span class="outcome outcome-{{ note.outcome }}">{{ note.outcome }}</span>
+        </div>
+        <h2>{{ note.diagnosis }}</h2>
+        <div class="note-detail-meta">
+          <span>Age group: <strong>{{ note.age_group }}</strong></span>
+          <span class="dot">·</span>
+          <span>Sex: <strong>{{ note.sex }}</strong></span>
+          <span class="dot">·</span>
+          <span>ICD-10: <strong>{{ note.icd_code }}</strong></span>
+        </div>
+      </div>
+
+      <div class="note-section">
+        <h3>Chief Complaint</h3>
+        <p>{{ note.chief_complaint }}</p>
+      </div>
+
+      <div class="note-section">
+        <h3>Clinical Note</h3>
+        <p class="note-full-text">{{ note.clinical_note }}</p>
+      </div>
+    </div>
+  </main>
+
+  <footer>
+    <p>Built with <a href="https://github.com/microsoft/documentdb" target="_blank" rel="noopener noreferrer">DocumentDB OSS</a> · Embeddings by <a href="https://ollama.com" target="_blank" rel="noopener noreferrer">Ollama</a> · Sample data only — not for clinical use</p>
+  </footer>
+</body>
+</html>
diff --git a/clinical-note-similarity-py/upload_notes.py b/clinical-note-similarity-py/upload_notes.py
new file mode 100644
index 0000000..3d57540
--- /dev/null
+++ b/clinical-note-similarity-py/upload_notes.py
@@ -0,0 +1,61 @@
+import json
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from utils.db import get_client, get_collection
+from utils.embeddings import get_embedding
+
+
+def build_embed_text(note: dict) -> str:
+    return f"{note['chief_complaint']} {note['clinical_note']}"
+
+
+def main():
+    data_path = Path(__file__).parent / "data" / "clinical_notes.json"
+    with open(data_path) as f:
+        notes = json.load(f)
+
+    print(f"Loaded {len(notes)} clinical notes\n")
+
+    client = get_client()
+    col = get_collection(client)
+    col.drop()
+    print("Cleared existing collection\n")
+
+    print("Generating embeddings and uploading...")
+    docs = []
+    for i, note in enumerate(notes, 1):
+        print(f"  [{i:2}/{len(notes)}] [{note['specialty']:<20}] {note['diagnosis'][:50]}...")
+        note["embedding"] = get_embedding(build_embed_text(note))
+        docs.append(note)
+
+    col.insert_many(docs)
+    print(f"\nInserted {len(docs)} note documents")
+
+    dimensions = int(os.getenv("EMBEDDING_DIMENSIONS", "768"))
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "clinicaldb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "notes")
+
+    client[db_name].command({
+        "createIndexes": col_name,
+        "indexes": [{
+            "key": {"embedding": "cosmosSearch"},
+            "name": "idx_vector_embedding",
+            "cosmosSearchOptions": {
+                "kind": "vector-ivf",
+                "numLists": 1,
+                "similarity": "COS",
+                "dimensions": dimensions,
+            },
+        }],
+    })
+    print(f"Vector index created (vector-ivf, dimensions: {dimensions}, similarity: COS)")
+    client.close()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/clinical-note-similarity-py/utils/__init__.py b/clinical-note-similarity-py/utils/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/clinical-note-similarity-py/utils/db.py b/clinical-note-similarity-py/utils/db.py
new file mode 100644
index 0000000..70ae847
--- /dev/null
+++ b/clinical-note-similarity-py/utils/db.py
@@ -0,0 +1,19 @@
+import os
+
+from pymongo import MongoClient
+
+
+def get_client() -> MongoClient:
+    uri = os.getenv("DOCUMENTDB_URI")
+    if not uri:
+        raise SystemExit("DOCUMENTDB_URI environment variable is not set; please configure it with your MongoDB/DocumentDB connection string.")
+    allow_invalid_certs = os.getenv("DOCUMENTDB_ALLOW_INVALID_CERTS", "").lower() in ("1", "true", "yes")
+    if allow_invalid_certs:
+        return MongoClient(uri, tlsAllowInvalidCertificates=True)
+    return MongoClient(uri)
+
+
+def get_collection(client: MongoClient):
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "clinicaldb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "notes")
+    return client[db_name][col_name]
diff --git a/clinical-note-similarity-py/utils/embeddings.py b/clinical-note-similarity-py/utils/embeddings.py
new file mode 100644
index 0000000..5968843
--- /dev/null
+++ b/clinical-note-similarity-py/utils/embeddings.py
@@ -0,0 +1,15 @@
+import os
+
+import requests
+
+
+def get_embedding(text: str) -> list:
+    base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
+    model = os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")
+    response = requests.post(
+        f"{base_url}/api/embeddings",
+        json={"model": model, "prompt": text},
+        timeout=60,
+    )
+    response.raise_for_status()
+    return response.json()["embedding"]
diff --git a/content-semantic-search-py/.env.example b/content-semantic-search-py/.env.example
new file mode 100644
index 0000000..7e055df
--- /dev/null
+++ b/content-semantic-search-py/.env.example
@@ -0,0 +1,8 @@
+DOCUMENTDB_URI=mongodb://<username>:<password>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256
+DOCUMENTDB_DATABASE=contentdb
+DOCUMENTDB_COLLECTION=articles
+OLLAMA_BASE_URL=http://127.0.0.1:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+FLASK_PORT=5000
+NEAREST_NEIGHBORS=5
+EMBEDDING_DIMENSIONS=768
diff --git a/content-semantic-search-py/.gitignore b/content-semantic-search-py/.gitignore
new file mode 100644
index 0000000..442c176
--- /dev/null
+++ b/content-semantic-search-py/.gitignore
@@ -0,0 +1,10 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+uploads/
diff --git a/content-semantic-search-py/README.md b/content-semantic-search-py/README.md
new file mode 100644
index 0000000..0af1032
--- /dev/null
+++ b/content-semantic-search-py/README.md
@@ -0,0 +1,188 @@
+# Content Semantic Search Portal — Python
+
+A Flask web portal that stores articles, blogs, and PDF documents as MongoDB documents with vector embeddings in **DocumentDB OSS**. Users search by meaning — not just keywords — and get back the most semantically relevant content ranked by cosine similarity. Built entirely on open-source tools with no cloud accounts required.
+
+## How it works
+
+```
+User Query (natural language)
+         │
+         ▼
+ Embed with nomic-embed-text (768-dim)
+         │
+         ▼
+  DocumentDB $search ──── cosine similarity ────► Ranked Results
+  (vector-ivf index)       by semantic meaning      with scores
+```
+
+At ingest time, each document's title and content are concatenated and embedded into a 768-dimensional vector using `nomic-embed-text` running locally in Ollama. That vector is stored alongside the document in DocumentDB.
+
+At search time, the user's query is embedded with the same model and DocumentDB's `$search` aggregation stage finds the most similar documents by cosine similarity — no keyword matching involved. This means a query for "neural networks and attention" will surface articles about transformers, BERT, and GPT even if those exact words don't appear in the article title.
+
+## Open-source stack
+
+| Component | Tool |
+|---|---|
+| Embedding model | [Ollama](https://ollama.com) `nomic-embed-text` (768 dimensions, runs locally) |
+| Vector database | [DocumentDB OSS](https://github.com/microsoft/documentdb) via Docker |
+| MongoDB driver | [PyMongo](https://pymongo.readthedocs.io/) |
+| Web framework | [Flask](https://flask.palletsprojects.com/) |
+| PDF extraction | [pypdf](https://pypi.org/project/pypdf/) |
+| Language | Python 3.10+ |
+
+## Prerequisites
+
+- **Python 3.10+** — [python.org](https://python.org)
+- **Docker Desktop** — [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
+- **Ollama** — [ollama.com/download](https://ollama.com/download)
+
+After installing Ollama, pull the embedding model:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+## Setup
+
+### 1. Start DocumentDB OSS
+
+**macOS / Linux / Git Bash:**
+```bash
+docker run -dt \
+  -p 10260:10260 \
+  -e USERNAME=docdbuser \
+  -e PASSWORD=Admin100! \
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+```
+
+**Windows PowerShell:**
+```powershell
+docker run -dt `
+  -p 10260:10260 `
+  -e USERNAME=docdbuser `
+  -e PASSWORD=Admin100! `
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+```
+
+### 2. Install dependencies
+
+```bash
+cd content-semantic-search-py
+pip install -r requirements.txt
+```
+
+### 3. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your DocumentDB credentials:
+
+| Variable | Default | Description |
+|---|---|---|
+| `DOCUMENTDB_URI` | — | Full MongoDB connection string |
+| `DOCUMENTDB_DATABASE` | `contentdb` | Database name |
+| `DOCUMENTDB_COLLECTION` | `articles` | Collection name |
+| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama server URL |
+| `OLLAMA_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model |
+| `FLASK_PORT` | `5000` | Port for the Flask web app |
+| `NEAREST_NEIGHBORS` | `5` | Default number of results |
+| `EMBEDDING_DIMENSIONS` | `768` | Must match the embedding model |
+
+### 4. Ingest sample articles
+
+Embeds all 15 sample articles and stores them in DocumentDB with a vector index:
+
+```bash
+python ingest.py
+```
+
+Expected output:
+```
+Loaded 15 sample articles
+
+Cleared existing collection
+
+Generating embeddings and uploading...
+  [ 1/15] Understanding Transformer Architecture in Modern NLP...
+  [ 2/15] Rising Sea Levels: Coastal Cities at Risk by 2050...
+  ...
+  [15/15] Generative AI in Creative Industries: Tools, Disruption...
+
+Inserted 15 documents
+Vector index created (vector-ivf, dimensions: 768, similarity: COS)
+```
+
+### 5. Start the web portal
+
+```bash
+python app.py
+```
+
+Open your browser at `http://localhost:5000`.
+
+## Ingesting custom content
+
+### Plain text file
+```bash
+python ingest.py --file my_post.txt --title "My Blog Post" --type blog --tags "AI,writing"
+```
+
+### PDF document
+```bash
+python ingest.py --file research_paper.pdf --title "Research Paper Title" --type research --tags "science,research"
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--file` | Path to a `.txt` or `.pdf` file |
+| `--title` | Title for the document (required with `--file`) |
+| `--type` | `article`, `blog`, or `research` (default: `article`) |
+| `--tags` | Comma-separated tags |
+
+## Sample queries to try
+
+| Query | What it should surface |
+|---|---|
+| `neural networks and self-attention` | Transformer architecture article |
+| `coastal flooding and climate adaptation` | Sea level rise article |
+| `gene therapy for inherited diseases` | CRISPR/genomics article |
+| `tracking people in public spaces` | Smart cities / surveillance blog |
+| `eating habits that reduce heart disease` | Mediterranean diet research |
+| `dark matter and early universe` | James Webb Telescope article |
+
+## Project structure
+
+```
+content-semantic-search-py/
+├── data/
+│   └── articles.json              # 15 sample articles on varied topics
+├── utils/
+│   ├── __init__.py
+│   ├── db.py                      # MongoDB client factory
+│   └── embeddings.py              # Ollama embedding helper
+├── templates/
+│   ├── index.html                 # Search page
+│   └── article.html               # Article detail page
+├── static/
+│   └── style.css                  # Styles
+├── ingest.py                      # Loads sample data or custom files
+├── app.py                         # Flask web application
+├── requirements.txt
+├── .env.example                   # Template — copy to .env
+├── .gitignore
+└── README.md
+```
+
+## Changing the embedding model
+
+Update both `OLLAMA_EMBEDDING_MODEL` and `EMBEDDING_DIMENSIONS` in `.env`, then re-run `python ingest.py` to rebuild all embeddings:
+
+| Model | Dimensions |
+|---|---|
+| `nomic-embed-text` | 768 |
+| `mxbai-embed-large` | 1024 |
+| `all-minilm` | 384 |
diff --git a/content-semantic-search-py/app.py b/content-semantic-search-py/app.py
new file mode 100644
index 0000000..018598d
--- /dev/null
+++ b/content-semantic-search-py/app.py
@@ -0,0 +1,127 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from flask import Flask, render_template, request
+from utils.db import get_client, get_collection
+from utils.embeddings import get_embedding
+import logging
+
+app = Flask(__name__)
+
+DEFAULT_NUM_RESULTS = 5
+
+_client = None
+_col = None
+
+
+@app.teardown_appcontext
+def close_mongo_client(exception=None):
+    global _client, _col
+    if _client is not None:
+        _client.close()
+        _client = None
+        _col = None
+
+
+def get_col():
+    global _client, _col
+    if _col is None:
+        _client = get_client()
+        _col = get_collection(_client)
+    return _col
+
+
+def semantic_search(query: str, content_type: str, num_results: int) -> list:
+    col = get_col()
+    k = num_results if content_type == "all" else num_results * 3
+
+    embedding = get_embedding(query)
+
+    pipeline = [
+        {
+            "$search": {
+                "cosmosSearch": {
+                    "vector": embedding,
+                    "path": "embedding",
+                    "k": k,
+                },
+                "returnStoredSource": True,
+            }
+        },
+        {
+            "$addFields": {"similarityScore": {"$meta": "searchScore"}}
+        },
+        {
+            "$project": {"embedding": 0}
+        },
+    ]
+
+    if content_type and content_type != "all":
+        pipeline.append({"$match": {"type": content_type}})
+
+    pipeline.append({"$limit": num_results})
+
+    return list(col.aggregate(pipeline))
+
+
+def get_content_types() -> list:
+    col = get_col()
+    return sorted(col.distinct("type"))
+
+
+@app.route("/")
+def index():
+    content_types = get_content_types()
+    return render_template("index.html", content_types=content_types)
+
+
+@app.route("/search", methods=["POST"])
+def search():
+    query = request.form.get("query", "").strip()
+    content_type = request.form.get("content_type", "all")
+    raw_num_results = request.form.get("num_results", "")
+    try:
+        num_results = int(raw_num_results)
+        if num_results <= 0:
+            num_results = DEFAULT_NUM_RESULTS
+    except (TypeError, ValueError):
+        num_results = DEFAULT_NUM_RESULTS
+    content_types = get_content_types()
+
+    results = []
+    error = None
+
+    if query:
+        try:
+            results = semantic_search(query, content_type, num_results)
+        except Exception as e:
+            logging.exception("Error during semantic search for query %r", query)
+            error = "An error occurred while processing your search. Please try again later."
+
+    return render_template(
+        "index.html",
+        query=query,
+        results=results,
+        content_type=content_type,
+        num_results=num_results,
+        content_types=content_types,
+        error=error,
+    )
+
+
+@app.route("/article/<article_id>")
+def article_detail(article_id):
+    col = get_col()
+    doc = col.find_one({"article_id": article_id}, {"embedding": 0})
+    if not doc:
+        return "Article not found", 404
+    return render_template("article.html", article=doc)
+
+
+if __name__ == "__main__":
+    port = int(os.getenv("FLASK_PORT", 5000))
+    print(f"Starting Content Semantic Search Portal on http://localhost:{port}")
+    app.run(debug=True, port=port)
diff --git a/content-semantic-search-py/data/articles.json b/content-semantic-search-py/data/articles.json
new file mode 100644
index 0000000..28313d1
--- /dev/null
+++ b/content-semantic-search-py/data/articles.json
@@ -0,0 +1,137 @@
+[
+  {
+    "article_id": "ART001",
+    "title": "Understanding Transformer Architecture in Modern NLP",
+    "content": "The transformer architecture, introduced in the landmark 'Attention Is All You Need' paper, revolutionized natural language processing by replacing recurrent networks with self-attention mechanisms. Unlike RNNs that process tokens sequentially, transformers process entire sequences in parallel, enabling massive parallelization during training. The multi-head attention mechanism allows the model to jointly attend to information from different representation subspaces, capturing both local and global dependencies in text. Today, transformer-based models like BERT, GPT, and T5 form the backbone of virtually every state-of-the-art NLP system.",
+    "type": "article",
+    "tags": ["machine learning", "NLP", "transformers", "deep learning", "AI"],
+    "author": "Dr. Sarah Chen",
+    "date": "2024-03-15"
+  },
+  {
+    "article_id": "ART002",
+    "title": "Rising Sea Levels: Coastal Cities at Risk by 2050",
+    "content": "Climate scientists project that global mean sea levels could rise between 0.3 and 1.0 meters by 2100 under moderate emissions scenarios, threatening hundreds of millions of people living in low-lying coastal regions. Cities like Miami, Jakarta, and Mumbai face the most acute risks, with some areas projected to experience permanent inundation within decades. The combination of thermal expansion of ocean water and accelerating ice sheet melt in Greenland and Antarctica is driving these projections. Adaptive infrastructure investment, managed retreat strategies, and aggressive emissions reduction are all being evaluated as potential responses.",
+    "type": "article",
+    "tags": ["climate change", "sea level rise", "coastal cities", "environment", "adaptation"],
+    "author": "Prof. James Okafor",
+    "date": "2024-01-22"
+  },
+  {
+    "article_id": "ART003",
+    "title": "Quantum Computing: When Will It Beat Classical Machines?",
+    "content": "Quantum computers leverage quantum mechanical phenomena — superposition and entanglement — to perform certain computations exponentially faster than classical computers. While Google's Sycamore processor claimed quantum supremacy in 2019 on a narrow benchmark, practical quantum advantage for real-world problems like drug discovery or cryptography remains elusive. Current NISQ-era devices suffer from high error rates, short coherence times, and limited qubit connectivity. Most researchers believe fault-tolerant quantum computing capable of beating classical machines on commercially relevant problems is still 10-15 years away.",
+    "type": "article",
+    "tags": ["quantum computing", "qubits", "quantum supremacy", "technology", "physics"],
+    "author": "Dr. Elena Vasquez",
+    "date": "2024-02-08"
+  },
+  {
+    "article_id": "ART004",
+    "title": "The Mediterranean Diet and Cardiovascular Health: What the Evidence Shows",
+    "content": "Decades of epidemiological research and randomized controlled trials have consistently linked adherence to a Mediterranean diet with significantly reduced risk of cardiovascular disease, stroke, and all-cause mortality. The diet, rich in olive oil, fish, legumes, whole grains, and fresh vegetables, appears to reduce LDL cholesterol and systemic inflammation through multiple mechanisms. The landmark PREDIMED trial demonstrated a 30% reduction in major cardiovascular events among high-risk adults following a Mediterranean diet supplemented with extra-virgin olive oil or mixed nuts. Researchers attribute much of the benefit to polyphenols, omega-3 fatty acids, and fiber working synergistically.",
+    "type": "research",
+    "tags": ["nutrition", "cardiovascular health", "Mediterranean diet", "clinical research", "wellness"],
+    "author": "Dr. Amara Diallo",
+    "date": "2023-11-14"
+  },
+  {
+    "article_id": "ART005",
+    "title": "15-Minute Cities: Rethinking Urban Design Around Human Scale",
+    "content": "The 15-minute city concept, popularized by urban planner Carlos Moreno and adopted in Paris and other European cities, proposes that every resident should be able to reach work, school, healthcare, groceries, and recreation within a 15-minute walk or bike ride from home. This framework challenges decades of car-centric suburban planning by prioritizing mixed-use zoning, active transportation infrastructure, and neighborhood-level amenities. Pilot implementations in Paris, Melbourne, and Portland show early evidence of reduced car trips and improved resident well-being. Critics argue the model is more achievable in dense European cities than in sprawling North American suburbs.",
+    "type": "article",
+    "tags": ["urban planning", "15-minute city", "sustainability", "transportation", "walkability"],
+    "author": "Maria Santos",
+    "date": "2024-04-03"
+  },
+  {
+    "article_id": "ART006",
+    "title": "Zero-Day Exploits: How Nation-State Hackers Find and Weaponize Vulnerabilities",
+    "content": "Zero-day vulnerabilities are software flaws unknown to the vendor, making them uniquely dangerous because no patch exists at the time of exploitation. Nation-state threat actors, particularly those affiliated with Russia, China, North Korea, and Iran, invest heavily in zero-day research and acquisition through gray-market brokers where a single critical vulnerability in enterprise software can sell for millions of dollars. The Stuxnet worm, which used four simultaneous zero-days to damage Iranian nuclear centrifuges, remains the canonical example of a weaponized zero-day campaign. Defenders increasingly rely on behavioral detection, memory-safe languages, and rapid patch cycles rather than signature-based tools to mitigate zero-day risk.",
+    "type": "article",
+    "tags": ["cybersecurity", "zero-day", "nation-state", "vulnerabilities", "threat intelligence"],
+    "author": "Alex Kim",
+    "date": "2024-03-30"
+  },
+  {
+    "article_id": "ART007",
+    "title": "The Lost City of Pompeii: New Excavations Reveal Everyday Roman Life",
+    "content": "Ongoing excavations in the Regio IX district of Pompeii continue to astonish archaeologists with their extraordinary preservation of first-century Roman daily life, frozen by the 79 AD eruption of Mount Vesuvius. Recent discoveries include a fast-food thermopolium with intact frescoes depicting the dishes served, a bakery with millstones still loaded with grain, and skeletal remains of slaves revealing evidence of hard physical labor through bone analysis. Advanced photogrammetry and ground-penetrating radar are allowing researchers to map unexcavated sections of the city before disturbing the soil. Each new excavation season rewrites what historians understand about Roman urban life, social hierarchies, and cuisine.",
+    "type": "article",
+    "tags": ["history", "archaeology", "Roman history", "Pompeii", "ancient civilization"],
+    "author": "Dr. Lucia Ferretti",
+    "date": "2023-09-18"
+  },
+  {
+    "article_id": "ART008",
+    "title": "Solar Power Economics: Why Utility-Scale Costs Have Dropped 90% in a Decade",
+    "content": "The levelized cost of utility-scale solar photovoltaic electricity has fallen from roughly $0.28 per kilowatt-hour in 2010 to under $0.03 in many markets by 2023, a decline driven by manufacturing scale, panel efficiency improvements, and competitive procurement. China's dominance in polysilicon and module manufacturing has created a global supply chain capable of producing terawatts of capacity annually at costs unimaginable a decade ago. Auctions in the Middle East, India, and Chile have repeatedly set record-low prices, with some contracts below $0.02/kWh. The remaining barriers to full solar deployment are now primarily grid integration, storage economics, and land use permitting rather than generation costs.",
+    "type": "research",
+    "tags": ["renewable energy", "solar power", "energy economics", "clean energy", "climate"],
+    "author": "Dr. Fatima Al-Rashid",
+    "date": "2024-01-05"
+  },
+  {
+    "article_id": "ART009",
+    "title": "Neuroplasticity: How the Adult Brain Continues to Change Throughout Life",
+    "content": "The long-held belief that the adult brain is fixed and immutable has been overturned by decades of neuroscience research demonstrating remarkable plasticity throughout the lifespan. Structural MRI studies show that learning new skills — from juggling to musical instruments to second languages — produces measurable increases in gray matter density in relevant cortical areas. Aerobic exercise promotes neurogenesis in the hippocampus, the brain region critical for memory consolidation, even in adults over 70. Cognitive rehabilitation after stroke leverages neuroplasticity by training surviving neural circuits to compensate for damaged regions. Understanding these mechanisms has profound implications for education, mental health treatment, and aging.",
+    "type": "research",
+    "tags": ["neuroscience", "neuroplasticity", "brain health", "learning", "cognitive science"],
+    "author": "Dr. Marcus Webb",
+    "date": "2023-12-02"
+  },
+  {
+    "article_id": "ART010",
+    "title": "The James Webb Space Telescope's First Year: What We've Learned",
+    "content": "After more than a decade of development and a nail-biting launch in December 2021, the James Webb Space Telescope has transformed observational astronomy in its first years of operation. Its infrared sensitivity allows it to peer through dust clouds opaque to Hubble, revealing stellar nurseries and the earliest galaxies that formed within 400 million years of the Big Bang. JWST has detected carbon dioxide in the atmosphere of exoplanet WASP-39b, demonstrating its power for atmospheric characterization of worlds beyond our solar system. Its observations of Uranus revealed unexpected ring structure detail, while its deep field images captured thousands of galaxies in a patch of sky smaller than a grain of sand held at arm's length.",
+    "type": "article",
+    "tags": ["space", "James Webb Telescope", "astronomy", "exoplanets", "cosmology"],
+    "author": "Dr. Priya Nair",
+    "date": "2024-02-20"
+  },
+  {
+    "article_id": "ART011",
+    "title": "The Loneliness Epidemic and Its Physical Health Consequences",
+    "content": "The US Surgeon General's 2023 advisory declared loneliness a public health epidemic, citing research showing that social isolation carries mortality risks equivalent to smoking 15 cigarettes per day. Loneliness activates the body's stress response system, elevating cortisol and inflammatory markers that over time damage cardiovascular, immune, and neurological systems. The rise of remote work, social media as a substitute for in-person connection, and the weakening of community institutions have all been cited as structural drivers of the epidemic. Researchers are now testing scalable interventions including volunteer programs, befriending services, and social prescribing in primary care settings.",
+    "type": "article",
+    "tags": ["mental health", "loneliness", "public health", "social connection", "wellbeing"],
+    "author": "Dr. Isabelle Moreau",
+    "date": "2024-04-11"
+  },
+  {
+    "article_id": "ART012",
+    "title": "Blockchain Beyond Cryptocurrency: Real-World Enterprise Applications",
+    "content": "While public blockchains like Bitcoin and Ethereum are synonymous with cryptocurrency speculation, permissioned blockchain networks are finding quiet but substantial adoption in supply chain provenance, healthcare data exchange, and trade finance. Walmart and IBM's Food Trust network uses blockchain to trace the provenance of food products from farm to shelf, reducing the time to trace a contamination source from days to seconds. The pharmaceutical industry uses blockchain-based serialization to combat counterfeit drug supply chains, with DSCSA compliance in the US driving adoption. In trade finance, digital letters of credit on blockchain platforms like Marco Polo and Contour have reduced settlement times from weeks to hours for participating banks.",
+    "type": "blog",
+    "tags": ["blockchain", "supply chain", "enterprise technology", "fintech", "distributed systems"],
+    "author": "Rajesh Patel",
+    "date": "2023-10-25"
+  },
+  {
+    "article_id": "ART013",
+    "title": "CRISPR Gene Editing: From Lab Curiosity to Approved Medicine",
+    "content": "A decade after Jennifer Doudna and Emmanuelle Charpentier's Nobel Prize-winning discovery of CRISPR-Cas9 as a programmable gene editing tool, the technology has moved from academic curiosity to approved medicine. In late 2023, the FDA approved the first CRISPR-based therapy — Casgevy — for sickle cell disease, offering a potential functional cure for patients who previously faced a lifetime of debilitating pain crises. Beyond inherited blood disorders, CRISPR is being investigated for solid tumors, HIV, high cholesterol, and inherited blindness. The main challenges ahead are delivery to target tissues, off-target editing risks, and equitable access given current manufacturing costs exceeding $2 million per patient.",
+    "type": "article",
+    "tags": ["genomics", "CRISPR", "gene editing", "medicine", "biotechnology"],
+    "author": "Dr. Hannah Brooks",
+    "date": "2024-03-05"
+  },
+  {
+    "article_id": "ART014",
+    "title": "Smart Cities and the Sensor Grid: Privacy vs. Efficiency Trade-offs",
+    "content": "Modern smart city deployments embed thousands of sensors — traffic cameras, air quality monitors, acoustic sensors, and pedestrian counters — into urban infrastructure to optimize traffic flow, reduce energy consumption, and improve emergency response times. Singapore, Amsterdam, and Columbus Ohio have implemented city-scale sensor platforms with measurable improvements in traffic congestion and energy use. However, civil liberties advocates warn that the same sensor infrastructure capable of counting pedestrians can also track individuals, creating pervasive surveillance infrastructure with limited democratic oversight. The line between smart city optimization and population surveillance is increasingly contested, particularly as facial recognition capabilities are integrated into existing camera networks.",
+    "type": "blog",
+    "tags": ["smart cities", "IoT", "privacy", "urban technology", "surveillance"],
+    "author": "Thomas Nguyen",
+    "date": "2023-08-14"
+  },
+  {
+    "article_id": "ART015",
+    "title": "Generative AI in Creative Industries: Tools, Disruption, and New Workflows",
+    "content": "Image generation models like Midjourney and DALL-E 3, music generation systems like Suno, and code generation tools like GitHub Copilot are reshaping creative and knowledge work workflows across industries. Professional illustrators, musicians, and developers report using these tools to accelerate early-stage ideation, prototype concepts, and handle repetitive production tasks — while using their own expertise to direct and refine outputs. The most significant labor market disruptions appear concentrated in entry-level creative roles: stock photography, basic illustration, and routine code generation. Copyright and attribution remain unresolved legal questions, with multiple class-action lawsuits challenging whether training on copyrighted material without permission constitutes infringement.",
+    "type": "blog",
+    "tags": ["generative AI", "creative industries", "AI art", "digital art", "future of work"],
+    "author": "Chloe Anderson",
+    "date": "2024-05-01"
+  }
+]
diff --git a/content-semantic-search-py/ingest.py b/content-semantic-search-py/ingest.py
new file mode 100644
index 0000000..d498fca
--- /dev/null
+++ b/content-semantic-search-py/ingest.py
@@ -0,0 +1,161 @@
+"""
+ingest.py — Load sample articles or custom files into DocumentDB with vector embeddings.
+
+Usage:
+  python ingest.py                                             # load all sample articles
+  python ingest.py --file my_post.txt --title "Title" --type blog
+  python ingest.py --file paper.pdf  --title "Title" --type research
+"""
+
+import argparse
+import json
+import os
+import uuid
+from datetime import date
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from utils.db import get_client, get_collection
+from utils.embeddings import get_embedding
+
+MAX_CONTENT_CHARS = 2000
+
+
+def extract_text_from_pdf(path: Path) -> str:
+    try:
+        from pypdf import PdfReader
+        reader = PdfReader(str(path))
+        parts = []
+        for page in reader.pages:
+            text = page.extract_text()
+            if text:
+                parts.append(text.strip())
+        return "\n".join(parts)
+    except ImportError:
+        raise SystemExit("pypdf is required for PDF ingestion: pip install pypdf")
+
+
+def extract_text_from_file(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix == ".pdf":
+        return extract_text_from_pdf(path)
+    return path.read_text(encoding="utf-8")
+
+
+def create_vector_index(client, db_name: str, col_name: str):
+    dimensions = int(os.getenv("EMBEDDING_DIMENSIONS", "768"))
+    client[db_name].command({
+        "createIndexes": col_name,
+        "indexes": [{
+            "key": {"embedding": "cosmosSearch"},
+            "name": "idx_vector_embedding",
+            "cosmosSearchOptions": {
+                "kind": "vector-ivf",
+                "numLists": 1,
+                "similarity": "COS",
+                "dimensions": dimensions,
+            },
+        }],
+    })
+    print(f"Vector index created (vector-ivf, dimensions: {dimensions}, similarity: COS)")
+
+
+def load_sample_articles(col, client):
+    data_path = Path(__file__).parent / "data" / "articles.json"
+    with open(data_path) as f:
+        articles = json.load(f)
+
+    print(f"Loaded {len(articles)} sample articles\n")
+    col.drop()
+    print("Cleared existing collection\n")
+
+    print("Generating embeddings and uploading...")
+    docs = []
+    for i, article in enumerate(articles, 1):
+        text = f"{article['title']} {article['content']}"
+        print(f"  [{i:2}/{len(articles)}] {article['title'][:60]}...")
+        article["embedding"] = get_embedding(text[:MAX_CONTENT_CHARS])
+        docs.append(article)
+
+    col.insert_many(docs)
+    print(f"\nInserted {len(docs)} documents")
+
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "contentdb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "articles")
+    create_vector_index(client, db_name, col_name)
+
+
+def ingest_file(col, client, file_path: str, title: str, content_type: str, tags: list):
+    path = Path(file_path)
+    if not path.exists():
+        raise SystemExit(f"File not found: {file_path}")
+
+    print(f"Extracting text from: {path.name}")
+    content = extract_text_from_file(path)
+    if len(content) > MAX_CONTENT_CHARS:
+        print(f"  Content truncated to {MAX_CONTENT_CHARS} chars for embedding")
+        embed_text = f"{title} {content[:MAX_CONTENT_CHARS]}"
+    else:
+        embed_text = f"{title} {content}"
+
+    print("Generating embedding...")
+    embedding = get_embedding(embed_text)
+
+    doc = {
+        "article_id": f"CUSTOM-{uuid.uuid4().hex[:8].upper()}",
+        "title": title,
+        "content": content[:5000],  # store up to 5000 chars
+        "type": content_type,
+        "tags": tags,
+        "author": "Uploaded",
+        "date": date.today().isoformat(),
+        "embedding": embedding,
+        "source_file": path.name,
+    }
+
+    col.insert_one(doc)
+    print(f"Inserted: {doc['article_id']} — {title}")
+
+    # Ensure vector index exists
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "contentdb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "articles")
+    try:
+        create_vector_index(client, db_name, col_name)
+    except Exception as exc:
+        # Ignore the expected "index already exists" case, surface others
+        message = str(exc).lower()
+        if "already exists" not in message:
+            raise
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Ingest content into DocumentDB")
+    parser.add_argument("--file", help="Path to a .txt or .pdf file to ingest")
+    parser.add_argument("--title", help="Title for the ingested document")
+    parser.add_argument("--type", default="article",
+                        choices=["article", "blog", "research"],
+                        help="Content type (default: article)")
+    parser.add_argument("--tags", default="",
+                        help="Comma-separated tags (e.g. 'AI,technology,research')")
+    args = parser.parse_args()
+
+    client = get_client()
+    col = get_collection(client)
+
+    if args.file:
+        if not args.title:
+            raise SystemExit("--title is required when ingesting a file")
+        tags = [t.strip() for t in args.tags.split(",") if t.strip()]
+        ingest_file(col, client, args.file, args.title, args.type, tags)
+    else:
+        load_sample_articles(col, client)
+
+    client.close()
+    print("\nDone.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/content-semantic-search-py/requirements.txt b/content-semantic-search-py/requirements.txt
new file mode 100644
index 0000000..d0816bc
--- /dev/null
+++ b/content-semantic-search-py/requirements.txt
@@ -0,0 +1,5 @@
+pymongo>=4.6.0
+python-dotenv>=1.0.0
+requests>=2.31.0
+flask>=3.0.0
+pypdf>=4.0.0
diff --git a/content-semantic-search-py/static/style.css b/content-semantic-search-py/static/style.css
new file mode 100644
index 0000000..724581c
--- /dev/null
+++ b/content-semantic-search-py/static/style.css
@@ -0,0 +1,241 @@
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: #f5f7fa;
+  color: #1a1a2e;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* ── Header ── */
+header {
+  background: linear-gradient(135deg, #1a6b8a 0%, #0d4a6b 100%);
+  color: white;
+  padding: 2rem 1.5rem;
+}
+.header-inner { max-width: 860px; margin: 0 auto; }
+header h1 { font-size: 1.9rem; font-weight: 700; letter-spacing: -0.5px; }
+.subtitle { margin-top: 0.4rem; opacity: 0.85; font-size: 0.95rem; }
+
+/* ── Main ── */
+main {
+  flex: 1;
+  max-width: 860px;
+  margin: 0 auto;
+  width: 100%;
+  padding: 2rem 1.5rem;
+}
+
+/* ── Search form ── */
+.search-section { margin-bottom: 1.5rem; }
+
+.search-form {
+  background: white;
+  border-radius: 12px;
+  padding: 1.25rem 1.5rem;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+}
+
+.search-row {
+  display: flex;
+  gap: 0.75rem;
+  margin-bottom: 0.85rem;
+}
+
+.search-input {
+  flex: 1;
+  padding: 0.7rem 1rem;
+  border: 2px solid #e0e7ef;
+  border-radius: 8px;
+  font-size: 0.97rem;
+  outline: none;
+  transition: border-color 0.2s;
+}
+.search-input:focus { border-color: #1a6b8a; }
+
+.search-btn {
+  padding: 0.7rem 1.6rem;
+  background: #1a6b8a;
+  color: white;
+  border: none;
+  border-radius: 8px;
+  font-size: 0.97rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s;
+  white-space: nowrap;
+}
+.search-btn:hover { background: #155a76; }
+
+.filter-row {
+  display: flex;
+  gap: 1.5rem;
+  align-items: center;
+  font-size: 0.9rem;
+  color: #555;
+}
+.filter-select {
+  margin-left: 0.4rem;
+  padding: 0.35rem 0.6rem;
+  border: 1px solid #cdd6e0;
+  border-radius: 6px;
+  font-size: 0.9rem;
+  outline: none;
+  cursor: pointer;
+}
+
+/* ── Results meta ── */
+.results-meta {
+  font-size: 0.9rem;
+  color: #666;
+  margin-bottom: 1rem;
+}
+
+/* ── Result card ── */
+.result-card {
+  background: white;
+  border-radius: 12px;
+  padding: 1.25rem 1.5rem;
+  margin-bottom: 1rem;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+  transition: box-shadow 0.2s;
+}
+.result-card:hover { box-shadow: 0 4px 16px rgba(0,0,0,0.12); }
+
+.card-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 0.4rem;
+}
+
+.card-title {
+  font-size: 1.05rem;
+  font-weight: 600;
+  color: #1a6b8a;
+  text-decoration: none;
+  line-height: 1.35;
+}
+.card-title:hover { text-decoration: underline; }
+
+.card-meta {
+  font-size: 0.82rem;
+  color: #888;
+  margin-bottom: 0.65rem;
+}
+.dot { margin: 0 0.35rem; }
+
+.card-excerpt {
+  font-size: 0.9rem;
+  color: #444;
+  line-height: 1.55;
+  margin-bottom: 0.75rem;
+}
+
+/* ── Type badges ── */
+.type-badge {
+  display: inline-block;
+  padding: 0.2rem 0.65rem;
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+.type-article  { background: #dbeafe; color: #1e40af; }
+.type-blog     { background: #dcfce7; color: #166534; }
+.type-research { background: #ede9fe; color: #5b21b6; }
+
+/* ── Tags ── */
+.tag-row { display: flex; flex-wrap: wrap; gap: 0.4rem; margin-bottom: 0.75rem; }
+.tag {
+  background: #f0f4f8;
+  color: #4a5568;
+  padding: 0.2rem 0.55rem;
+  border-radius: 4px;
+  font-size: 0.78rem;
+}
+
+/* ── Similarity score bar ── */
+.score-row {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  font-size: 0.82rem;
+}
+.score-label { color: #888; white-space: nowrap; }
+.score-bar-bg {
+  flex: 1;
+  height: 6px;
+  background: #e8edf3;
+  border-radius: 3px;
+  overflow: hidden;
+}
+.score-bar {
+  height: 100%;
+  background: linear-gradient(90deg, #1a6b8a, #2dd4bf);
+  border-radius: 3px;
+  transition: width 0.4s ease;
+}
+.score-pct { color: #1a6b8a; font-weight: 600; white-space: nowrap; }
+
+/* ── Error / empty states ── */
+.error-banner {
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  color: #991b1b;
+  border-radius: 8px;
+  padding: 0.85rem 1.2rem;
+  margin-bottom: 1rem;
+  font-size: 0.9rem;
+}
+.empty-state {
+  text-align: center;
+  padding: 3rem 1rem;
+  color: #888;
+  font-size: 0.95rem;
+}
+
+/* ── Article detail ── */
+.back-link {
+  display: inline-block;
+  color: #1a6b8a;
+  font-size: 0.9rem;
+  text-decoration: none;
+  margin-bottom: 1.25rem;
+}
+.back-link:hover { text-decoration: underline; }
+
+.article-detail {
+  background: white;
+  border-radius: 12px;
+  padding: 2rem;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+}
+.article-header { margin-bottom: 1.25rem; }
+.article-header h2 {
+  font-size: 1.5rem;
+  margin: 0.5rem 0 0.4rem;
+  line-height: 1.35;
+}
+.article-body {
+  font-size: 1rem;
+  line-height: 1.7;
+  color: #333;
+  margin-top: 1.25rem;
+}
+
+/* ── Footer ── */
+footer {
+  text-align: center;
+  padding: 1.5rem;
+  font-size: 0.82rem;
+  color: #aaa;
+}
+footer a { color: #1a6b8a; text-decoration: none; }
+footer a:hover { text-decoration: underline; }
diff --git a/content-semantic-search-py/templates/article.html b/content-semantic-search-py/templates/article.html
new file mode 100644
index 0000000..c6fb8b7
--- /dev/null
+++ b/content-semantic-search-py/templates/article.html
@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{{ article.title }}</title>
+  <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}" />
+</head>
+<body>
+  <header>
+    <div class="header-inner">
+      <h1>Content Semantic Search</h1>
+      <p class="subtitle">Search articles, blogs, and research by meaning</p>
+    </div>
+  </header>
+
+  <main>
+    <a href="/" class="back-link">← Back to search</a>
+
+    <article class="article-detail">
+      <div class="article-header">
+        <span class="type-badge type-{{ article.type }}">{{ article.type }}</span>
+        <h2>{{ article.title }}</h2>
+        <div class="card-meta">
+          <span>{{ article.author }}</span>
+          <span class="dot">·</span>
+          <span>{{ article.date }}</span>
+          <span class="dot">·</span>
+          <span>ID: {{ article.article_id }}</span>
+        </div>
+      </div>
+
+      {% if article.tags %}
+      <div class="tag-row">
+        {% for tag in article.tags %}
+        <span class="tag">{{ tag }}</span>
+        {% endfor %}
+      </div>
+      {% endif %}
+
+      <div class="article-body">
+        <p>{{ article.content }}</p>
+      </div>
+    </article>
+  </main>
+
+  <footer>
+    <p>Built with <a href="https://github.com/microsoft/documentdb" target="_blank" rel="noopener noreferrer">DocumentDB OSS</a> · Vector search powered by <a href="https://ollama.com" target="_blank" rel="noopener noreferrer">Ollama</a></p>
+  </footer>
+</body>
+</html>
diff --git a/content-semantic-search-py/templates/index.html b/content-semantic-search-py/templates/index.html
new file mode 100644
index 0000000..a2dd058
--- /dev/null
+++ b/content-semantic-search-py/templates/index.html
@@ -0,0 +1,123 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Content Semantic Search Portal</title>
+  <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}" />
+</head>
+<body>
+  <header>
+    <div class="header-inner">
+      <h1>Content Semantic Search</h1>
+      <p class="subtitle">Search articles, blogs, and research by meaning — powered by DocumentDB vector search</p>
+    </div>
+  </header>
+
+  <main>
+    <section class="search-section">
+      <form method="POST" action="/search" class="search-form">
+        <div class="search-row">
+          <input
+            type="text"
+            name="query"
+            class="search-input"
+            placeholder="e.g. neural networks and attention mechanisms"
+            value="{{ query or '' }}"
+            autofocus
+          />
+          <button type="submit" class="search-btn">Search</button>
+        </div>
+        <div class="filter-row">
+          <label>
+            Type:
+            <select name="content_type" class="filter-select">
+              <option value="all" {% if (content_type or 'all') == 'all' %}selected{% endif %}>All Types</option>
+              {% for ct in content_types %}
+              <option value="{{ ct }}" {% if content_type == ct %}selected{% endif %}>
+                {{ ct | capitalize }}
+              </option>
+              {% endfor %}
+            </select>
+          </label>
+          <label>
+            Results:
+            <select name="num_results" class="filter-select">
+              {% for n in [3, 5, 10] %}
+              <option value="{{ n }}" {% if (num_results or 5) == n %}selected{% endif %}>{{ n }}</option>
+              {% endfor %}
+            </select>
+          </label>
+        </div>
+      </form>
+    </section>
+
+    {% if error %}
+    <div class="error-banner">
+      <strong>Error:</strong> {{ error }}
+    </div>
+    {% endif %}
+
+    {% if query %}
+    <section class="results-section">
+      <p class="results-meta">
+        {% if results %}
+          Showing <strong>{{ results | length }}</strong> result{% if results | length != 1 %}s{% endif %} for
+          <em>"{{ query }}"</em>
+          {% if content_type and content_type != 'all' %}
+            in <strong>{{ content_type }}</strong>
+          {% endif %}
+        {% else %}
+          No results found for <em>"{{ query }}"</em>
+        {% endif %}
+      </p>
+
+      {% for article in results %}
+      <div class="result-card">
+        <div class="card-header">
+          <a href="/article/{{ article.article_id }}" class="card-title">{{ article.title }}</a>
+          <span class="type-badge type-{{ article.type }}">{{ article.type }}</span>
+        </div>
+
+        <div class="card-meta">
+          <span>{{ article.author }}</span>
+          <span class="dot">·</span>
+          <span>{{ article.date }}</span>
+        </div>
+
+        <p class="card-excerpt">
+          {{ article.content[:220] }}{% if article.content | length > 220 %}…{% endif %}
+        </p>
+
+        {% if article.tags %}
+        <div class="tag-row">
+          {% for tag in article.tags[:5] %}
+          <span class="tag">{{ tag }}</span>
+          {% endfor %}
+        </div>
+        {% endif %}
+
+        <div class="score-row">
+          <span class="score-label">Similarity</span>
+          <div class="score-bar-bg">
+            <div class="score-bar" style="width: {{ (article.similarityScore * 100) | round(1) }}%"></div>
+          </div>
+          <span class="score-pct">{{ (article.similarityScore * 100) | round(1) }}%</span>
+        </div>
+      </div>
+      {% endfor %}
+
+      {% if not results and not error %}
+      <div class="empty-state">
+        <p>No articles matched your query. Try different keywords or broaden the type filter.</p>
+      </div>
+      {% endif %}
+    </section>
+    {% endif %}
+  </main>
+
+  <footer>
+    <p>Built with <a href="https://github.com/microsoft/documentdb" target="_blank" rel="noopener noreferrer">DocumentDB OSS</a> · Vector search powered by <a href="https://ollama.com" target="_blank" rel="noopener noreferrer">Ollama</a></p>
+  </footer>
+</body>
+</html>
diff --git a/content-semantic-search-py/utils/__init__.py b/content-semantic-search-py/utils/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/content-semantic-search-py/utils/db.py b/content-semantic-search-py/utils/db.py
new file mode 100644
index 0000000..217978f
--- /dev/null
+++ b/content-semantic-search-py/utils/db.py
@@ -0,0 +1,22 @@
+import os
+
+from pymongo import MongoClient
+
+
+def get_client() -> MongoClient:
+    uri = os.getenv("DOCUMENTDB_URI")
+    if not uri:
+        raise SystemExit("DOCUMENTDB_URI environment variable is not set. Please configure it to connect to DocumentDB.")
+
+    allow_invalid_certs = os.getenv("DOCUMENTDB_ALLOW_INVALID_CERTS", "false").lower() in ("1", "true", "yes")
+
+    if allow_invalid_certs:
+        return MongoClient(uri, tlsAllowInvalidCertificates=True)
+
+    return MongoClient(uri)
+
+
+def get_collection(client: MongoClient):
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "contentdb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "articles")
+    return client[db_name][col_name]
diff --git a/content-semantic-search-py/utils/embeddings.py b/content-semantic-search-py/utils/embeddings.py
new file mode 100644
index 0000000..5968843
--- /dev/null
+++ b/content-semantic-search-py/utils/embeddings.py
@@ -0,0 +1,15 @@
+import os
+
+import requests
+
+
+def get_embedding(text: str) -> list:
+    base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
+    model = os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")
+    response = requests.post(
+        f"{base_url}/api/embeddings",
+        json={"model": model, "prompt": text},
+        timeout=60,
+    )
+    response.raise_for_status()
+    return response.json()["embedding"]
diff --git a/fraud-detection-agent-py/.env.example b/fraud-detection-agent-py/.env.example
new file mode 100644
index 0000000..b44816e
--- /dev/null
+++ b/fraud-detection-agent-py/.env.example
@@ -0,0 +1,8 @@
+DOCUMENTDB_URI=mongodb://<username>:<password>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256
+DOCUMENTDB_DATABASE=frauddb
+DOCUMENTDB_COLLECTION=transactions
+OLLAMA_BASE_URL=http://127.0.0.1:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+OLLAMA_LLM_MODEL=llama3.2
+NEAREST_NEIGHBORS=5
+EMBEDDING_DIMENSIONS=768
diff --git a/fraud-detection-agent-py/.gitignore b/fraud-detection-agent-py/.gitignore
new file mode 100644
index 0000000..d119d9e
--- /dev/null
+++ b/fraud-detection-agent-py/.gitignore
@@ -0,0 +1,9 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
diff --git a/fraud-detection-agent-py/README.md b/fraud-detection-agent-py/README.md
new file mode 100644
index 0000000..c6cf033
--- /dev/null
+++ b/fraud-detection-agent-py/README.md
@@ -0,0 +1,248 @@
+# Fraud Detection Multi-Agent System — Python
+
+An AI-powered fraud detection pipeline built entirely on open-source tools. It uses a **three-agent architecture** — Retrieval, Analysis, and Decision — backed by **DocumentDB OSS native vector search** and locally running **Ollama LLMs** to classify incoming transactions as `APPROVE`, `REVIEW`, or `BLOCK`. No cloud accounts or API keys required.
+
+## How it works
+
+```
+New Transaction
+      │
+      ▼
+┌─────────────────────────────────────────────┐
+│  Agent 1 — Retrieval                        │
+│                                             │
+│  1. Build semantic description of the tx    │
+│  2. Embed with nomic-embed-text via Ollama  │
+│  3. Vector search DocumentDB for top-k      │
+│     similar historical transactions         │
+└─────────────────┬───────────────────────────┘
+                  │ top-k similar txns (with fraud labels)
+                  ▼
+┌─────────────────────────────────────────────┐
+│  Agent 2 — Analysis                         │
+│                                             │
+│  llama3.2 identifies risk indicators,       │
+│  trust signals, and overall risk level      │
+│  (LOW / MEDIUM / HIGH)                      │
+└─────────────────┬───────────────────────────┘
+                  │ risk analysis JSON
+                  ▼
+┌─────────────────────────────────────────────┐
+│  Agent 3 — Decision                         │
+│                                             │
+│  llama3.2 outputs the final verdict:        │
+│  APPROVE / REVIEW / BLOCK                   │
+│  + confidence score + recommended action    │
+└─────────────────────────────────────────────┘
+```
+
+### Agent 1 — Retrieval
+
+The retrieval agent does not call an LLM. Instead it:
+
+1. Builds a semantic description from the transaction fields (description, merchant, category, amount, location).
+2. Embeds that description using `nomic-embed-text` running locally in Ollama.
+3. Runs a `$search` aggregation pipeline against DocumentDB using `cosmosSearch` vector similarity.
+4. Returns the top-k most similar historical transactions, each annotated with a `similarityScore`.
+
+The historical transactions include fraud labels, so the analysis agent can see which similar patterns were previously confirmed as fraud.
+
+### Agent 2 — Analysis
+
+The analysis agent calls `llama3.2` via Ollama's `/api/chat` endpoint. It receives:
+- The new transaction details
+- The top-k similar historical transactions with their fraud labels and similarity scores
+
+It outputs a structured JSON with `risk_indicators`, `trust_signals`, `risk_level`, and `reasoning`.
+
+### Agent 3 — Decision
+
+The decision agent calls `llama3.2` a second time with a focused prompt: given the transaction and the analysis, produce a final `APPROVE`, `REVIEW`, or `BLOCK` decision with a `confidence` score and a `recommended_action` for the operations team.
+
+## Open-source stack
+
+| Component | Tool |
+|---|---|
+| LLM (Analysis + Decision agents) | [Ollama](https://ollama.com) (`llama3.2`, runs locally) |
+| Embedding model | `nomic-embed-text` via Ollama (768 dimensions) |
+| Vector database | [DocumentDB OSS](https://github.com/microsoft/documentdb) via Docker |
+| MongoDB driver | [PyMongo](https://pymongo.readthedocs.io/) |
+| Language | Python 3.10+ |
+
+## Prerequisites
+
+Install the following before getting started:
+
+- **Python 3.10+** — [python.org](https://python.org)
+- **Docker Desktop** — [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
+- **Ollama** — [ollama.com/download](https://ollama.com/download)
+
+After installing Ollama, pull the required models:
+
+```bash
+ollama pull llama3.2          # used by Analysis and Decision agents
+ollama pull nomic-embed-text  # embedding model (768 dimensions)
+```
+
+## Setup
+
+### 1. Start DocumentDB OSS
+
+**macOS / Linux / Git Bash:**
+```bash
+docker run -dt \
+  -p 10260:10260 \
+  -e USERNAME=docdbuser \
+  -e PASSWORD=Admin100! \
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+```
+
+**Windows PowerShell:**
+```powershell
+docker run -dt `
+  -p 10260:10260 `
+  -e USERNAME=docdbuser `
+  -e PASSWORD=Admin100! `
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+```
+
+### 2. Install dependencies
+
+```bash
+cd fraud-detection-agent-py
+pip install -r requirements.txt
+```
+
+### 3. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your DocumentDB credentials:
+
+| Variable | Default | Description |
+|---|---|---|
+| `DOCUMENTDB_URI` | — | Full MongoDB connection string |
+| `DOCUMENTDB_DATABASE` | `frauddb` | Database name |
+| `DOCUMENTDB_COLLECTION` | `transactions` | Collection name |
+| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama server URL |
+| `OLLAMA_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model |
+| `OLLAMA_LLM_MODEL` | `llama3.2` | LLM for Analysis + Decision agents |
+| `NEAREST_NEIGHBORS` | `5` | Top-k transactions retrieved per query |
+| `EMBEDDING_DIMENSIONS` | `768` | Must match the embedding model output |
+
+> **Windows tip:** If Ollama refuses connections, use `http://127.0.0.1:11434` instead of `http://localhost:11434` to avoid IPv6 issues.
+
+### 4. Seed the database
+
+Generates embeddings for all 20 historical transactions and inserts them with a vector index:
+
+```bash
+python upload_data.py
+```
+
+Expected output:
+```
+Loaded 20 transactions
+
+Cleared existing collection
+
+Generating embeddings and uploading...
+  [ 1/20] [legit] Whole Foods Market: Regular weekly groceries purchased at local supermarket...
+  [ 2/20] [legit] Planet Fitness: Monthly gym membership auto-renewal charged to card on file...
+  ...
+  [20/20] [FRAUD] ATM International Withdrawal: ATM cash withdrawal in foreign country immed...
+
+Inserted 20 documents
+Vector index created (vector-ivf, dimensions: 768, similarity: COS)
+```
+
+### 5. Run the agent pipeline
+
+```bash
+python main.py
+```
+
+## Expected output
+
+```
+Fraud Detection Multi-Agent System
+Database : frauddb
+LLM Model: llama3.2
+Neighbors: 5
+
+======================================================================
+
+Transaction 1/5
+  Merchant : RetailMart Gift Cards
+  Amount   : $2400.00
+  Location : Online
+  Details  : Online purchase of high-value gift cards at multiple retailers within minutes...
+
+[ Agent 1: Retrieval ] Finding similar historical transactions...
+  Found 5 similar transactions (3 fraud, 2 legitimate)
+
+[ Agent 2: Analysis  ] Identifying risk patterns...
+  Risk Level : HIGH
+  Indicators : Multiple gift cards in rapid succession, online purchase, high amount
+  Trust      : None identified
+
+[ Agent 3: Decision  ] Making final verdict...
+
+  VERDICT : BLOCK (confidence: 92%)
+  Reason  : Multiple high-value gift card purchases in rapid succession is a strong indicator of gift card fraud.
+  Action  : Block transaction and flag account for security review.
+```
+
+## Changing the LLM
+
+Any model available in Ollama works. Pull the model and update `OLLAMA_LLM_MODEL` in `.env`:
+
+```bash
+ollama pull mistral      # strong general-purpose model
+ollama pull qwen2.5      # excellent reasoning
+ollama pull phi3.5       # lightweight and fast
+```
+
+## Changing the embedding model
+
+Update both `OLLAMA_EMBEDDING_MODEL` and `EMBEDDING_DIMENSIONS`, then re-run `python upload_data.py`:
+
+| Model | Dimensions |
+|---|---|
+| `nomic-embed-text` | 768 |
+| `mxbai-embed-large` | 1024 |
+| `all-minilm` | 384 |
+
+## Project structure
+
+```
+fraud-detection-agent-py/
+├── data/
+│   └── transactions.json         # 20 historical transactions (10 fraud, 10 legitimate)
+├── agents/
+│   ├── __init__.py
+│   ├── retrieval_agent.py        # Agent 1: vector search in DocumentDB
+│   ├── analysis_agent.py         # Agent 2: LLM pattern analysis
+│   └── decision_agent.py         # Agent 3: final APPROVE/REVIEW/BLOCK verdict
+├── utils/
+│   ├── __init__.py
+│   ├── db.py                     # MongoDB client factory
+│   └── embeddings.py             # Ollama embedding helper
+├── upload_data.py                # Seeds DocumentDB with embeddings + vector index
+├── cleanup.py                    # Drops the transactions collection
+├── main.py                       # Entry point: runs all 5 sample transactions
+├── requirements.txt
+├── .env.example                  # Template — copy to .env and fill in credentials
+├── .gitignore
+└── README.md
+```
+
+## Cleanup
+
+Drop the transactions collection when you are done:
+
+```bash
+python cleanup.py
+```
diff --git a/fraud-detection-agent-py/agents/__init__.py b/fraud-detection-agent-py/agents/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fraud-detection-agent-py/agents/analysis_agent.py b/fraud-detection-agent-py/agents/analysis_agent.py
new file mode 100644
index 0000000..625c619
--- /dev/null
+++ b/fraud-detection-agent-py/agents/analysis_agent.py
@@ -0,0 +1,86 @@
+import json
+import os
+
+import requests
+
+ANALYSIS_SYSTEM_PROMPT = """You are a fraud detection analyst. You will be given a new transaction and a set of similar historical transactions (some fraudulent, some legitimate).
+
+Analyze the new transaction and identify:
+1. Risk indicators — patterns that suggest fraud
+2. Trust signals — patterns that suggest legitimacy
+3. Overall risk level: LOW, MEDIUM, or HIGH
+
+Be concise. Focus on behavioral patterns, not just amounts.
+
+Respond ONLY with valid JSON in this exact format:
+{
+  "risk_indicators": ["list of red flags"],
+  "trust_signals": ["list of positive signals"],
+  "risk_level": "LOW",
+  "reasoning": "brief explanation"
+}"""
+
+
+class AnalysisAgent:
+    """Agent 2 — uses an LLM to identify fraud patterns from retrieved transactions."""
+
+    def __init__(self):
+        self.base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
+        self.model = os.getenv("OLLAMA_LLM_MODEL", "llama3.2")
+
+    def _format_similar(self, similar: list) -> str:
+        lines = []
+        for i, tx in enumerate(similar, 1):
+            label = "FRAUD" if tx.get("is_fraud") else "LEGITIMATE"
+            fraud_type = f" ({tx['fraud_type']})" if tx.get("fraud_type") else ""
+            score = tx.get("similarityScore", 0)
+            lines.append(
+                f"{i}. [{label}{fraud_type}] {tx.get('description', '')} "
+                f"| ${tx.get('amount', 0):.2f} | {tx.get('merchant', '')} "
+                f"| {tx.get('location', '')} | similarity: {score:.4f}"
+            )
+        return "\n".join(lines)
+
+    def run(self, transaction: dict, similar: list) -> dict:
+        user_prompt = (
+            f"NEW TRANSACTION TO ANALYZE:\n"
+            f"Description: {transaction['description']}\n"
+            f"Amount: ${transaction['amount']:.2f}\n"
+            f"Merchant: {transaction['merchant']}\n"
+            f"Category: {transaction['category']}\n"
+            f"Location: {transaction['location']}\n\n"
+            f"SIMILAR HISTORICAL TRANSACTIONS:\n"
+            f"{self._format_similar(similar)}\n\n"
+            f"Analyze the new transaction and respond with JSON only."
+        )
+
+        response = requests.post(
+            f"{self.base_url}/api/chat",
+            json={
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": ANALYSIS_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                "stream": False,
+                "format": "json",
+            },
+            timeout=120,
+        )
+        response.raise_for_status()
+        content = response.json()["message"]["content"]
+
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError:
+            risk_level = "MEDIUM"
+            if "HIGH" in content.upper():
+                risk_level = "HIGH"
+            elif "LOW" in content.upper():
+                risk_level = "LOW"
+            return {
+                "risk_indicators": [],
+                "trust_signals": [],
+                "risk_level": risk_level,
+                "reasoning": content[:500],
+            }
diff --git a/fraud-detection-agent-py/agents/decision_agent.py b/fraud-detection-agent-py/agents/decision_agent.py
new file mode 100644
index 0000000..925d9a6
--- /dev/null
+++ b/fraud-detection-agent-py/agents/decision_agent.py
@@ -0,0 +1,71 @@
+import json
+import os
+
+import requests
+
+DECISION_SYSTEM_PROMPT = """You are the final decision-maker in a fraud detection pipeline.
+
+Given a transaction and its risk analysis, output a final decision:
+- APPROVE: Low risk, process the transaction normally
+- REVIEW: Medium risk, flag for human review before processing
+- BLOCK: High risk, block the transaction immediately
+
+Respond ONLY with valid JSON in this exact format:
+{
+  "decision": "APPROVE",
+  "confidence": 0.85,
+  "reason": "one sentence explanation",
+  "recommended_action": "specific next step for the operations team"
+}"""
+
+
+class DecisionAgent:
+    """Agent 3 — makes the final APPROVE / REVIEW / BLOCK verdict."""
+
+    def __init__(self):
+        self.base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
+        self.model = os.getenv("OLLAMA_LLM_MODEL", "llama3.2")
+
+    def run(self, transaction: dict, analysis: dict) -> dict:
+        risk_indicators = ", ".join(analysis.get("risk_indicators", [])) or "none"
+        trust_signals = ", ".join(analysis.get("trust_signals", [])) or "none"
+
+        user_prompt = (
+            f"TRANSACTION:\n"
+            f"  {transaction['description']}\n"
+            f"  Amount: ${transaction['amount']:.2f} | Merchant: {transaction['merchant']} | Location: {transaction['location']}\n\n"
+            f"RISK ANALYSIS:\n"
+            f"  Risk Level  : {analysis.get('risk_level', 'UNKNOWN')}\n"
+            f"  Risk Indicators: {risk_indicators}\n"
+            f"  Trust Signals  : {trust_signals}\n"
+            f"  Reasoning   : {analysis.get('reasoning', '')}\n\n"
+            f"Make a final decision. Respond with JSON only."
+        )
+
+        response = requests.post(
+            f"{self.base_url}/api/chat",
+            json={
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": DECISION_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                "stream": False,
+                "format": "json",
+            },
+            timeout=120,
+        )
+        response.raise_for_status()
+        content = response.json()["message"]["content"]
+
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError:
+            risk_level = analysis.get("risk_level", "MEDIUM")
+            decision_map = {"LOW": "APPROVE", "MEDIUM": "REVIEW", "HIGH": "BLOCK"}
+            return {
+                "decision": decision_map.get(risk_level, "REVIEW"),
+                "confidence": 0.5,
+                "reason": "Automatic fallback decision based on risk level.",
+                "recommended_action": "Manual review required.",
+            }
diff --git a/fraud-detection-agent-py/agents/retrieval_agent.py b/fraud-detection-agent-py/agents/retrieval_agent.py
new file mode 100644
index 0000000..9d3f25d
--- /dev/null
+++ b/fraud-detection-agent-py/agents/retrieval_agent.py
@@ -0,0 +1,47 @@
+import os
+
+from utils.embeddings import get_embedding
+
+
+class RetrievalAgent:
+    """Agent 1 — retrieves similar historical transactions via DocumentDB vector search."""
+
+    def __init__(self, collection):
+        self.collection = collection
+        self.k = int(os.getenv("NEAREST_NEIGHBORS", "5"))
+
+    def _build_description(self, transaction: dict) -> str:
+        return (
+            f"Transaction: {transaction['description']}. "
+            f"Merchant: {transaction['merchant']}. "
+            f"Category: {transaction['category']}. "
+            f"Amount: ${transaction['amount']:.2f}. "
+            f"Location: {transaction['location']}."
+        )
+
+    def run(self, transaction: dict) -> list:
+        description = self._build_description(transaction)
+        embedding = get_embedding(description)
+
+        pipeline = [
+            {
+                "$search": {
+                    "cosmosSearch": {
+                        "vector": embedding,
+                        "path": "embedding",
+                        "k": self.k,
+                    },
+                    "returnStoredSource": True,
+                }
+            },
+            {
+                "$addFields": {
+                    "similarityScore": {"$meta": "searchScore"}
+                }
+            },
+            {
+                "$project": {"embedding": 0}
+            },
+        ]
+
+        return list(self.collection.aggregate(pipeline))
diff --git a/fraud-detection-agent-py/cleanup.py b/fraud-detection-agent-py/cleanup.py
new file mode 100644
index 0000000..0411e16
--- /dev/null
+++ b/fraud-detection-agent-py/cleanup.py
@@ -0,0 +1,17 @@
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from utils.db import get_client, get_collection
+
+
+def main():
+    client = get_client()
+    col = get_collection(client)
+    col.drop()
+    print(f"Dropped collection: {col.full_name}")
+    client.close()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/fraud-detection-agent-py/data/transactions.json b/fraud-detection-agent-py/data/transactions.json
new file mode 100644
index 0000000..ad0e9c0
--- /dev/null
+++ b/fraud-detection-agent-py/data/transactions.json
@@ -0,0 +1,202 @@
+[
+  {
+    "transaction_id": "TX001",
+    "description": "Regular weekly groceries purchased at local supermarket near registered home address",
+    "amount": 127.43,
+    "merchant": "Whole Foods Market",
+    "category": "Groceries",
+    "location": "Austin, TX",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX002",
+    "description": "Monthly gym membership auto-renewal charged to card on file as usual",
+    "amount": 49.99,
+    "merchant": "Planet Fitness",
+    "category": "Health & Fitness",
+    "location": "Chicago, IL",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX003",
+    "description": "Morning coffee and pastry at neighborhood coffee shop visited regularly on weekdays",
+    "amount": 6.75,
+    "merchant": "Blue Bottle Coffee",
+    "category": "Dining",
+    "location": "Brooklyn, NY",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX004",
+    "description": "Gas station fill-up at familiar station near home, normal volume for vehicle type",
+    "amount": 58.20,
+    "merchant": "Shell Gas Station",
+    "category": "Gas & Fuel",
+    "location": "Dallas, TX",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX005",
+    "description": "Dinner at local Italian restaurant with family on a Friday evening, tip included",
+    "amount": 94.50,
+    "merchant": "Trattoria Milano",
+    "category": "Dining",
+    "location": "San Francisco, CA",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX006",
+    "description": "Monthly streaming video subscription auto-renewal, same amount every month",
+    "amount": 15.99,
+    "merchant": "Netflix",
+    "category": "Subscriptions",
+    "location": "Online",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX007",
+    "description": "Prescription pickup at local pharmacy, same medications refilled monthly",
+    "amount": 23.40,
+    "merchant": "CVS Pharmacy",
+    "category": "Healthcare",
+    "location": "Seattle, WA",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX008",
+    "description": "Paperback novel purchased at neighborhood bookstore on a Saturday afternoon",
+    "amount": 18.95,
+    "merchant": "Powell's Books",
+    "category": "Books & Entertainment",
+    "location": "Portland, OR",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX009",
+    "description": "Monthly electric utility bill automatic payment, consistent with prior month amounts",
+    "amount": 132.00,
+    "merchant": "Austin Energy",
+    "category": "Utilities",
+    "location": "Austin, TX",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX010",
+    "description": "Automated monthly mortgage payment to known lender, identical amount each month",
+    "amount": 1850.00,
+    "merchant": "Chase Mortgage",
+    "category": "Mortgage",
+    "location": "Online Banking",
+    "is_fraud": false,
+    "fraud_type": null
+  },
+  {
+    "transaction_id": "TX011",
+    "description": "Multiple high-value gift cards purchased across different store locations within 20 minutes, buyer declined store assistance",
+    "amount": 3200.00,
+    "merchant": "Walmart Gift Cards",
+    "category": "Gift Cards",
+    "location": "Online",
+    "is_fraud": true,
+    "fraud_type": "gift_card_fraud"
+  },
+  {
+    "transaction_id": "TX012",
+    "description": "International wire transfer to unknown overseas account in Eastern Europe immediately following suspicious login from foreign IP address",
+    "amount": 9800.00,
+    "merchant": "International Wire Transfer",
+    "category": "Transfer",
+    "location": "International",
+    "is_fraud": true,
+    "fraud_type": "account_takeover"
+  },
+  {
+    "transaction_id": "TX013",
+    "description": "Luxury watch purchase from unverified online vendor, shipping address differs completely from billing address, no prior relationship",
+    "amount": 3750.00,
+    "merchant": "Prestige Timepieces Online",
+    "category": "Luxury Goods",
+    "location": "Online",
+    "is_fraud": true,
+    "fraud_type": "card_not_present"
+  },
+  {
+    "transaction_id": "TX014",
+    "description": "High-end electronics bulk order using newly opened account with unverified identity, expedited shipping to freight forwarder",
+    "amount": 4299.99,
+    "merchant": "TechVault Electronics",
+    "category": "Electronics",
+    "location": "Online",
+    "is_fraud": true,
+    "fraud_type": "synthetic_identity"
+  },
+  {
+    "transaction_id": "TX015",
+    "description": "Large transfer to new payee immediately following unauthorized password reset and email change, account holder unreachable",
+    "amount": 7500.00,
+    "merchant": "Digital Bank Wire",
+    "category": "Transfer",
+    "location": "Online",
+    "is_fraud": true,
+    "fraud_type": "phishing"
+  },
+  {
+    "transaction_id": "TX016",
+    "description": "Duplicate charge appearing at same gas station within 30 minutes, second charge submitted from skimming device after original",
+    "amount": 58.20,
+    "merchant": "QuickFuel Station",
+    "category": "Gas & Fuel",
+    "location": "Houston, TX",
+    "is_fraud": true,
+    "fraud_type": "card_skimming"
+  },
+  {
+    "transaction_id": "TX017",
+    "description": "Customer disputed high-value electronics purchase claiming non-receipt despite confirmed delivery signature on file",
+    "amount": 1289.00,
+    "merchant": "Amazon Marketplace",
+    "category": "Electronics",
+    "location": "Online",
+    "is_fraud": true,
+    "fraud_type": "friendly_fraud"
+  },
+  {
+    "transaction_id": "TX018",
+    "description": "New account opened with slightly altered identity details making immediate bulk fashion purchases before verification completes",
+    "amount": 2100.00,
+    "merchant": "Luxury Fashion Direct",
+    "category": "Apparel",
+    "location": "Miami, FL",
+    "is_fraud": true,
+    "fraud_type": "identity_theft"
+  },
+  {
+    "transaction_id": "TX019",
+    "description": "Corporate vendor invoice payment redirected to attacker bank account following spoofed email impersonating CFO with new wire instructions",
+    "amount": 15000.00,
+    "merchant": "Corporate Vendor Payment",
+    "category": "Business Transfer",
+    "location": "Wire Transfer",
+    "is_fraud": true,
+    "fraud_type": "business_email_compromise"
+  },
+  {
+    "transaction_id": "TX020",
+    "description": "ATM cash withdrawal in foreign country immediately followed by domestic online purchase within same minute, physically impossible",
+    "amount": 600.00,
+    "merchant": "ATM International Withdrawal",
+    "category": "Cash Withdrawal",
+    "location": "Budapest, Hungary",
+    "is_fraud": true,
+    "fraud_type": "atm_skimming"
+  }
+]
diff --git a/fraud-detection-agent-py/main.py b/fraud-detection-agent-py/main.py
new file mode 100644
index 0000000..cad814f
--- /dev/null
+++ b/fraud-detection-agent-py/main.py
@@ -0,0 +1,119 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from agents.analysis_agent import AnalysisAgent
+from agents.decision_agent import DecisionAgent
+from agents.retrieval_agent import RetrievalAgent
+from utils.db import get_client, get_collection
+
+# Transactions to analyze — different from the training data
+SAMPLE_TRANSACTIONS = [
+    {
+        "description": "Online purchase of high-value gift cards at multiple retailers within minutes of each other",
+        "amount": 2400.00,
+        "merchant": "RetailMart Gift Cards",
+        "category": "Gift Cards",
+        "location": "Online",
+    },
+    {
+        "description": "Restaurant dinner charge at a local bistro, regular weekend dining spot for this customer",
+        "amount": 87.50,
+        "merchant": "The Rustic Bistro",
+        "category": "Dining",
+        "location": "New York, NY",
+    },
+    {
+        "description": "International wire to overseas account initiated immediately after account password was changed",
+        "amount": 9800.00,
+        "merchant": "International Wire Service",
+        "category": "Transfer",
+        "location": "International",
+    },
+    {
+        "description": "Monthly grocery shopping at familiar supermarket consistent with prior month patterns",
+        "amount": 143.22,
+        "merchant": "Fresh Grocers",
+        "category": "Groceries",
+        "location": "Brooklyn, NY",
+    },
+    {
+        "description": "Luxury watch purchase from unknown online vendor, shipping address completely different from billing",
+        "amount": 3750.00,
+        "merchant": "Prestige Timepieces",
+        "category": "Luxury Goods",
+        "location": "Online",
+    },
+]
+
+GREEN  = "\033[92m"
+YELLOW = "\033[93m"
+RED    = "\033[91m"
+BOLD   = "\033[1m"
+RESET  = "\033[0m"
+
+DECISION_COLOR = {"APPROVE": GREEN, "REVIEW": YELLOW, "BLOCK": RED}
+
+
+def separator():
+    print("=" * 70)
+
+
+def main():
+    client = get_client()
+    col = get_collection(client)
+
+    retrieval = RetrievalAgent(col)
+    analysis  = AnalysisAgent()
+    decision  = DecisionAgent()
+
+    print(f"\n{BOLD}Fraud Detection Multi-Agent System{RESET}")
+    print(f"Database : {os.getenv('DOCUMENTDB_DATABASE', 'frauddb')}")
+    print(f"LLM Model: {os.getenv('OLLAMA_LLM_MODEL', 'llama3.2')}")
+    print(f"Neighbors: {os.getenv('NEAREST_NEIGHBORS', '5')}")
+
+    for i, tx in enumerate(SAMPLE_TRANSACTIONS, 1):
+        separator()
+        print(f"\nTransaction {i}/{len(SAMPLE_TRANSACTIONS)}")
+        print(f"  Merchant : {tx['merchant']}")
+        print(f"  Amount   : ${tx['amount']:.2f}")
+        print(f"  Location : {tx['location']}")
+        print(f"  Details  : {tx['description']}\n")
+
+        print("[ Agent 1: Retrieval ] Finding similar historical transactions...")
+        similar = retrieval.run(tx)
+        fraud_count = sum(1 for s in similar if s.get("is_fraud"))
+        legit_count = len(similar) - fraud_count
+        print(f"  Found {len(similar)} similar transactions ({fraud_count} fraud, {legit_count} legitimate)\n")
+
+        print("[ Agent 2: Analysis  ] Identifying risk patterns...")
+        result = analysis.run(tx, similar)
+        risk_level = result.get("risk_level", "UNKNOWN")
+        risk_color = {"LOW": GREEN, "MEDIUM": YELLOW, "HIGH": RED}.get(risk_level, "")
+        print(f"  Risk Level : {risk_color}{risk_level}{RESET}")
+        indicators = result.get("risk_indicators", [])
+        if indicators:
+            print(f"  Indicators : {', '.join(indicators[:3])}")
+        signals = result.get("trust_signals", [])
+        if signals:
+            print(f"  Trust      : {', '.join(signals[:2])}")
+        print()
+
+        print("[ Agent 3: Decision  ] Making final verdict...")
+        verdict = decision.run(tx, result)
+        dec = verdict.get("decision", "REVIEW")
+        color = DECISION_COLOR.get(dec, "")
+        confidence = verdict.get("confidence", 0)
+
+        print(f"\n  {BOLD}VERDICT : {color}{dec}{RESET}{BOLD} (confidence: {confidence:.0%}){RESET}")
+        print(f"  Reason  : {verdict.get('reason', '')}")
+        print(f"  Action  : {verdict.get('recommended_action', '')}")
+
+    separator()
+    client.close()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/fraud-detection-agent-py/requirements.txt b/fraud-detection-agent-py/requirements.txt
new file mode 100644
index 0000000..a979282
--- /dev/null
+++ b/fraud-detection-agent-py/requirements.txt
@@ -0,0 +1,3 @@
+pymongo>=4.6.0
+python-dotenv>=1.0.0
+requests>=2.31.0
diff --git a/fraud-detection-agent-py/upload_data.py b/fraud-detection-agent-py/upload_data.py
new file mode 100644
index 0000000..81385a8
--- /dev/null
+++ b/fraud-detection-agent-py/upload_data.py
@@ -0,0 +1,68 @@
+import json
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from utils.db import get_client, get_collection
+from utils.embeddings import get_embedding
+
+
+def build_description(tx: dict) -> str:
+    return (
+        f"Transaction: {tx['description']}. "
+        f"Merchant: {tx['merchant']}. "
+        f"Category: {tx['category']}. "
+        f"Amount: ${tx['amount']:.2f}. "
+        f"Location: {tx['location']}."
+    )
+
+
+def main():
+    data_path = Path(__file__).parent / "data" / "transactions.json"
+    with open(data_path) as f:
+        transactions = json.load(f)
+
+    print(f"Loaded {len(transactions)} transactions\n")
+
+    client = get_client()
+    col = get_collection(client)
+    col.drop()
+    print("Cleared existing collection\n")
+
+    print("Generating embeddings and uploading...")
+    docs = []
+    for i, tx in enumerate(transactions, 1):
+        label = "FRAUD" if tx.get("is_fraud") else "legit"
+        print(f"  [{i:2}/{len(transactions)}] [{label:5}] {tx['merchant']}: {tx['description'][:55]}...")
+        tx["embedding"] = get_embedding(build_description(tx))
+        docs.append(tx)
+
+    col.insert_many(docs)
+    print(f"\nInserted {len(docs)} documents")
+
+    dimensions = int(os.getenv("EMBEDDING_DIMENSIONS", "768"))
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "frauddb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "transactions")
+
+    client[db_name].command({
+        "createIndexes": col_name,
+        "indexes": [{
+            "key": {"embedding": "cosmosSearch"},
+            "name": "idx_vector_embedding",
+            "cosmosSearchOptions": {
+                "kind": "vector-ivf",
+                "numLists": 1,
+                "similarity": "COS",
+                "dimensions": dimensions,
+            },
+        }],
+    })
+    print(f"Vector index created (vector-ivf, dimensions: {dimensions}, similarity: COS)")
+    client.close()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/fraud-detection-agent-py/utils/__init__.py b/fraud-detection-agent-py/utils/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fraud-detection-agent-py/utils/db.py b/fraud-detection-agent-py/utils/db.py
new file mode 100644
index 0000000..a194aff
--- /dev/null
+++ b/fraud-detection-agent-py/utils/db.py
@@ -0,0 +1,14 @@
+import os
+
+from pymongo import MongoClient
+
+
+def get_client() -> MongoClient:
+    uri = os.environ["DOCUMENTDB_URI"]
+    return MongoClient(uri, tlsAllowInvalidCertificates=True)
+
+
+def get_collection(client: MongoClient):
+    db_name = os.getenv("DOCUMENTDB_DATABASE", "frauddb")
+    col_name = os.getenv("DOCUMENTDB_COLLECTION", "transactions")
+    return client[db_name][col_name]
diff --git a/fraud-detection-agent-py/utils/embeddings.py b/fraud-detection-agent-py/utils/embeddings.py
new file mode 100644
index 0000000..5968843
--- /dev/null
+++ b/fraud-detection-agent-py/utils/embeddings.py
@@ -0,0 +1,15 @@
+import os
+
+import requests
+
+
+def get_embedding(text: str) -> list:
+    base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
+    model = os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")
+    response = requests.post(
+        f"{base_url}/api/embeddings",
+        json={"model": model, "prompt": text},
+        timeout=60,
+    )
+    response.raise_for_status()
+    return response.json()["embedding"]
diff --git a/registry.yml b/registry.yml
index 1f508b1..9f46012 100644
--- a/registry.yml
+++ b/registry.yml
@@ -43,3 +43,54 @@ samples:
       - Vanilla JS
       - Full Stack
     githubUrl: "https://github.com/documentdb/documentdb-samples-gallery/tree/main/retail-product-store-js"
+
+  - id: fraud-detection-agent-py
+    title: "Fraud Detection Multi-Agent System: Retrieval, Analysis, and Decision Agents with DocumentDB Vector Search"
+    description: "A Python app that uses a three-agent pipeline — Retrieval, Analysis, and Decision — to classify transactions as APPROVE, REVIEW, or BLOCK. The Retrieval Agent finds similar historical transactions using DocumentDB OSS native vector search; the Analysis Agent uses llama3.2 via Ollama to identify risk patterns; the Decision Agent issues the final verdict with a confidence score. Runs entirely on open-source tools with no cloud accounts required."
+    language: Python
+    industry: Financial Services
+    difficulty: Intermediate
+    tags:
+      - Vector Search
+      - Multi-Agent
+      - Fraud Detection
+      - Ollama
+      - Embeddings
+      - RAG
+      - DocumentDB OSS
+      - Open Source
+    githubUrl: "https://github.com/documentdb/documentdb-samples-gallery/tree/main/fraud-detection-agent-py"
+
+  - id: content-semantic-search-py
+    title: "Content Semantic Search Portal: Semantic Search Over Articles, Blogs, and PDFs"
+    description: "A Python/Flask web portal that stores articles, blogs, and PDF documents as MongoDB documents with vector embeddings in DocumentDB OSS. Users search by meaning using natural language and receive semantically ranked results by cosine similarity. Supports ingesting custom .txt and .pdf files alongside sample content. Built entirely on open-source tools with no cloud accounts required."
+    language: Python
+    industry: Media & Publishing
+    difficulty: Beginner
+    tags:
+      - Vector Search
+      - Semantic Search
+      - Flask
+      - Embeddings
+      - Ollama
+      - PDF
+      - DocumentDB OSS
+      - Open Source
+    githubUrl: "https://github.com/documentdb/documentdb-samples-gallery/tree/main/content-semantic-search-py"
+
+  - id: clinical-note-similarity-py
+    title: "Clinical Note Similarity Explorer: Find Similar Cases with DocumentDB Vector Search"
+    description: "A Python/Flask web app that stores de-identified fictional clinical notes with vector embeddings and metadata in DocumentDB OSS. Clinicians and researchers can search for similar cases using natural language clinical descriptions, filtered by medical specialty, with results ranked by semantic similarity. All notes are fictional sample data. Built entirely on open-source tools."
+    language: Python
+    industry: Healthcare
+    difficulty: Intermediate
+    tags:
+      - Vector Search
+      - Semantic Search
+      - Flask
+      - Embeddings
+      - Ollama
+      - Clinical NLP
+      - DocumentDB OSS
+      - Open Source
+    githubUrl: "https://github.com/documentdb/documentdb-samples-gallery/tree/main/clinical-note-similarity-py"