M4 Tasks

[agill59]

Milestone 4 - Finalizing your AI Dashboard Copy (Task allocation/checklist)

In this milestone, you will finalize your dashboard into a production-ready product.
You will improve performance, extend your AI feature, write logic tests,
and address feedback from your instructor, TA, and peers.

Before starting, re-read the General Project Guidelines.
Submission, versioning, and GitHub workflow requirements are the same throughout the course.
You can also use feedback based on your gh activity to guide changes in this part.

Deliverables Checklist

• Working App: Functional app deployed on Posit Connect Cloud; stable URL linked in the repo About section.
• Parquet + DuckDB: Data loading switched to parquet/DuckDB with controls wired via ibis or SQL.
• Advanced Feature: One advanced feature implemented and discussed in a GitHub Issue (see Section 4), with necessary extra files.
• Tests: At least 3 behaviors tested (using playwright) and documented with one-sentence descriptions and at least 1 function unit tested (see Section 5).
• Feedback Prioritization Issue: GitHub Issue M4 Feedback Prioritization created, all items categorized and closed or explained.
• Feedback Addressed: All critical items resolved; at least one resolved item per team member.
• CONTRIBUTING.md: Updated with M3 retrospective and M4 collaboration norms, merged via PR.
• Spec Docs Updated: Specification document(s) reflect decisions made this milestone before code was written.
• CHANGELOG: CHANGELOG.md updated with a [0.4.0] entry - all 7 subheadings present and cross-linked (Added / Changed / Fixed / Known Issues / Release Highlight / Collaboration / Reflection). See the template.
• Release v0.4.0: Created on GitHub with release notes summarizing merged PRs.
• Gradescope Submission: PDF with link to release submitted.

---

1. Submission Instructions (10)

Same as previous milestones - see General Project Guidelines.
Remember to republish your stable Posit Connect Cloud deployment after creating your v0.4.0 release.

---

2. Collaboration -- for the project as a whole (20)

Same GitHub workflow as previous milestones - all changes reach main via pull requests,
each PR receives at least one peer review before merging, and tasks are tracked as GitHub Issues
closed through the resolving PR. Your specification document(-s) should be updated before any substantial changes, and they should reflect decision-making happening before code writing, not the opposite.
See General Project Guidelines for the full workflow.

For M4, pay particular attention to:

• Work organization: work on code and documentation should be spread across team members - no single person should carry the codebase or dominate the review queue. If you had issues with that before, in M4 you have an opportunity to demonstrate good practices, organizing work on the app and explaining the changes you implemented (yourself or based on our advice). For example, the M4 feedback section is an opportunity to help to involve every team member resolves at least one feedback item.
• Scoped PRs: each PR addresses one feature or fix, with atomic commits, meaningful messages and updated documentation before the code, without code dumps.
• Design before code: for larger features, issues, PR descriptions, and design doc changes should explain intent before writing the implementation - this gives teammates context.
• No deadline-eve bursts: last moment changes lead to worse practices. We do not penalize that directly, but last pushes are most likely to be reviewed particularly closely. Try to spread contributions throughout the milestone, not concentrate into the final night.
• Legible release notes: your v0.4.0 release must include a summary of merged PRs categorized by type
  (Added / Changed / Fixed), and added reflection (see general guidelines) so the project history is readable to the whole team. This is where we start our grading from, so all changes and deviations should be rationalized here as well.
