diff --git a/plugins/help_guide.py b/plugins/help_guide.py index c6df43e..48b90e5 100644 --- a/plugins/help_guide.py +++ b/plugins/help_guide.py @@ -1,29 +1,49 @@ """ Help & FAQ plugin for Reflecting Pool. -Provides a user-friendly guide for non-technical users. Designed to -be the first place new users look when they're unsure how things work. +Provides a user-friendly usage guide and FAQ for non-technical users. +Designed to be the first place new users look when they're unsure how +things work. """ from plugin_loader import register +GITHUB_REPO = "https://github.com/aadams149/Reflecting-Pool" +GITHUB_PROFILE = "https://github.com/aadams149" + @register( "Help & FAQ", order=200, needs_df=False, - description="Plain-language guide and frequently asked questions", + description="Plain-language usage guide and frequently asked questions", ) def render(ctx): import streamlit as st st.markdown( - "Welcome to **Reflecting Pool**! This guide answers the most " - "common questions about how the app works. Click any section " - "below to expand it." + "Welcome to **Reflecting Pool**! This guide covers how to use " + "the app and answers frequently asked questions. Pick a section " + "below to get started." + ) + + # GitHub links + st.markdown( + f'' + '' + "Reflecting Pool on GitHub" + "  |  " + f'@aadams149', + unsafe_allow_html=True, ) st.divider() + # ================================================================== + # USAGE GUIDE + # ================================================================== + st.subheader("Usage Guide") + # ------------------------------------------------------------------ # 1. Getting Started # ------------------------------------------------------------------ @@ -32,7 +52,7 @@ def render(ctx): **What is Reflecting Pool?** Reflecting Pool turns your handwritten journal into a searchable, -analysable digital archive. You take photos of your journal pages, +analyzable digital archive. You take photos of your journal pages, the app reads the handwriting (using OCR - optical character recognition), and then you can search, browse, and explore your entries right here in the dashboard. @@ -67,8 +87,8 @@ def render(ctx): | Method | How it works | |--------|-------------| -| **Batch processing** | Place all photos in a folder, then run the OCR command once. Best for a large backlog of photos. | -| **OCR Watcher** | Use the *OCR Watcher* section in the sidebar to watch a folder. Every time you add a new photo, it's processed automatically. | +| **Batch processing** | Place all photos in a folder, then run the OCR command once. Best for a large backlog of photos. | +| **OCR Watcher** | Use the *OCR Watcher* section in the sidebar to watch a folder. Every time you add a new photo, it's processed automatically. | After processing, each entry gets a date (extracted from the filename or the photo's creation date) and a plain-text file. @@ -82,16 +102,16 @@ def render(ctx): **How search works** Reflecting Pool uses *semantic search*, which means you can search by -meaning rather than exact words. For example, searching for +meaning rather than exact words. For example, searching for "feeling stressed about deadlines" will find entries that talk about work pressure even if those exact words don't appear. **Two ways to search** - **Sidebar search** - type a query in the *Search* box on the left - and click **Search**. Results appear right in the sidebar. + and click **Search**. Results appear right in the sidebar. - **Chat tab** - open the **Chat** tab and have a conversation about - your journal. The AI assistant can pull relevant entries into its + your journal. The AI assistant can pull relevant entries into its answers. **Tips for better results** @@ -118,8 +138,8 @@ def render(ctx): **Sentiment analysis** Each entry is given a *sentiment score* between -1 (very negative) and -+1 (very positive). This is calculated automatically using a tool -called VADER, which looks at the words you used. It's a rough guide ++1 (very positive). This is calculated automatically using a tool +called VADER, which looks at the words you used. It's a rough guide to the emotional tone - not a clinical assessment. - Scores above **+0.3** are considered positive. @@ -143,18 +163,21 @@ def render(ctx): st.markdown(""" **What the Music tab does** -If you have Spotify listening data, Reflecting Pool can show what you -were listening to around the time of each journal entry. This can -surface interesting connections between your mood and your music. +Reflecting Pool scans your journal entries for mentions of songs and +artists, then looks them up on Apple Music / iTunes to show album +artwork, track details, and preview links. It's a fun way to see +what music was on your mind while you were writing. -**How to add Spotify data** +**How to get the best results** -1. Request your data from Spotify (Account > Privacy > Download your data). -2. Place the exported JSON files in the expected location. -3. The **Music** tab will automatically pick them up. +The detection works best when you're specific in your journal: -If you don't use Spotify or haven't added the data yet, the Music tab -will simply let you know. +- **Use quotes** - *listened to "Everlong" by Foo Fighters* +- **Mention artists** - *been listening to a lot of Radiohead lately* +- **Use colons** - *Song: "Karma Police"* + +If the Music tab says no mentions were detected, try writing about +songs or artists in your entries and they'll appear next time. """) # ------------------------------------------------------------------ @@ -162,14 +185,14 @@ def render(ctx): # ------------------------------------------------------------------ with st.expander("Customizing Appearance", expanded=False): st.markdown(""" -**Themes and colours** +**Themes and colors** -Open the **Appearance** tab to change the look of the dashboard. You +Open the **Appearance** tab to change the look of the dashboard. You can adjust: -- **Primary colour** - the accent colour used on buttons and highlights -- **Background colour** - the main background of the page -- **Text colour** - the default text colour +- **Primary color** - the accent color used on buttons and highlights +- **Background color** - the main background of the page +- **Text color** - the default text color - **Font family** and **font size** Changes are saved automatically and will persist the next time you open @@ -190,7 +213,7 @@ def render(ctx): - Make sure the *OCR Output Directory* in the sidebar points to the correct folder (it should contain `text/` and `metadata/` - sub-folders). + subfolders). - Confirm that you've run the OCR pipeline at least once so there are processed text files. @@ -210,13 +233,115 @@ def render(ctx): **The app feels slow** -- Large numbers of entries can take a moment to load. Try narrowing +- Large numbers of entries can take a moment to load. Try narrowing the date range in the sidebar. - The first search after starting the app may be slower while the database loads into memory. +""") + + # ================================================================== + # FAQ + # ================================================================== + st.divider() + st.subheader("Frequently Asked Questions") + + with st.expander("Does Reflecting Pool share my data with anyone?", expanded=False): + st.markdown(""" +**No.** Reflecting Pool runs entirely on your own computer. Your +journal text, photos, and search database all stay on your machine. +Nothing is uploaded to the cloud or shared with third parties. + +The only network calls the app makes are: + +- **Apple Music / iTunes lookups** when the Music tab searches for + song metadata (only the song or artist name is sent, not your + journal text). +- **Chat tab** requests, if you've configured an AI provider - only + the specific journal excerpts relevant to your question are sent. + +You can use the app completely offline if you skip the Music and Chat +features. +""") + + with st.expander("I think I've found a bug. How can I report it?", expanded=False): + st.markdown(f""" +The best way to report a bug is to open an issue on GitHub: + +1. Go to the [Reflecting Pool Issues page]({GITHUB_REPO}/issues). +2. Click **New Issue**. +3. Describe what happened, what you expected, and any error messages + you saw. + +If you're not comfortable with GitHub, you can also reach the +developer at their [GitHub profile]({GITHUB_PROFILE}). +""") + + with st.expander("What languages does Reflecting Pool support?", expanded=False): + st.markdown(""" +Currently, Reflecting Pool is optimized for **English** handwriting. +The OCR engine (Tesseract) supports many languages, but the sentiment +analysis and text processing features are English-focused. + +Support for additional languages is something we'd like to add in the +future. +""") + + with st.expander("Can I use typed/printed text instead of handwriting?", expanded=False): + st.markdown(""" +Yes! The OCR engine works with both handwritten and printed text. +In fact, printed text tends to be recognized more accurately. Just +take a photo of the page the same way you would for handwriting. +""") + + with st.expander("How accurate is the sentiment analysis?", expanded=False): + st.markdown(""" +Sentiment analysis provides a general sense of the emotional tone of +each entry, but it's not perfect. The tool (VADER) was designed for +social media text, so it works best with straightforward language. + +Things to keep in mind: + +- **Sarcasm and irony** are often misread. +- **Mixed entries** (good and bad things in one entry) may average out + to neutral. +- The scores are most useful as a **general trend** over time rather + than a precise measurement of any single entry. +""") + + with st.expander("Can I back up my data?", expanded=False): + st.markdown(""" +Yes. Your data lives in a few places on your computer: + +| What | Where | +|------|-------| +| Original photos | Wherever you saved them | +| OCR output (text + metadata) | The *OCR Output Directory* shown in the sidebar | +| Search database | The *RAG Database Path* shown in the sidebar | +| Theme settings | `theme.json` in the project folder | + +To back up, simply copy these folders to an external drive or cloud +storage. The search database can also be rebuilt at any time by +clicking *Ingest to RAG* in the sidebar. +""") + + with st.expander("Can I add plugins or extend the app?", expanded=False): + st.markdown(f""" +Yes! Reflecting Pool has a plugin system. You can add new tabs by +dropping a Python file into the `plugins/` folder. Each plugin is a +small script that uses the `@register` decorator to add itself to the +dashboard. + +For details on how to write a plugin, see the +[plugins README]({GITHUB_REPO}/tree/main/plugins) on GitHub. +""") + + with st.expander("Do I need an internet connection?", expanded=False): + st.markdown(""" +For most features, **no**. The OCR processing, analytics, search, and +appearance customization all work offline. -**Something else?** +You will need an internet connection for: -Check the project's GitHub page for open issues, or create a new -issue describing what you're experiencing. +- **Music tab** - looks up song info on Apple Music / iTunes. +- **Chat tab** - sends queries to an AI provider (if configured). """)