diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..8515248 --- /dev/null +++ b/.env.example @@ -0,0 +1,3 @@ +# Copy to .env (never commit .env). Used by scripts/, not by the app. +# Create a key at https://aistudio.google.com/apikey and pick the project g311-communication-needs-map. +GEMINI_API_KEY= diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..3202555 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# The team's advisors are asked to review every pull request. +* @kquakk @skarthikb-tech diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..addee33 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,25 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: astral-sh/setup-uv@v10.3.0 + - run: uv sync --locked + - run: uv run ruff check + - run: uv run ruff format --check + - run: uv run pytest + # Streamlit Community Cloud installs from requirements.txt; keep it in step with uv.lock. + - name: requirements.txt matches uv.lock + run: | + uv export --no-dev --no-hashes --no-emit-project -o requirements.txt + git diff --exit-code requirements.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c493864 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +.venv/ +.env +__pycache__/ +.pytest_cache/ +.ruff_cache/ +.streamlit/secrets.toml diff --git a/.python-version b/.python-version new file mode 100644 index 0000000..e4fba21 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.12 diff --git a/.streamlit/config.toml b/.streamlit/config.toml new file mode 100644 index 0000000..7357e68 --- /dev/null +++ b/.streamlit/config.toml @@ -0,0 +1,3 @@ +[theme] +base = "light" +primaryColor = "#1a73e8" diff --git a/README.md b/README.md index c5403c5..bae207f 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,46 @@ Georgia 311 Challenge 2026 · DevDogs (GDG on Campus UGA) - Advisor: Kyle Quach and Shakthi Karthik - Sprint: Oct 16–30, 2026. Demo Day: Fri Oct 30 at DevFest Atlanta. -Starter code is added once the team confirms its stack at the Oct 19 kickoff. +## What's here + +A blank [Streamlit](https://streamlit.io) app, plus the council district boundaries. Nothing is built yet; that's up to you. + +| File | What it's for | +| --- | --- | +| `app.py` | The app. Start here. It should read only files in `data/`, so it runs anywhere with no keys. | +| `data/` | Committed data the app reads. The six council districts and the city limits are already here (see `data/README.md` for the source). | +| `scripts/` | Code you run on your own machine to fetch and prepare data, writing the results to `data/`. [geopandas](https://geopandas.org) is installed for joining Census areas to districts. | +| `scripts/gemini.py` | `client()` returns a Gemini client for writing summaries ahead of time. It reads `GEMINI_API_KEY` from `.env` (copy `.env.example`). | +| `tests/` | [pytest](https://docs.pytest.org) tests. `test_app.py` checks the app starts without errors. | + +If Gemini replies "This model is currently experiencing high demand", change the model in `scripts/gemini.py` to an older Flash model such as `gemini-3.5-flash`. The newest model is the busiest on the free tier. + +The Census data source comes in a separate pull request: the BigQuery sandbox or the Census API. Merge one. + +## Run it locally + +Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then: + +```sh +uv sync +uv run streamlit run app.py # http://localhost:8501, reloads as you edit +uv run python scripts/