Merge the recent pull requests from dev into main.

.github/workflows/data-integrity.yml

@@ -0,0 +1,31 @@
+name: Data Integrity Validation
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+
+jobs:
+  validate-data-integrity:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install optional dependencies
+        run: |
+          pip install jsonschema
+
+      - name: Run data integrity validator on valid example data
+        run: |
+          python -m data_integrity.validator \
+            --input data_integrity/examples/valid_data.json \
+            --schema data_integrity/examples/sample_schema.json \
+            --json

.gitignore

@@ -180,3 +180,11 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+
+# Virtual environments
+venv310/
+venv/
+
+# Federated Learning Models
+dreamsApp/app/models/production_chime_model/
+dreamsApp/app/models/temp_training_artifact/

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+"python.terminal.useEnvFile": true,
+"python-envs.defaultEnvManager": "ms-python.python:system",
+"python-envs.pythonProjects": []
+}

LOCATION_PROXIMITY_SUMMARY.md

@@ -0,0 +1,260 @@
+# Location-Proximity Analysis Extension
+
+## Overview
+
+A new module for DREAMS that analyzes **multi-dimensional location proximity** to understand how semantically similar places influence emotional patterns in recovery journeys.
+
+**Key Innovation**: Goes beyond GPS coordinates to consider categorical, linguistic, and cultural dimensions of location similarity.
+
+---
+
+## Module Location
+
+```
+DREAMS/location_proximity/
+├── __init__.py
+├── location_extractor.py          # Extract GPS from images
+├── proximity_calculator.py        # Multi-dimensional proximity
+├── emotion_location_mapper.py     # Emotion-location patterns
+├── semantic_clustering.py         # Cluster similar places
+├── demo.py                        # Demonstration script
+├── test_proximity.py              # Test suite
+├── requirements.txt               # Dependencies
+├── README.md                      # Module documentation
+└── RESEARCH.md                    # Research foundation
+```
+
+---
+
+## Quick Demo
+
+```bash
+cd location_proximity
+pip install -r requirements.txt
+python demo.py
+```
+
+**Output**:
+```
+DEMO 1: Multi-Dimensional Proximity Calculation
+================================================================
+St. Mary's Church ↔ Holy Trinity Church : 0.850
+Alaska Native Medical Center ↔ Providence Hospital : 0.725
+
+✓ Notice: Two churches have high proximity despite different locations
+✓ Notice: Two hospitals cluster together semantically
+```
+
+---
+
+## Key Features
+
+### 1. Multi-Dimensional Proximity
+Calculates location similarity using:
+- **Geographic**: Physical distance (Haversine)
+- **Categorical**: Place type (church ↔ church)
+- **Linguistic**: Language context
+- **Cultural**: Shared cultural tags
+
+### 2. Emotion-Location Mapping
+- Track emotional patterns at specific locations
+- Identify "emotional hotspots" (places with consistent emotions)
+- Compare emotions across place categories
+- Temporal emotion trends at locations
+
+### 3. Semantic Clustering
+- Group semantically similar places
+- Analyze emotional patterns within clusters
+- Discover cross-location patterns
+- DBSCAN-based clustering (no predefined cluster count)
+
+---
+
+## Research Questions Addressed
+
+1. **Do semantically similar places evoke similar emotions?**
+   - Compare two different churches vs. church and hospital
+
+2. **Is categorical proximity more predictive than geographic proximity?**
+   - Correlation analysis between proximity dimensions and emotions
+
+3. **Do certain place types consistently associate with specific emotions?**
+   - Statistical analysis across place categories
+
+4. **How do place-emotion associations evolve during recovery?**
+   - Temporal analysis of location patterns
+
+---
+
+## Example Use Cases
+
+### Use Case 1: Categorical Analysis
+**Question**: Do all churches evoke positive emotions, or just specific ones?
+
+```python
+from location_proximity.emotion_location_mapper import EmotionLocationMapper
+
+mapper = EmotionLocationMapper()
+# Add data...
+
+# Compare specific church vs. all churches
+church_a_profile = mapper.get_location_sentiment_profile("church_a")
+all_churches = mapper.compare_place_types()["church"]
+```
+
+### Use Case 2: Cross-Location Patterns
+**Question**: Do Portuguese restaurants evoke similar emotions despite different locations?
+
+```python
+from location_proximity.semantic_clustering import find_similar_place_patterns
+
+patterns = find_similar_place_patterns(
+    places=portuguese_restaurants,
+    emotion_mapper=mapper,
+    proximity_threshold=0.6
+)
+```
+
+### Use Case 3: Recovery Journey Mapping
+**Question**: How does a person's emotional relationship with healthcare facilities change over time?
+
+```python
+hospitals = [p for p in places if p['type'] == 'hospital']
+for hospital in hospitals:
+    trend = mapper.temporal_emotion_trend(hospital['id'])
+    # Analyze trend...
+```
+
+---
+
+## Integration with DREAMS
+
+### Extend Post Schema
+```python
+# Add to dreamsApp/app/ingestion/routes.py
+from location_proximity.location_extractor import extract_location_from_image
+
+location = extract_location_from_image(image_path)
+if location:
+    post_doc['location'] = {
+        'lat': location['lat'],
+        'lon': location['lon']
+    }
+```
+
+### Add Dashboard Route
+```python
+# Add to dreamsApp/app/dashboard/main.py
+@bp.route('/location_analysis/<user_id>')
+def location_analysis(user_id):
+    # Use EmotionLocationMapper to analyze patterns
+    # Render visualization
+```
+
+---
+
+## Metrics & Validation
+
+### Clustering Quality
+- Silhouette score
+- Davies-Bouldin index
+
+### Emotion Prediction
+- Accuracy of predicting emotion from place type
+- Precision/Recall for hotspot identification
+
+### Statistical Significance
+- Chi-square tests for sentiment distributions
+- ANOVA across place types
+- Effect size calculations
+
+---
+
+## Research Contribution
+
+**Novel Contribution**: First formalization of multi-dimensional location proximity for emotion analysis in recovery journeys.
+
+**Potential Publications**:
+1. "Beyond GPS: Multi-Dimensional Location Proximity in Emotional Recovery Analysis"
+2. "Semantic Place Similarity and Emotional Patterns in Digitized Memories"
+3. "Affective Geography of Recovery: A Computational Approach"
+
+---
+
+## Dependencies
+
+```
+Pillow>=10.0.0          # Image EXIF extraction
+numpy>=1.24.0           # Numerical computations
+scikit-learn>=1.3.0     # Clustering algorithms
+```
+
+---
+
+## Testing
+
+```bash
+cd location_proximity
+pytest test_proximity.py -v
+```
+
+**Test Coverage**:
+- Geographic distance calculation
+- Proximity metrics (all dimensions)
+- Emotion-location mapping
+- Clustering functionality
+- Edge cases and error handling
+
+---
+
+## Future Enhancements
+
+### Phase 1 (Current)
+- [x] Multi-dimensional proximity calculation
+- [x] Emotion-location mapping
+- [x] Semantic clustering
+- [x] Demo and tests
+
+### Phase 2 (Next)
+- [ ] Google Places API integration
+- [ ] Automated place type detection
+- [ ] Interactive map visualization (Folium)
+- [ ] Real-time clustering
+
+### Phase 3 (Future)
+- [ ] Image-based place recognition (CNN)
+- [ ] Temporal-spatial modeling
+- [ ] Cross-user analysis
+- [ ] Causal inference methods
+
+---
+
+## Contributing
+
+This module was developed as part of GSoC 2026 project:
+> "Understanding proximity in locations and emotions through digitized memories"
+
+**Mentors**: Jihye Kwon, Pradeeban Kathiravelu  
+**Institution**: University of Alaska Fairbanks
+
+Contributions welcome! See [location_proximity/README.md](location_proximity/README.md) for details.
+
+---
+
+## Contact
+
+- **Project**: https://github.com/KathiraveluLab/DREAMS
+- **Discussions**: https://github.com/KathiraveluLab/DREAMS/discussions
+- **Mentors**: jkwon2@alaska.edu, pkathiravelu@alaska.edu
+
+---
+
+## License
+
+Same as DREAMS project (see [LICENSE](LICENSE))
+
+---
+
+**Status**: ✅ Ready for integration and testing  
+**Version**: 0.1.0  
+**Last Updated**: 2024

