Skip to content

Commit d3f6ec6

Browse files
bassosimonebassosimone
committed
feat: introduce initial prototype streamlit app
This pull request introduces the initial prototype streamlit app wiring the iqb library dependency in. We also introduce a github workflow to test it's all WAI. While there, document how to install `uv` on macOS.
1 parent c96eb6a commit d3f6ec6

File tree

9 files changed

+938
-18
lines changed

9 files changed

+938
-18
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 54 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,18 +22,62 @@ jobs:
2222
- name: Set up Python
2323
run: uv python install 3.13
2424

25-
- name: Install library
26-
run: |
27-
cd library
28-
uv venv
29-
uv pip install -e .
25+
- name: Sync workspace dependencies
26+
run: uv sync
3027

3128
- name: Test library imports
32-
run: |
33-
cd library
34-
uv run python -c "from iqb import IQB, IQB_CONFIG; print('✓ IQB and IQB_CONFIG imported')"
29+
run: uv run python -c "from iqb import IQB, IQB_CONFIG; print('✓ IQB and IQB_CONFIG imported')"
3530

3631
- name: Run library smoke test
32+
run: uv run python -c "from iqb import IQB; iqb = IQB(); score = iqb.calculate_iqb_score(); print(f'✓ IQB score calculated: {score}')"
33+
34+
test-prototype:
35+
name: Test Streamlit Prototype
36+
runs-on: ubuntu-latest
37+
steps:
38+
- uses: actions/checkout@v4
39+
40+
- name: Install uv
41+
uses: astral-sh/setup-uv@v3
42+
with:
43+
enable-cache: true
44+
45+
- name: Set up Python
46+
run: uv python install 3.13
47+
48+
- name: Sync workspace dependencies
49+
run: uv sync
50+
51+
- name: Test prototype imports
3752
run: |
38-
cd library
39-
uv run python -c "from iqb import IQB; iqb = IQB(); score = iqb.calculate_iqb_score(); print(f'✓ IQB score calculated: {score}')"
53+
uv run python -c "import streamlit; print('✓ Streamlit imported')"
54+
uv run python -c "from iqb import IQB; print('✓ Can import IQB library from prototype')"
55+
56+
- name: Validate Home.py syntax
57+
run: |
58+
cd prototype
59+
uv run python -m py_compile Home.py
60+
echo "✓ Home.py syntax valid"
61+
62+
- name: Test Streamlit app can load
63+
run: |
64+
cd prototype
65+
# Start streamlit in background, wait for it to be ready, then kill it
66+
timeout 10s uv run streamlit run Home.py --server.headless=true --server.port=8501 > /tmp/streamlit.log 2>&1 &
67+
STREAMLIT_PID=$!
68+
69+
# Wait for streamlit to start (max 8 seconds)
70+
for i in {1..8}; do
71+
if grep -q "You can now view your Streamlit app" /tmp/streamlit.log 2>/dev/null; then
72+
echo "✓ Streamlit app started successfully"
73+
kill $STREAMLIT_PID 2>/dev/null || true
74+
exit 0
75+
fi
76+
sleep 1
77+
done
78+
79+
# If we get here, streamlit didn't start properly
80+
echo "✗ Streamlit failed to start"
81+
cat /tmp/streamlit.log
82+
kill $STREAMLIT_PID 2>/dev/null || true
83+
exit 1

‎README.md‎

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,30 +27,63 @@ https://www.measurementlab.net/publications/IQB_executive_summary_2025.pdf).
2727

2828
## Repository Architecture
2929

30-
### **`data/`**
31-
32-
Sample datasets used in the IQB app prototype and notebooks.
33-
3430
### **`library/`**
3531

3632
The IQB library containing methods for calculating the IQB score and data collection.
3733

34+
See [library/README.md](library/README.md) for details.
35+
3836
### **`prototype/`**
3937

40-
A simple web application implemented using Python's [streamlit](https://streamlit.io/)
41-
library for applying and parametrizing the IQB framework in different use cases.
38+
A Streamlit web application for applying and parametrizing the IQB framework
39+
in different use cases.
40+
41+
See [prototype/README.md](prototype/README.md) for how to run it locally.
4242

4343
### **`analysis/`**
4444

4545
Jupyter notebooks for exploratory data analysis, experimentation, and research.
4646

47-
## Development Ennvironment
47+
### **`data/`**
48+
49+
Sample datasets used in the IQB app prototype and notebooks.
50+
51+
## Development Environment
4852