• CONTRIBUTING.md: update this file with a brief retrospective on your M3 collaboration (what worked, what didn't) and any norms your team is committing to for M4. Submit it via a PR so the decision is on record.

---

3. Performance: Parquet + DuckDB (10)

• This week you will switch your data to lazy loading with parquet + DuckDB,
  so that filters are applied at the database level and only matching rows are pulled into memory.

Your team must:

1. Convert your processed dataset to parquet format (store in data/processed/).
2. Connect to it using ibis + DuckDB (or raw DuckDB SQL if you prefer).
3. Wire your Shiny input controls to the query using @reactive.calc -
   all filtering must happen before the data enters a DataFrame.
4. Verify the app renders correctly and that filters still work as expected after the switch.

Note: if your dataset is small (< 50k rows), the performance gain will be minimal,
but you still need to practice it for production at scale.

---

4. Advanced Feature (Pick One) (20)

• Choose one of the following options and implement it in your dashboard.
  All options are worth the same points.

You should briefly discuss the option priortization and how it fits into your dashboard concept in github issue, and reflect the results in specification documents.

Option A: Querychat Customization

Extend the AI tab from M3 by customizing querychat's behavior:

• Override the system prompt (or its parts) to give the LLM meaningful context about your dataset and the user's goals.
• Use on_tool_request to intercept LLM tool calls to validate, log, or transform them before execution.
• Add at least one user-facing control that affects LLM behavior
  (e.g., a slider for response verbosity, a dropdown to switch response style, or a toggle to restrict scope).
• For all decisions the motivation should be based on experimentation, your repository should contain a notebook with experiments and narrative, and the resulting option and summary of motivation should be reflected in the specifications document.

Option B: Persistent LLM Logging

Log querychat interactions to an external source (e.g. MongoDB Atlas, Google Sheets, ...):

• Record each query, the LLM's response, and a timestamp.
• Display a summary of recent interactions in the app (e.g., a table of past queries with responses).
• Handle errors gracefully: logging failures must not break the UI.
• Describe WHY you need the log and demonstrate how you would use it for your goals (sketch a data pipeline and illustrate with examples, .ipynb is fine)

Option C: RAG: Custom Knowledge Base for Querychat

Inject domain-specific knowledge into your querychat interface:

• Create a small knowledge base relevant to your dataset
  (e.g., a glossary, a methodology document, or curated Q&A pairs).
• Connect it to querychat so the LLM can retrieve and cite relevant context when answering user questions.
• Demonstrate at least one query in your reflection where the RAG context visibly improves the response
  compared to without it.

Option D: Component click event interaction

Have you application react to one of your output components (bar in bargraph, point/line/ploygon in a map, section of a pie chart, etc).

• Treat one of your output components as if it was an input component, where some click interaction will filter the underlying reactive calc data and have the rest of your application react to the filtered data.

Examples:

• Clicking on a country in a map will act as if the user selected the country from an input dropdown
• Clicking on a category in a bar graph or pie chart will filter the dashboard data for that selected category
• Clicking on a point in a map will display in an output component additional details about the selectecd point (this would be different from a hoverover effect)

---

5. Tests (10)

Write tests that verify the core logic of your dashboard.
The goal is not full coverage - it is to document expected behavior
and make it clear what breaks if the logic changes.

• Choose any of the following formats:

• Unit tests (pytest): test functions in isolation with explicit inputs and expected outputs.

• Doctests: embed examples directly in your function docstrings.

• Analysis notebook (notebooks/logic_tests.ipynb): run your main filtering or aggregation functions
  across representative parameter combinations and show expected vs. actual output.

Regardless of format, your tests must:

• Cover at least 3 distinct behaviors using playwright
  (e.g., edge-case filter, aggregation correctness, a data type or boundary condition).
• Refactor your code into at least 1 function and write a unit test (pytest) for it.
• Include a one-sentence description per test explaining what behavior is being verified and why it matters for the dashboard.
• Pass on a clean environment. Document how to run them in your README.
• Tests must be runnable with a single command documented in your README.
• In your reflection, describe what each test covers and what could break if the behavior changes.

---

6. Address Feedback (20)

You will receive feedback from three sources this milestone:
your instructor (lab review at M3 and M4), your TA (written comments, lab review, grading), and peers (peer review).

Process:

1. Collect all feedback into a single GitHub Issue titled M4 Feedback Prioritization.
2. Discuss as a team and categorize each item as:
   • Critical: broken functionality, major UX problem, accuracy issue - must be fixed (your instructor can point critical issues, you can't de-prioritize those).
   • Non-critical: improvements, polish, nice-to-haves.
3. Reflect the addressed issues in your specification (you can make them sub-items).
4. Address all critical items.
5. Each team member must resolve at least one item (critical or non-critical).
   If the number of critical items is less than the team size, each remaining team member picks
   one additional non-critical item to address.
6. Close each item either through a PR (if implementing the fix)
   or by commenting why it won't be addressed and closing it as "not planned".

In your reflection, briefly explain your prioritization: why were certain items critical,
and what trade-offs did you make?

Finally make sure your project card is rendering properly https://ubc-mds.github.io/DSCI_532-projects/

• Has a proper running gif
• Dashboard adn Repo links are working
• When you click on the group number the sketch and gif are rendering.

---

7. Changelog and Reflection (10)

• Update CHANGELOG.md with a [0.4.0] entry following the format from the
  General Project Guidelines.
  This is where grading starts - make it complete and use it to cross-reference your work.

Use the structure below as your starting point:

## [0.4.0] - YYYY-MM-DD

### Added

- <!-- New features, components, tests - one line each. Reference PRs where relevant (e.g. #12). -->

### Changed

- <!-- Spec or design deviations, and motivation. -->
- <!-- Feedback items you addressed: "Addressed: <item description> (#<prioritization issue>) via #<PR>" -->

### Fixed

- <!-- Bugs resolved since M3. -->

- **Feedback prioritization issue link:** #...

### Known Issues

- <!-- Anything incomplete or broken TAs should be aware of (so it isn't mistaken for unfinished work). -->

### Release Highlight: [Name of your advanced feature]

<!-- One short paragraph describing what you built and what it does for the user. -->

- **Option chosen:** A / B / C / D
- **PR:** #...
- **Why this option over the others:** <!-- 1–2 sentences; link to your feature prioritization issue -->
- **Feature prioritization issue link:** #...

### Collaboration

<!-- Summary of workflow or collaboration improvements made since M3. -->

- **CONTRIBUTING.md:** <!-- Link to the PR that updated it with your M3 retrospective and M4 norms. -->
- **M3 retrospective:** <!-- What changed in your workflow after M3 collaboration feedback. -->
- **M4:** <!-- What you tried or improved this milestone. -->

### Reflection

<!-- Standard (see General Guidelines): what the dashboard does well, current limitations,
     any intentional deviations from DSCI 531 visualization best practices. -->

<!-- Trade-offs: one sentence on feedback prioritization - full rationale is in #<issue> and ### Changed above. -->

<!-- Most useful: which lecture, material, or feedback shaped your work most this milestone,
     and anything you wish had been covered. -->