README.md

@@ -4,33 +4,57 @@ Digitization for Recovery: Exploring Arts with Mining for Societal well-being.
 
 DREAMS is an extension of the Beehive project, focused on exploring time and ordering across photo memories to better understand personal recovery journeys. The goal is to build tools that help track and analyze visual narratives over time using data mining and intelligent processing.
 
-## 🔨 Current Progress
+## Current Progress
 
-- ✅ Set up core infrastructure using Flask and Hugging Face models.
-- ✅ Implemented a basic **Caption Sentiment Analysis API** to classify emotional tone in user-submitted captions.
-- 🔄 Integrating this API into Beehive to capture sentiment when users upload photos.
-- 🔬 Exploring time-based data structuring and narrative analysis features.
+- Set up core infrastructure using Flask and Hugging Face models.
+- Implemented a basic **Caption Sentiment Analysis API** to classify emotional tone in user-submitted captions.
+- Integrating this API into Beehive to capture sentiment when users upload photos.
+- Exploring time-based data structuring and narrative analysis features.
 
-### 📁 [View the API Module](./dreamsApp/README.md)
+### [View the API Module](./dreamsApp/README.md)
 
-## 📦 Repositories
+## Repositories
 
 - Beehive: [github.com/KathiraveluLab/beehive](https://github.com/KathiraveluLab/Beehive)
 - DREAMS: [github.com/KathiraveluLab/DREAMS](https://github.com/KathiraveluLab/DREAMS)
 
 
-## 📁 Repository Structure
+## Repository Structure
+
+```text
+DREAMS/
+├── dreamsApp/                  # Main application package
+│   ├── app/                    # Flask app package (app factory + blueprints)
+│   │   ├── __init__.py         # create_app() factory
+│   │   ├── config.py           # App configuration
+│   │   ├── models.py           # Database models
+│   │   ├── auth.py             # Authentication routes
+│   │   │
+│   │   ├── ingestion/          # Image ingestion & processing
+│   │   │   ├── __init__.py
+│   │   │   └── routes.py
+│   │   │
+│   │   ├── dashboard/          # Dashboard & analytics views
+│   │   │   ├── __init__.py
+│   │   │   └── main.py
+│   │   │
+│   │   └── utils/              # Core ML / NLP utilities
+│   │       ├── sentiment.py    # Caption sentiment analysis
+│   │       ├── keywords.py     # Keyword extraction
+│   │       ├── clustering.py   # Keyword clustering (HDBSCAN)
+│   │       └── llms.py         # LLM (Gemini) integration
+│   │
+│   └── docs/                   # Project documentation
+│
+├── data_integrity/             # Data validation utilities
+├── location_proximity/         # Location-based analysis (future)
+├── dream-integration/          # Integration & experimental code
+├── tests/                      # Unit and integration tests
+│
+├── requirements.txt            # Python dependencies
+├── pytest.ini                  # Pytest configuration
+└── README.md                   # Project documentation
 
-    DREAMS/
-    ├── dreamsApp/
-    │   ├── __init__.py                #        App factory
-    │   ├── captionSentiments.py       # API logic and model loading
-    |   ├── README.md
-    ├──tests/
-    |  ├──test_sentiment.py
-    ├──pytest.ini
-    ├──README.md
-    ├──requirements.txt
 
 ## Installation and Setup
 
@@ -50,7 +74,7 @@ pip install -r requirements.txt
 pytest
 
 # 5. Start the Flask server in debug mode
-flask --app dreamsApp run --debug
+flask --app "dreamsApp.app:create_app()" run --debug
 ```
 
 More coming soon!