4953
We use [uv](https://astral.sh/uv) as a replacement for several Python repository
5054
management tools such as `pip`, `poetry`, etc.
5155

52-
On Ubuntu, you can install `uv` as follows:
56+
### Installing uv
57+
58+
On Ubuntu:
5359

5460
```bash
5561
snap install astral-uv
5662
```
63+
64+
On macOS:
65+
66+
```bash
67+
brew install uv
68+
```
69+
70+
On other platforms, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
71+
72+
### Quick Start
73+
74+
```bash
75+
# Clone the repository
76+
git clone https://github.com/m-lab/iqb.git
77+
cd iqb
78+
79+
# Sync all dependencies (creates .venv automatically)
80+
uv sync
81+
82+
# Run the Streamlit prototype
83+
cd prototype
84+
uv run streamlit run Home.py
85+
```
86+
87+
See component-specific READMEs for more details:
88+
- [library/README.md](library/README.md) - Working with the IQB library
89+
- [prototype/README.md](prototype/README.md) - Running the Streamlit app

‎prototype/Home.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
"""IQB Streamlit Prototype - Main Entry Point"""
2+
3+
import streamlit as st
4+
from iqb import IQB, IQB_CONFIG
5+
6+
st.set_page_config(
7+
page_title="IQB Prototype",
8+
page_icon="📊",
9+
layout="wide"
10+
)
11+
12+
st.title("Internet Quality Barometer (IQB)")
13+
st.write("Phase 1 Prototype - Streamlit Dashboard")
14+
15+
st.markdown("""
16+
### Welcome to the IQB Prototype
17+
18+
This dashboard implements the Internet Quality Barometer framework, which assesses
19+
Internet quality beyond simple "speed" measurements by considering multiple use cases
20+
and their specific network requirements.
21+
22+
**Current status**: Under active development
23+
""")
24+
25+
# Smoke test: calculate IQB score
26+
try:
27+
iqb = IQB()
28+
score = iqb.calculate_iqb_score()
29+
30+
st.success(f"✓ IQB Library loaded successfully")
31+
st.metric("Sample IQB Score", f"{score:.3f}")
32+
33+
with st.expander("View IQB Configuration"):
34+
st.json(IQB_CONFIG)
35+
36+
except Exception as e:
37+
st.error(f"Error loading IQB library: {e}")
38+
39+
st.info("Dashboard functionality coming soon...")

‎prototype/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# IQB Streamlit Prototype
2+
3+
Streamlit-based dashboard for the Internet Quality Barometer (IQB) project.
4+
5+
## Prerequisites
6+
7+
- Python 3.13 (see `.python-version` at repo root)
8+
- [uv](https://astral.sh/uv) installed (see root README.md)
9+
10+
## Running Locally
11+
12+
From the **repository root**:
13+
14+
```bash
15+
# Sync dependencies (creates .venv if needed)
16+
uv sync
17+
18+
# Run Streamlit app
19+
cd prototype
20+
uv run streamlit run Home.py
21+
```
22+
23+
The app will be available at: http://localhost:8501
24+
25+
## Development Workflow
26+
27+
```bash
28+
# Install/update dependencies after pulling changes
29+
uv sync
30+
31+
# Run the app
32+
cd prototype
33+
uv run streamlit run Home.py
34+
35+
# Make changes to Home.py - Streamlit auto-reloads on save
36+
```
37+
38+
## Project Structure
39+
40+
```
41+
prototype/
42+
├── Home.py # Main Streamlit entry point
43+
├── pyproject.toml # Dependencies (streamlit, pandas, mlab-iqb)
44+
└── README.md # This file
45+
```
46+
47+
## Dependencies
48+
49+
The prototype depends on:
50+
- **streamlit** - Web framework
51+
- **pandas** - Data manipulation
52+
- **numpy** - Numerical operations
53+
- **mlab-iqb** - IQB library (from `../library`, managed via uv workspace)
54+
55+
Dependencies are locked in the workspace `uv.lock` at the repository root.

‎prototype/app.py‎

Whitespace-only changes.

‎prototype/pyproject.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[project]
2+
name = "iqb-prototype"
3+
version = "0.1.0"
4+
description = "Streamlit prototype for Internet Quality Barometer"
5+
requires-python = ">=3.13"
6+
dependencies = [
7+
"streamlit>=1.39.0",
8+
"pandas>=2.2.0",
9+
"numpy>=1.26.0",
10+
"mlab-iqb",
11+
]
12+
13+
[tool.uv.sources]
14+
mlab-iqb = { workspace = true }

‎prototype/requirements_streamlit.txt‎

Whitespace-only changes.

‎pyproject.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[tool.uv.workspace]
2+
members = ["library", "prototype"]

0 commit comments

Comments
 (0)