-**Last Updated**: 2026-02-03
+**Last Updated**: 2026-02-12
Made with โค๏ธ by the Discogsography community
diff --git a/docs/extractor-consistency-fixes.md b/docs/extractor-consistency-fixes.md
deleted file mode 100644
index 286ff06..0000000
--- a/docs/extractor-consistency-fixes.md
+++ /dev/null
@@ -1,306 +0,0 @@
-# Extractor Consistency Fixes
-
-## Summary
-
-This document describes the changes made to ensure both `pyextractor` and `rustextractor` operate identically with respect to state marker tracking.
-
-## Issues Fixed
-
-### 1. State Marker Tracking Improvements
-
-#### Problem: Incorrect Metrics in State Marker
-
-The state marker JSON was showing incorrect values:
-- `bytes_downloaded`: 0 (should show actual bytes)
-- `messages_published`: 0 in publishing_phase (should aggregate from files)
-- `batches_sent`: 0 (should show actual batch count)
-
-#### Root Causes
-
-1. **Per-file tracking missing**: Download phase only tracked aggregate bytes, not per-file
-2. **Publishing metrics not aggregated**: Publishing phase metrics were tracked separately instead of being calculated from file progress
-3. **Batch tracking incomplete**: Batches weren't being counted properly
-
-#### Solution
-
-**Enhanced State Marker Structure:**
-
-1. **Added `FileDownloadStatus`** to track downloads per file:
- ```python
- @dataclass
- class FileDownloadStatus:
- status: PhaseStatus
- bytes_downloaded: int
- started_at: datetime | None
- completed_at: datetime | None
- ```
-
-2. **Added `downloads_by_file`** to `DownloadPhase`:
- - Tracks each file's download status and size
- - `bytes_downloaded` is now calculated as sum of all files
-
-3. **Added `batches_sent`** to `FileProcessingStatus`:
- - Tracks batches sent per file
- - Publishing phase aggregates from all files
-
-4. **Auto-calculation in `update_file_progress()`**:
- ```python
- def update_file_progress(self, filename: str, records: int, messages: int, batches: int = 0):
- # Update file-specific progress
- # ...
-
- # Auto-calculate publishing phase from all files
- self.publishing_phase.messages_published = sum(
- status.messages_published for status in self.processing_phase.progress_by_file.values()
- )
- self.publishing_phase.batches_sent = sum(
- status.batches_sent for status in self.processing_phase.progress_by_file.values()
- )
- ```
-
-### 2. Extractor Behavioral Consistency
-
-#### Problems Found
-
-1. **Missing `start_file_download()` in Python**
- - Rust: Called before each download
- - Python: Not called at all
- - **Impact**: Missing download start timestamps in Python
-
-2. **Different cached file tracking timing**
- - Python: Tracked cached files BEFORE `start_download()`
- - Rust: Tracked cached files AFTER `start_download()`
- - **Impact**: Timeline ordering inconsistency
-
-3. **Reversed completion order**
- - Python: State marker โ Completion message
- - Rust: Completion message โ State marker
- - **Impact**: Race condition risk on process crash
-
-#### Solutions Applied
-
-**Python (`discogs.py`):**
-
-1. **Added `start_file_download()` before download** (line 406-407):
- ```python
- # Start tracking file download in state marker
- state_marker.start_file_download(filename)
- state_marker.save(marker_path)
- ```
-
-2. **Moved cached file tracking after `start_download()`** (lines 392-398):
- ```python
- # Start download phase tracking
- state_marker.start_download(total_files)
- state_marker.save(marker_path)
-
- # Track cached files (those with valid checksums that were skipped)
- for filename, checksum in checksums.items():
- file_path = output_path / filename
- if file_path.exists():
- file_size = file_path.stat().st_size
- state_marker.file_downloaded(filename, file_size)
- ```
-
-3. **Already correct**: State marker updated before completion message
-
-**Python (`extractor.py`):**
-
-1. **Added `batches_sent` counter** (line 120):
- ```python
- self.batches_sent: int = 0
- ```
-
-2. **Increment after batch flush** (line 804):
- ```python
- # Increment batches sent counter
- self.batches_sent += 1
- ```
-
-3. **Pass to `update_file_progress()`** (line 702):
- ```python
- self.state_marker.update_file_progress(
- self.input_file,
- self.total_count, # records
- self.total_count, # messages (one per record)
- self.batches_sent, # batches
- )
- ```
-
-**Rust (`downloader.rs`):**
-
-1. **Added `start_file_download()` before download** (lines 88-92):
- ```rust
- // Start tracking file download
- if let Some(ref mut marker) = self.state_marker {
- marker.start_file_download(filename);
- marker.save(marker_path).await.ok();
- }
- ```
-
-2. **Already correct**: Cached files tracked after `start_download()`
-
-**Rust (`extractor.rs`):**
-
-1. **Added batch tracking** (lines 339, 373, 383, 388):
- ```rust
- let mut total_batches = 0u64;
- // ...
- total_batches += 1;
- ```
-
-2. **Pass to `update_file_progress()`** (line 359):
- ```rust
- marker.update_file_progress(&file_name, total_records, total_records, total_batches);
- ```
-
-3. **Fixed completion order** (lines 299-319):
- ```rust
- // Mark file as completed in state marker FIRST (consistent with Python)
- {
- let mut marker = state_marker.lock().await;
- marker.complete_file_processing(file_name, total_count);
- marker.save(&marker_path).await?;
- }
-
- // Update state
- // ...
-
- // THEN send file completion message (consistent with Python)
- mq.send_file_complete(data_type, file_name, total_count).await?;
- ```
-
-## Verification
-
-### Test Results
-
-**Python Tests:**
-```bash
-uv run pytest tests/common/test_state_marker.py -v
-# Result: 22 passed in 1.89s
-```
-
-**Rust Tests:**
-```bash
-cd extractor/rustextractor && cargo test --lib state_marker
-# Result: 14 passed; 0 failed
-```
-
-### Expected State Marker Output
-
-With these fixes, the state marker JSON now correctly shows:
-
-```json
-{
- "download_phase": {
- "status": "completed",
- "bytes_downloaded": 12052065551, // โ
Correct total
- "downloads_by_file": {
- "discogs_20260201_artists.xml.gz": {
- "status": "completed",
- "bytes_downloaded": 480351382,
- "started_at": "2026-02-04T00:02:54Z",
- "completed_at": "2026-02-04T00:03:45Z"
- },
- "discogs_20260201_labels.xml.gz": {
- "status": "completed",
- "bytes_downloaded": 86848860,
- "started_at": "2026-02-04T00:03:45Z",
- "completed_at": "2026-02-04T00:04:01Z"
- }
- // ... other files ...
- }
- },
- "processing_phase": {
- "status": "in_progress",
- "records_extracted": 525000,
- "progress_by_file": {
- "discogs_20260201_artists.xml.gz": {
- "status": "in_progress",
- "records_extracted": 175000,
- "messages_published": 175000,
- "batches_sent": 1750 // โ
Now tracked
- },
- "discogs_20260201_labels.xml.gz": {
- "status": "in_progress",
- "records_extracted": 180000,
- "messages_published": 180000,
- "batches_sent": 1800 // โ
Now tracked
- }
- // ... other files ...
- }
- },
- "publishing_phase": {
- "status": "in_progress",
- "messages_published": 525000, // โ
Aggregated from files
- "batches_sent": 5250, // โ
Aggregated from files
- "last_amqp_heartbeat": "2026-02-04T00:23:18Z"
- }
-}
-```
-
-## Operational Consistency
-
-Both extractors now:
-
-1. **Download Phase:**
- - Call `start_download(total_files)` before any downloads
- - Call `start_file_download(filename)` before each file download
- - Call `file_downloaded(filename, bytes)` after each download (or for cached files)
- - Track per-file download status with timestamps
- - Calculate aggregate `bytes_downloaded` from all files
-
-2. **Processing Phase:**
- - Call `start_processing(total_files)` before processing
- - Call `start_file_processing(filename)` when starting each file
- - Call `update_file_progress(filename, records, messages, batches)` periodically (every 5000 records)
- - Track batch counts per file
- - Auto-calculate publishing phase metrics from file progress
- - Call `complete_file_processing(filename, total_records)` when done
-
-3. **Completion Order:**
- - Update state marker first
- - Send AMQP completion message second
- - Prevents state loss on crash between operations
-
-4. **Publishing Metrics:**
- - No direct calls to `update_publishing()` needed
- - Metrics automatically calculated from `progress_by_file`
- - Publishing phase status updated when any messages are published
-
-## Benefits
-
-1. **Accurate Tracking**: All metrics now reflect actual progress
-2. **Consistent Behavior**: Both implementations operate identically
-3. **Better Observability**: Per-file tracking provides detailed insights
-4. **Safer Operations**: Consistent completion order reduces race condition risk
-5. **Easier Debugging**: State marker provides complete audit trail
-6. **Resume Capability**: Per-file status enables fine-grained resume logic
-
-## Migration Notes
-
-No breaking changes for users. The enhanced state marker is backward-compatible:
-- Old state markers without `downloads_by_file` will be handled gracefully
-- Old state markers without `batches_sent` will default to 0
-- Publishing phase metrics will be recalculated on next update
-
-## Files Modified
-
-### Common
-- `common/state_marker.py` - Enhanced data structures and methods
-- `extractor/rustextractor/src/state_marker.rs` - Enhanced data structures and methods
-
-### Python Extractor
-- `extractor/pyextractor/discogs.py` - Download tracking fixes
-- `extractor/pyextractor/extractor.py` - Batch counting and progress updates
-
-### Rust Extractor
-- `extractor/rustextractor/src/downloader.rs` - Download tracking enhancements
-- `extractor/rustextractor/src/extractor.rs` - Batch counting and completion order fix
-
-### Tests
-- `tests/common/test_state_marker.py` - Updated for new method signatures
-- `extractor/rustextractor/src/state_marker.rs` (tests module) - Updated for new method signatures
-- `extractor/rustextractor/src/extractor.rs` (tests module) - Updated for new method signatures
-
-All tests pass in both implementations.
diff --git a/docs/logging-configuration.md b/docs/logging-configuration.md
deleted file mode 100644
index 4e00a8b..0000000
--- a/docs/logging-configuration.md
+++ /dev/null
@@ -1,270 +0,0 @@
-# Logging Configuration
-
-This document describes the unified logging configuration across all Discogsography services.
-
-## Overview
-
-All services in the Discogsography platform use a consistent logging pattern controlled by the `LOG_LEVEL` environment variable. This ensures uniform behavior across Python and Rust services.
-
-## Log Levels
-
-The following log levels are supported across all services:
-
-| Level | Description | Use Case |
-| ---------- | --------------------------------------------- | ------------------------------- |
-| `DEBUG` | Detailed diagnostic information | Development and troubleshooting |
-| `INFO` | General informational messages | Production (default) |
-| `WARNING` | Warning messages for potential issues | Production monitoring |
-| `ERROR` | Error messages for failures | Production alerts |
-| `CRITICAL` | Critical errors requiring immediate attention | Production alerts |
-
-**Default**: If `LOG_LEVEL` is not set, all services default to `INFO`.
-
-## Configuration
-
-### Environment Variable
-
-Set the `LOG_LEVEL` environment variable to control logging verbosity:
-
-```bash
-# Development with debug logging
-export LOG_LEVEL=DEBUG
-
-# Production with info logging (default)
-export LOG_LEVEL=INFO
-
-# Error-only logging
-export LOG_LEVEL=ERROR
-```
-
-### Docker Compose
-
-```yaml
-services:
- my-service:
- environment:
- LOG_LEVEL: INFO
-```
-
-### Docker Run
-
-```bash
-docker run -e LOG_LEVEL=DEBUG discogsography/service:latest
-```
-
-## Service-Specific Details
-
-### Python Services
-
-All Python services (extractor, graphinator, tableinator, dashboard, discovery) use the `setup_logging()` function from `common/config.py`:
-
-```python
-from common import setup_logging
-
-# Reads from LOG_LEVEL environment variable, defaults to INFO
-setup_logging("service_name", log_file=Path("/logs/service.log"))
-```
-
-**Features**:
-
-- Structured JSON logging with emoji indicators
-- Correlation IDs from contextvars
-- Service-specific context (name, environment)
-- File and console output
-- Automatic suppression of verbose third-party logs
-
-### Rust Extractor
-
-The Rust extractor uses Rust's `tracing` framework and maps Python log levels to Rust equivalents:
-
-| Python Level | Rust Level | Notes |
-| ------------ | ---------- | -------------------------------------- |
-| DEBUG | debug | Detailed diagnostic info |
-| INFO | info | General messages (default) |
-| WARNING | warn | Warning messages |
-| ERROR | error | Error messages |
-| CRITICAL | error | Mapped to error (Rust has no critical) |
-
-**Configuration**:
-
-```bash
-# Debug logging
-LOG_LEVEL=DEBUG cargo run
-
-# Production logging
-LOG_LEVEL=INFO cargo run
-```
-
-**Implementation** (main.rs):
-
-```rust
-let log_level = std::env::var("LOG_LEVEL")
- .unwrap_or_else(|_| "INFO".to_string())
- .to_uppercase();
-
-let rust_level = match log_level.as_str() {
- "DEBUG" => "debug",
- "INFO" => "info",
- "WARNING" | "WARN" => "warn",
- "ERROR" => "error",
- "CRITICAL" => "error",
- _ => "info"
-};
-```
-
-## Log Format
-
-### Python Services (JSON)
-
-```json
-{
- "timestamp": "2024-01-15T10:30:45.123456Z",
- "level": "info",
- "logger": "graphinator",
- "event": "๐ Service starting...",
- "service": "graphinator",
- "environment": "production",
- "lineno": 1210
-}
-```
-
-### Rust Extractor (JSON)
-
-```json
-{
- "timestamp": "2024-01-15T10:30:45.123456Z",
- "level": "INFO",
- "target": "rust_extractor",
- "message": "๐ Starting Rust-based Discogs data extractor with high performance",
- "line": 59
-}
-```
-
-## Emoji Indicators
-
-All services use consistent emoji indicators for visual clarity:
-
-- ๐ Service starting
-- โ
Successful operations
-- โ Errors and failures
-- โ ๏ธ Warnings
-- ๐ Progress updates
-- ๐ In-progress operations
-- ๐ Shutdown events
-- ๐ฅ Health checks
-- ๐ฅ Download operations
-- ๐ Completion milestones
-
-## Testing
-
-### Python
-
-```python
-import os
-import logging
-from common import setup_logging
-
-# Test with environment variable
-os.environ['LOG_LEVEL'] = 'DEBUG'
-setup_logging("test_service")
-assert logging.getLogger().level == logging.DEBUG
-
-# Test default behavior
-del os.environ['LOG_LEVEL']
-setup_logging("test_service")
-assert logging.getLogger().level == logging.INFO
-```
-
-### Rust
-
-```rust
-// Tests in src/config.rs verify environment variable handling
-#[test]
-fn test_log_level_from_env() {
- std::env::set_var("LOG_LEVEL", "DEBUG");
- // Configuration should use DEBUG level
- std::env::remove_var("LOG_LEVEL");
-}
-```
-
-## Troubleshooting
-
-### Service not respecting LOG_LEVEL
-
-1. **Check environment variable is set**:
-
- ```bash
- docker exec
printenv LOG_LEVEL
- ```
-
-1. **Verify service startup logs**:
-
- ```bash
- docker logs | head -20
- ```
-
-1. **Check for explicit level parameter** (Python):
-
- ```python
- # This overrides LOG_LEVEL
- setup_logging("service", level="WARNING")
- ```
-
-### Too much logging in production
-
-1. Set `LOG_LEVEL=WARNING` or `LOG_LEVEL=ERROR`
-1. Check third-party library log levels are suppressed (handled automatically)
-
-### Not enough logging for debugging
-
-1. Set `LOG_LEVEL=DEBUG`
-1. Restart the service
-1. Monitor logs: `docker logs -f `
-
-## Best Practices
-
-1. **Development**: Use `DEBUG` for detailed diagnostic information
-1. **Staging**: Use `INFO` to match production behavior
-1. **Production**: Use `INFO` or `WARNING` depending on volume
-1. **Incident Response**: Temporarily set to `DEBUG` for affected services
-1. **Case Insensitive**: LOG_LEVEL values are case-insensitive (`debug` == `DEBUG`)
-1. **Container Logs**: All logs go to stdout/stderr for container orchestration
-1. **File Logs**: Python services also write to `/logs/.log` inside containers
-
-## Migration Notes
-
-### From RUST_LOG (Rust Extractor)
-
-**Old**:
-
-```yaml
-environment:
- RUST_LOG: rust_extractor=info,lapin=warn
-```
-
-**New**:
-
-```yaml
-environment:
- LOG_LEVEL: INFO
-```
-
-### From Verbose Flag (Rust Extractor)
-
-**Old**:
-
-```bash
-cargo run --verbose
-```
-
-**New**:
-
-```bash
-LOG_LEVEL=DEBUG cargo run
-```
-
-## See Also
-
-- [Logging Guide](logging-guide.md) - Detailed logging best practices
-- [Emoji Guide](emoji-guide.md) - Complete emoji reference
-- [Troubleshooting](troubleshooting.md) - Common issues and solutions
diff --git a/docs/logging-guide.md b/docs/logging-guide.md
index bc30ee8..08ce7f0 100644
--- a/docs/logging-guide.md
+++ b/docs/logging-guide.md
@@ -1,11 +1,16 @@
-# ๐ Logging Conventions Guide
+# ๐ Logging Guide
-> Consistent, emoji-enhanced logging patterns across all Discogsography services
+
-## Overview
+**Consistent, emoji-enhanced logging patterns and configuration across all Discogsography services**
-Discogsography uses a standardized logging approach with emoji prefixes for visual clarity and quick issue
-identification. This guide ensures consistent logging across all services.
+[๐ Back to Main](../README.md) | [๐ Documentation Index](README.md) | [๐ Emoji Guide](emoji-guide.md)
+
+
+
+## ๐ Overview
+
+Discogsography uses a standardized logging approach with emoji prefixes for visual clarity and quick issue identification. All services use consistent logging controlled by the `LOG_LEVEL` environment variable.
### Logging Flow
@@ -40,6 +45,139 @@ flowchart LR
style File fill:#fff3e0,stroke:#ff9800,stroke-width:2px
```
+## โ๏ธ Configuration
+
+### Environment Variable
+
+All services in the Discogsography platform use the `LOG_LEVEL` environment variable for consistent logging control.
+
+#### Supported Log Levels
+
+| Level | Description | Use Case |
+| ---------- | --------------------------------------------- | ------------------------------- |
+| `DEBUG` | Detailed diagnostic information | Development and troubleshooting |
+| `INFO` | General informational messages | Production (default) |
+| `WARNING` | Warning messages for potential issues | Production monitoring |
+| `ERROR` | Error messages for failures | Production alerts |
+| `CRITICAL` | Critical errors requiring immediate attention | Production alerts |
+
+**Default**: If `LOG_LEVEL` is not set, all services default to `INFO`.
+
+#### Setting Log Level
+
+```bash
+# Development with debug logging
+export LOG_LEVEL=DEBUG
+
+# Production with info logging (default)
+export LOG_LEVEL=INFO
+
+# Error-only logging
+export LOG_LEVEL=ERROR
+```
+
+#### Docker Compose
+
+```yaml
+services:
+ my-service:
+ environment:
+ LOG_LEVEL: INFO
+```
+
+#### Docker Run
+
+```bash
+docker run -e LOG_LEVEL=DEBUG discogsography/service:latest
+```
+
+### Service-Specific Implementation
+
+#### Python Services
+
+All Python services (extractor, graphinator, tableinator, dashboard, discovery) use the `setup_logging()` function from `common/config.py`:
+
+```python
+from common import setup_logging
+
+# Reads from LOG_LEVEL environment variable, defaults to INFO
+setup_logging("service_name", log_file=Path("/logs/service.log"))
+```
+
+**Features**:
+- Structured JSON logging with emoji indicators
+- Correlation IDs from contextvars
+- Service-specific context (name, environment)
+- File and console output
+- Automatic suppression of verbose third-party logs
+
+#### Rust Extractor
+
+The Rust extractor uses Rust's `tracing` framework and maps Python log levels to Rust equivalents:
+
+| Python Level | Rust Level | Notes |
+| ------------ | ---------- | -------------------------------------- |
+| DEBUG | debug | Detailed diagnostic info |
+| INFO | info | General messages (default) |
+| WARNING | warn | Warning messages |
+| ERROR | error | Error messages |
+| CRITICAL | error | Mapped to error (Rust has no critical) |
+
+**Configuration**:
+
+```bash
+# Debug logging
+LOG_LEVEL=DEBUG cargo run
+
+# Production logging
+LOG_LEVEL=INFO cargo run
+```
+
+**Implementation** (main.rs):
+
+```rust
+let log_level = std::env::var("LOG_LEVEL")
+ .unwrap_or_else(|_| "INFO".to_string())
+ .to_uppercase();
+
+let rust_level = match log_level.as_str() {
+ "DEBUG" => "debug",
+ "INFO" => "info",
+ "WARNING" | "WARN" => "warn",
+ "ERROR" => "error",
+ "CRITICAL" => "error",
+ _ => "info"
+};
+```
+
+## ๐ Log Format
+
+### Python Services (JSON)
+
+```json
+{
+ "timestamp": "2024-01-15T10:30:45.123456Z",
+ "level": "info",
+ "logger": "graphinator",
+ "event": "๐ Service starting...",
+ "service": "graphinator",
+ "environment": "production",
+ "lineno": 1210
+}
+```
+
+### Rust Extractor (JSON)
+
+```json
+{
+ "timestamp": "2024-01-15T10:30:45.123456Z",
+ "level": "INFO",
+ "target": "rust_extractor",
+ "message": "๐ Starting Rust-based Discogs data extractor with high performance",
+ "line": 59
+}
+```
+
## ๐จ Emoji Pattern
**Format**: `logger.{level}("{emoji} {message}")`
@@ -266,30 +404,7 @@ except Exception as e:
raise
```
-## ๐ง Configuration
-
-### LOG_LEVEL Environment Variable
-
-All Discogsography services use the `LOG_LEVEL` environment variable for consistent log level control:
-
-```bash
-# Set log level for all services
-export LOG_LEVEL=DEBUG # Detailed diagnostic information
-export LOG_LEVEL=INFO # General informational messages (default)
-export LOG_LEVEL=WARNING # Warning conditions only
-export LOG_LEVEL=ERROR # Error conditions only
-export LOG_LEVEL=CRITICAL # Critical conditions only
-
-# Run service with specific log level
-LOG_LEVEL=DEBUG docker-compose up discovery
-
-# Check what DEBUG logging shows
-docker-compose logs discovery | grep "๐" # Neo4j queries
-docker-compose logs discovery | grep "๐" # Progress updates
-docker-compose logs discovery | grep "๐" # Processing operations
-```
-
-For complete details on log level configuration across all services, see [Logging Configuration](logging-configuration.md).
+## ๐ง Advanced Configuration
### Basic Setup
@@ -333,6 +448,40 @@ class JSONFormatter(logging.Formatter):
)
```
+## ๐ Troubleshooting
+
+### Service not respecting LOG_LEVEL
+
+1. **Check environment variable is set**:
+
+ ```bash
+ docker exec printenv LOG_LEVEL
+ ```
+
+2. **Verify service startup logs**:
+
+ ```bash
+ docker logs | head -20
+ ```
+
+3. **Check for explicit level parameter** (Python):
+
+ ```python
+ # This overrides LOG_LEVEL
+ setup_logging("service", level="WARNING")
+ ```
+
+### Too much logging in production
+
+1. Set `LOG_LEVEL=WARNING` or `LOG_LEVEL=ERROR`
+2. Check third-party library log levels are suppressed (handled automatically)
+
+### Not enough logging for debugging
+
+1. Set `LOG_LEVEL=DEBUG`
+2. Restart the service
+3. Monitor logs: `docker logs -f `
+
## ๐ Log Analysis
### Finding Errors
@@ -377,6 +526,48 @@ logger.info("Starting service ๐")
logger.info("๐ ๐ง Starting and configuring")
```
+## ๐ Migration Notes
+
+### From RUST_LOG (Rust Extractor)
+
+**Old**:
+
+```yaml
+environment:
+ RUST_LOG: rust_extractor=info,lapin=warn
+```
+
+**New**:
+
+```yaml
+environment:
+ LOG_LEVEL: INFO
+```
+
+### From Verbose Flag (Rust Extractor)
+
+**Old**:
+
+```bash
+cargo run --verbose
+```
+
+**New**:
+
+```bash
+LOG_LEVEL=DEBUG cargo run
+```
+
+## ๐ Best Practices Summary
+
+1. **Development**: Use `DEBUG` for detailed diagnostic information
+2. **Staging**: Use `INFO` to match production behavior
+3. **Production**: Use `INFO` or `WARNING` depending on volume
+4. **Incident Response**: Temporarily set to `DEBUG` for affected services
+5. **Case Insensitive**: LOG_LEVEL values are case-insensitive (`debug` == `DEBUG`)
+6. **Container Logs**: All logs go to stdout/stderr for container orchestration
+7. **File Logs**: Python services also write to `/logs/.log` inside containers
+
## ๐ Quick Reference Card
```
@@ -390,6 +581,19 @@ Services: ๐ฐ RabbitMQ | ๐ Neo4j | ๐ PostgreSQL | ๐ Network
> **๐ก Tip**: Set `LOG_LEVEL=DEBUG` to see detailed diagnostic logs including database queries marked with ๐
-______________________________________________________________________
+## ๐ Related Documentation
+
+- [Emoji Guide](emoji-guide.md) - Complete emoji reference for the project
+- [Monitoring Guide](monitoring.md) - Real-time monitoring and debugging
+- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
+- [Configuration Guide](configuration.md) - Complete environment variable reference
+
+---
+
+
+
+**Last Updated**: 2026-02-12
Remember: Consistent logging makes debugging easier and operations smoother! ๐ฏ
+
+
diff --git a/docs/mypy-precommit-differences.md b/docs/mypy-precommit-differences.md
deleted file mode 100644
index 15ad51c..0000000
--- a/docs/mypy-precommit-differences.md
+++ /dev/null
@@ -1,249 +0,0 @@
-# MyPy Pre-commit vs Standalone Differences
-
-## Problem Summary
-
-Running `uv run mypy .` produces **505 errors** while `uv run pre-commit run mypy --all-files` produces **0 errors**.
-
-## Root Causes
-
-### 1. **File Scope Difference** (Primary)
-
-**Pre-commit configuration:**
-```yaml
-files: ^(common|dashboard|discovery|extractor|graphinator|tableinator)/.*\.py$
-```
-
-- Pre-commit **ONLY** checks source files in these directories
-- **EXCLUDES** all `tests/` directory files
-- When checking only source directories: **21 errors**
-- When checking tests too: **505 errors** (484 in tests alone)
-
-### 2. **Missing Dependencies in Pre-commit Environment** (Critical)
-
-Pre-commit creates an **isolated virtual environment** for mypy with limited dependencies.
-
-**Dependencies in pre-commit mypy environment:**
-```
-aio-pika==9.5.8
-dict_hash==1.3.7
-mypy==1.19.1
-neo4j==6.1.0
-orjson==3.11.7
-psycopg==3.3.2
-types-tqdm==4.67.3.20260205
-types-xmltodict==1.0.1.20260113
-```
-
-**Critical MISSING dependencies:**
-- โ `structlog` - Used extensively in `common/config.py`
-- โ `fastapi` - Used in all API modules
-- โ `pydantic` - Data validation models
-- โ `prometheus_client` - Metrics in dashboard
-- โ `numpy`, `scipy`, `sklearn` - ML/data processing
-- โ `pandas`, `plotly` - Analytics/visualization
-- โ `sqlalchemy` - Database ORM
-- โ `redis`, `httpx` - Networking/caching
-- โ `sentence_transformers`, `transformers`, `onnxruntime` - ML models
-- โ `slowapi`, `networkx` - API rate limiting, graph algorithms
-
-**Impact:** When mypy can't import a module, it treats it as `Any` type, which:
-- Suppresses type errors in that module
-- Allows invalid type combinations to pass
-- Creates false confidence in type safety
-
-### 3. **Error Distribution**
-
-```
-Total errors: 505
-โโโ Tests: ~484 errors (95.8%)
-โ โโโ Missing return type annotations
-โ โโโ Unused type: ignore comments
-โ โโโ Non-overlapping equality checks
-โ โโโ Indexing and operator issues
-โโโ Source: 21 errors (4.2%)
- โโโ common/config.py: 3 errors (structlog types)
- โโโ dashboard/dashboard.py: 18 errors (prometheus types + unused ignores)
-```
-
-## Why Pre-commit Passes Despite Source Errors
-
-Even though there are 21 errors in source files, pre-commit reports **0 errors** because:
-
-1. **Missing `structlog`** โ `common/config.py` errors suppressed
-2. **Missing `prometheus_client`** โ `dashboard/dashboard.py` type errors suppressed
-3. Without these dependencies, mypy can't perform proper type checking
-
-## Final Solution โ
-
-**Use a local pre-commit hook that runs mypy from the project's uv environment.**
-
-This eliminates all configuration duplication and ensures complete consistency:
-
-```yaml
-# .pre-commit-config.yaml
-- repo: local
- hooks:
- - id: mypy
- name: mypy
- entry: uv run mypy
- language: system
- types: [python]
- pass_filenames: false
- args: ["."]
-```
-
-**Benefits:**
-- โ
No `additional_dependencies` duplication
-- โ
Uses exact project dependencies from `pyproject.toml`
-- โ
Respects all mypy configuration in `pyproject.toml`
-- โ
Identical results between `uv run mypy .` and pre-commit
-- โ
Faster hook execution (no separate environment)
-- โ
Single source of truth for all configuration
-
-**Configuration in `pyproject.toml`:**
-```toml
-[tool.mypy]
-python_version = "3.13"
-# ... all your mypy settings ...
-exclude = "^tests/" # Excludes tests from type checking
-```
-
-**Result:** Both standalone and pre-commit now show **identical output**:
-```
-Found 21 errors in 2 files (checked 65 source files)
-```
-
----
-
-## Alternative Solutions (Not Recommended)
-
-### Option 1: Add All Dependencies to Pre-commit
-
-Update `.pre-commit-config.yaml`:
-
-```yaml
-- repo: https://github.com/pre-commit/mirrors-mypy
- rev: a66e98df7b4aeeb3724184b332785976d062b92e # frozen: v1.19.1
- hooks:
- - id: mypy
- files: ^(common|dashboard|discovery|extractor|graphinator|tableinator)/.*\.py$
- additional_dependencies:
- # Type stubs
- - types-tqdm
- - types-xmltodict
- # Direct dependencies
- - orjson
- - dict-hash
- - aio-pika
- - neo4j
- - psycopg[binary]
- # ADDED: Critical dependencies for type checking
- - structlog
- - fastapi
- - pydantic
- - prometheus-client
- - numpy
- - scipy
- - scikit-learn
- - pandas
- - plotly
- - sqlalchemy
- - redis
- - httpx
- - slowapi
- - networkx
- # ML dependencies (consider adding if type errors persist)
- - sentence-transformers
- - transformers
- - onnxruntime
-```
-
-**Pros:**
-- Accurate type checking in pre-commit
-- Catches errors before commit
-- Consistent with standalone mypy
-
-**Cons:**
-- Slower pre-commit hook installation
-- Larger cache size
-
-### Option 2: Use Project Environment for Pre-commit
-
-Create a local pre-commit hook that uses the project's uv environment:
-
-```yaml
-- repo: local
- hooks:
- - id: mypy
- name: mypy
- entry: uv run mypy
- language: system
- types: [python]
- files: ^(common|dashboard|discovery|extractor|graphinator|tableinator)/.*\.py$
- pass_filenames: false
-```
-
-**Pros:**
-- Uses exact project dependencies
-- No dependency duplication
-- Faster for developers with environment already set up
-
-**Cons:**
-- Requires `uv` and environment to be set up
-- May not work in CI without setup
-
-### Option 3: Include Tests in Pre-commit
-
-Extend file pattern to include tests:
-
-```yaml
-files: ^(common|dashboard|discovery|extractor|graphinator|tableinator|tests)/.*\.py$
-```
-
-**Note:** This will reveal the 484+ test errors that currently aren't checked.
-
-### Option 4: Separate Test Type Checking
-
-Keep pre-commit for source files, run full mypy in CI:
-
-```yaml
-# .github/workflows/ci.yml
-- name: ๐ Type check with mypy
- run: uv run mypy . # Checks everything including tests
-```
-
-## Immediate Action Items
-
-1. **Fix source file errors (21 errors):**
- - `common/config.py`: Add type ignores or fix structlog typing
- - `dashboard/dashboard.py`: Remove unused type: ignore comments
-
-2. **Choose solution:**
- - Recommended: **Option 1** (add dependencies) for accurate pre-commit checking
- - Alternative: **Option 2** (local hook) for faster development
-
-3. **Fix test errors (484 errors):**
- - Add return type annotations to test functions
- - Remove unused type: ignore comments
- - Fix enum comparison issues
-
-## Testing the Fix
-
-After implementing a solution:
-
-```bash
-# Clean pre-commit cache
-uv run pre-commit clean
-
-# Re-run pre-commit
-uv run pre-commit run mypy --all-files
-
-# Should now match standalone mypy on source files
-uv run mypy common dashboard discovery extractor graphinator tableinator
-```
-
-## References
-
-- Pre-commit config: `.pre-commit-config.yaml`
-- MyPy config: `pyproject.toml` `[tool.mypy]` section
-- Pre-commit environment: `~/.cache/pre-commit/repoe3sr52ed/`
diff --git a/docs/s3-listing-fix.md b/docs/s3-listing-fix.md
deleted file mode 100644
index 2d4db0b..0000000
--- a/docs/s3-listing-fix.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# S3 Listing Fix for Discogs Data Downloads
-
-## Problem
-
-The Discogs S3 bucket (`discogs-data-dumps`) is configured to allow public downloads of specific files (using `s3:GetObject`), but it **does not** allow public listing of the bucket contents (using `s3:ListBucket`).
-
-When pyextractor and rustextractor attempted to use `list_objects_v2` to discover available data files, they would receive an `AccessDenied` error because the bucket policy explicitly denies the `ListBucket` action for anonymous users.
-
-## Solution
-
-Instead of trying to list and access the S3 bucket directly, both extractors now:
-1. **Scrape the file list** from the Discogs website at https://data.discogs.com/
-2. **Download files through the Discogs website proxy** instead of direct S3 access
-
-### How It Works
-
-1. **Fetch Main Page**: Get the list of available year directories (e.g., 2026/, 2025/, etc.)
-2. **Fetch Recent Years**: Check the last 2 years for available data files
-3. **Parse File Information**: Extract file names and version IDs from the HTML
-4. **Download via Proxy**: Use the Discogs website download URLs (e.g., `https://data.discogs.com/?download=data%2F2026%2Fdiscogs_20260101_artists.xml.gz`)
-
-### Benefits
-
-- โ
Avoids `AccessDenied` errors from S3 listing and GetObject attempts
-- โ
Uses only publicly available information from the Discogs website
-- โ
Downloads through Discogs' official website proxy (same as browser downloads)
-- โ
No AWS credentials or S3 client needed
-- โ
Simpler, more reliable approach
-
-## Changes Made
-
-### Python Extractor (`extractor/pyextractor/discogs.py`)
-
-1. **Removed S3 dependencies**: Removed `boto3` from imports and dependencies
-2. **Added HTTP downloads**: Created `_download_file_from_discogs()` function to download files via Discogs website proxy
-3. **Added web scraping**: Created `_scrape_file_list_from_discogs()` function to fetch file list from website
-4. **Updated download logic**: Modified `download_discogs_data()` to use HTTP downloads instead of S3
-5. **Updated dependencies**: Added `requests>=2.31.0`, removed `boto3>=1.34.0` from `pyproject.toml`
-
-### Rust Extractor (`extractor/rustextractor/src/downloader.rs`)
-
-1. **Removed S3 dependencies**: Removed `aws-config` and `aws-sdk-s3` from Cargo.toml
-2. **Removed S3 client**: Removed `S3Client` from `Downloader` struct
-3. **Added HTTP downloads**: Updated `download_file()` method to download files via Discogs website proxy using reqwest
-4. **Added web scraping**: Created `scrape_file_list_from_discogs()` method to fetch file list from website
-5. **Updated file listing**: Modified `list_s3_files()` to use the scraper instead of S3 listing
-6. **Updated dependencies**: Added `regex` and `urlencoding`, removed AWS SDK dependencies from `Cargo.toml`
-7. **Updated tests**: Fixed test comments and warnings, all 18 tests passing
-
-## Testing
-
-The Python implementation was tested and successfully retrieves the file list:
-
-```
-โ
Successfully scraped file list!
-๐ Found 13 unique versions
-
-๐
Latest versions:
- - 20260101: 5 files (4 data + 1 checksum)
- - 20251201: 5 files (4 data + 1 checksum)
- - 20251101: 5 files (4 data + 1 checksum)
-```
-
-## Technical Details
-
-### HTML Structure
-
-The Discogs data page uses a simple HTML structure:
-
-- **Main page**: Lists year directories as `?prefix=data%2F{YEAR}%2F`
-- **Year page**: Lists files as `?download=data%2F{YEAR}%2Fdiscogs_{YYYYMMDD}_{type}.xml.gz`
-
-### File Naming Pattern
-
-Files follow a predictable pattern:
-- `discogs_{YYYYMMDD}_artists.xml.gz`
-- `discogs_{YYYYMMDD}_labels.xml.gz`
-- `discogs_{YYYYMMDD}_masters.xml.gz`
-- `discogs_{YYYYMMDD}_releases.xml.gz`
-- `discogs_{YYYYMMDD}_CHECKSUM.txt`
-
-A complete monthly dump consists of exactly 5 files (4 data files + 1 checksum).
-
-### Download URLs
-
-Files are downloaded using the Discogs website proxy:
-- **Format**: `https://data.discogs.com/?download={url_encoded_s3_key}`
-- **Example**: `https://data.discogs.com/?download=data%2F2026%2Fdiscogs_20260101_artists.xml.gz`
-
-This approach:
-- Works exactly like browser downloads
-- Requires no authentication
-- Is officially supported by Discogs
-- Handles rate limiting and CDN caching
-
-## Future Considerations
-
-### Website Structure Changes
-
-If Discogs changes their website structure, the scraping logic may need to be updated. However, since this is a static HTML page with a simple structure, it's unlikely to change frequently.
-
-### Alternative Approaches
-
-1. **If Discogs enables public S3 access**: Could revert to S3 API for better performance
-2. **If Discogs provides an API**: Could use official API endpoints instead of scraping
-3. **If download proxy changes**: May need to update URL construction logic
-
-### Performance Optimization
-
-The current implementation:
-- Checks only the last 2 years for efficiency
-- Uses streaming downloads for large files
-- Maintains checksum validation for data integrity
-
-Future optimizations could include:
-- Parallel downloads for multiple files
-- Resume capability for interrupted downloads
-- Better progress reporting with actual file sizes
diff --git a/explore/Dockerfile b/explore/Dockerfile
new file mode 100644
index 0000000..9a75318
--- /dev/null
+++ b/explore/Dockerfile
@@ -0,0 +1,130 @@
+# syntax=docker/dockerfile:1
+
+# Build arguments
+ARG PYTHON_VERSION=3.13
+ARG UID=1000
+ARG GID=1000
+
+FROM python:${PYTHON_VERSION}-slim AS builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:0.10.1 /uv /bin/uv
+
+# Set environment for build
+ENV UV_SYSTEM_PYTHON=1 \
+ UV_CACHE_DIR=/tmp/.cache/uv \
+ UV_LINK_MODE=copy \
+ PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /app
+
+# Copy dependency files first for better caching
+COPY pyproject.toml uv.lock README.md ./
+COPY common/pyproject.toml ./common/
+COPY explore/pyproject.toml ./explore/
+
+# Install dependencies and clean up
+# hadolint ignore=SC2015
+RUN --mount=type=cache,target=/tmp/.cache/uv \
+ uv sync --frozen --no-dev --extra explore && \
+ # Clean up cache and test files
+ find /app/.venv -type f -name "*.pyc" -delete && \
+ find /app/.venv -type f -name "*.pyo" -delete && \
+ find /app/.venv -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true && \
+ find /app/.venv -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true && \
+ find /app/.venv -type d -name "tests" -exec rm -rf {} + 2>/dev/null || true && \
+ # Remove type stubs and docs
+ find /app/.venv -type d -name "*.dist-info" -exec rm -rf {}/tests {} + 2>/dev/null || true && \
+ find /app/.venv -name "py.typed" -delete 2>/dev/null || true && \
+ # Strip compiled extensions
+ find /app/.venv -name "*.so" -exec strip --strip-unneeded {} \; 2>/dev/null || true
+
+# Copy source files
+COPY common/ ./common/
+COPY explore/ ./explore/
+
+# Final stage
+FROM python:${PYTHON_VERSION}-slim
+
+# Build arguments for labels
+ARG BUILD_DATE
+ARG BUILD_VERSION
+ARG VCS_REF
+ARG UID=1000
+ARG GID=1000
+
+# OCI Image Spec Annotations
+# https://github.com/opencontainers/image-spec/blob/main/annotations.md
+LABEL org.opencontainers.image.title="Discogsography Explore" \
+ org.opencontainers.image.description="Interactive graph exploration and trends visualization for Discogsography with Neo4j-powered queries." \
+ org.opencontainers.image.authors="Robert Wlodarczyk " \
+ org.opencontainers.image.url="https://github.com/SimplicityGuy/discogsography" \
+ org.opencontainers.image.documentation="https://github.com/SimplicityGuy/discogsography/blob/main/README.md" \
+ org.opencontainers.image.source="https://github.com/SimplicityGuy/discogsography" \
+ org.opencontainers.image.vendor="SimplicityGuy" \
+ org.opencontainers.image.licenses="MIT" \
+ org.opencontainers.image.version="${BUILD_VERSION:-0.1.0}" \
+ org.opencontainers.image.revision="${VCS_REF}" \
+ org.opencontainers.image.created="${BUILD_DATE}" \
+ org.opencontainers.image.base.name="docker.io/library/python:${PYTHON_VERSION}-slim" \
+ com.discogsography.service="explore" \
+ com.discogsography.dependencies="fastapi,uvicorn,neo4j" \
+ com.discogsography.python.version="${PYTHON_VERSION}"
+
+# Install minimal runtime dependencies
+# hadolint ignore=DL3008
+RUN apt-get update && \
+ apt-get upgrade -y && \
+ apt-get install -y --no-install-recommends \
+ curl \
+ && \
+ apt-get clean && \
+ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+# Create user and directories with configurable UID/GID
+RUN groupadd -r -g ${GID} discogsography && \
+ useradd -r -l -u ${UID} -g discogsography -m -s /bin/bash discogsography && \
+ mkdir -p /tmp /app /logs && \
+ chown -R discogsography:discogsography /tmp /app /logs
+
+WORKDIR /app
+
+# Copy only necessary files from builder
+COPY --from=builder --chown=discogsography:discogsography /app/.venv /app/.venv
+COPY --from=builder --chown=discogsography:discogsography /app/common /app/common
+COPY --from=builder --chown=discogsography:discogsography /app/explore /app/explore
+
+# UV not needed at runtime
+
+# Create startup script
+# hadolint ignore=SC2016
+RUN printf '#!/bin/sh\nset -e\nsleep "${STARTUP_DELAY:-0}"\nexec /app/.venv/bin/python -m explore.explore "$@"\n' > /app/start.sh && \
+ chmod +x /app/start.sh
+
+# Health check on health port 8007
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+ CMD curl -f http://localhost:8007/health || exit 1
+
+USER discogsography:discogsography
+
+# Environment variables
+ENV HOME=/home/discogsography \
+ PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_SYSTEM_PYTHON=1 \
+ UV_NO_CACHE=1 \
+ PATH="/app/.venv/bin:$PATH" \
+ NEO4J_ADDRESS="" \
+ NEO4J_USERNAME="" \
+ NEO4J_PASSWORD=""
+
+EXPOSE 8006 8007
+
+# Declare volume for logs
+VOLUME ["/logs"]
+
+# Security: This container should be run with:
+# docker run --cap-drop=ALL --security-opt=no-new-privileges:true ...
+
+CMD ["/app/start.sh"]
diff --git a/explore/README.md b/explore/README.md
new file mode 100644
index 0000000..7bf4302
--- /dev/null
+++ b/explore/README.md
@@ -0,0 +1,153 @@
+# Explore Service
+
+๐ **Interactive Graph Exploration and Trends Visualization**
+
+The Explore service provides a lightweight, fast-loading interface for navigating the Discogs knowledge graph and visualizing release trends over time.
+
+## ๐ Features
+
+### ๐ Interactive Graph Explorer
+
+- **Force-Directed Graph**: D3.js-powered visualization of entity relationships
+- **Category Expansion**: Click category nodes to load releases, artists, labels, aliases, and styles
+- **Info Panel**: View detailed node information on click
+- **Search Types**: Explore by Artist, Genre, or Label
+- **Fast Autocomplete**: Debounced search with Neo4j fulltext indexes
+
+### ๐ Trends Visualization
+
+- **Time-Series Charts**: Plotly.js charts showing release counts over time
+- **Multi-Entity Support**: View trends for artists, genres, or labels
+- **Interactive Tooltips**: Hover for year-by-year details
+
+## ๐ Quick Start
+
+### Using Docker (Recommended)
+
+```bash
+# Start all services including explore
+docker-compose up -d
+
+# Access the Explore UI
+open http://localhost:8006
+```
+
+### Local Development
+
+```bash
+# Install dependencies
+uv sync --extra explore
+
+# Set environment variables
+export NEO4J_ADDRESS="bolt://localhost:7687"
+export NEO4J_USERNAME="neo4j"
+export NEO4J_PASSWORD="password"
+
+# Start the explore service
+just explore
+```
+
+## ๐๏ธ Architecture
+
+```mermaid
+graph TD
+ UI["๐ Browser
HTML + D3.js + Plotly.js"]
+ API["๐ Explore API
FastAPI :8006"]
+ HEALTH["๐ฅ Health Server
:8007"]
+ NEO4J[("๐ Neo4j
Graph Database")]
+
+ UI -->|HTTP| API
+ API -->|Bolt| NEO4J
+ HEALTH -.->|Status| API
+
+ style UI fill:#e3f2fd,stroke:#0d47a1,stroke-width:2px
+ style API fill:#fff9c4,stroke:#f57c00,stroke-width:2px
+ style HEALTH fill:#fce4ec,stroke:#880e4f,stroke-width:2px
+ style NEO4J fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
+```
+
+### Dependencies
+
+The Explore service connects to **Neo4j only** - no RabbitMQ, PostgreSQL, or Redis needed. This makes it fast to start and simple to deploy.
+
+## ๐ก API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check (also available on port 8007) |
+| GET | `/api/autocomplete` | Search entities with autocomplete |
+| GET | `/api/explore` | Get center node with category counts |
+| GET | `/api/expand` | Expand a category node to get children |
+| GET | `/api/node/{node_id}` | Get full details for a node |
+| GET | `/api/trends` | Get time-series release counts |
+
+### Autocomplete
+
+```
+GET /api/autocomplete?q=radio&type=artist&limit=10
+```
+
+Parameters:
+- `q` (required, min 2 chars): Search query
+- `type` (default: "artist"): Entity type - artist, genre, or label
+- `limit` (default: 10, max: 50): Maximum results
+
+### Explore
+
+```
+GET /api/explore?name=Radiohead&type=artist
+```
+
+Returns a center node and artificial category nodes with counts (e.g., Releases: 42, Labels: 5, Aliases: 2).
+
+### Expand
+
+```
+GET /api/expand?node_id=Radiohead&type=artist&category=releases&limit=50
+```
+
+Expands a category node to return its children. Valid categories per type:
+- **artist**: releases, labels, aliases
+- **genre**: artists, labels, styles
+- **label**: releases, artists
+
+### Node Details
+
+```
+GET /api/node/1?type=artist
+```
+
+Returns full details for a specific node (artist, release, label, genre, or style).
+
+### Trends
+
+```
+GET /api/trends?name=Radiohead&type=artist
+```
+
+Returns year-by-year release counts for the given entity.
+
+## โ๏ธ Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NEO4J_ADDRESS` | Neo4j bolt connection URL | Required |
+| `NEO4J_USERNAME` | Neo4j username | Required |
+| `NEO4J_PASSWORD` | Neo4j password | Required |
+
+## ๐ Ports
+
+| Port | Purpose |
+|------|---------|
+| 8006 | Main service (API + static files) |
+| 8007 | Health check endpoint |
+
+## ๐งช Testing
+
+```bash
+# Run unit and API tests
+uv run pytest tests/explore/ -m 'not e2e' -v
+
+# Run E2E tests (requires Playwright)
+uv run pytest tests/explore/test_explore_ui.py -v
+```
diff --git a/explore/__init__.py b/explore/__init__.py
new file mode 100644
index 0000000..5bb7008
--- /dev/null
+++ b/explore/__init__.py
@@ -0,0 +1 @@
+"""Explore service for interactive graph exploration of Discogs data."""
diff --git a/explore/explore.py b/explore/explore.py
new file mode 100755
index 0000000..75d4a39
--- /dev/null
+++ b/explore/explore.py
@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""Explore service for interactive graph exploration of Discogs data."""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Query
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import ORJSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from common import (
+ AsyncResilientNeo4jDriver,
+ ExploreConfig,
+ HealthServer,
+ setup_logging,
+)
+from explore.neo4j_indexes import create_all_indexes
+from explore.neo4j_queries import (
+ AUTOCOMPLETE_DISPATCH,
+ DETAILS_DISPATCH,
+ EXPAND_DISPATCH,
+ EXPLORE_DISPATCH,
+ TRENDS_DISPATCH,
+)
+
+
+logger = logging.getLogger(__name__)
+
+# Module-level state
+neo4j_driver: AsyncResilientNeo4jDriver | None = None
+config: ExploreConfig | None = None
+
+
+def get_health_data() -> dict[str, Any]:
+ """Return health check data."""
+ return {
+ "status": "healthy" if neo4j_driver else "starting",
+ "service": "explore",
+ "timestamp": datetime.now(UTC).isoformat(),
+ }
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
+ """Manage application lifecycle."""
+ # fmt: off
+ print("โโโโโโโ โโโโโโโโโโโ โโโโโโโ โโโโโโโ โโโโโโโ โโโโโโโโ ")
+ print("โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโ ")
+ print("โโโ โโโโโโโโโโโโโโโโโ โโโ โโโโโโ โโโโโโโโโโโโ ")
+ print("โโโ โโโโโโโโโโโโโโโโโ โโโ โโโโโโ โโโโโโโโโโโ ")
+ print("โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ ")
+ print("โโโโโโโ โโโโโโโโโโโ โโโโโโโ โโโโโโโ โโโโโโโ โโโโโโโโ ")
+ print(" ")
+ print("โโโโโโโโโโโ โโโโโโโโโโ โโโ โโโโโโโ โโโโโโโ โโโโโโโโ ")
+ print("โโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ ")
+ print("โโโโโโ โโโโโโ โโโโโโโโโโโ โโโ โโโโโโโโโโโโโโโโโ ")
+ print("โโโโโโ โโโโโโ โโโโโโโ โโโ โโโ โโโโโโโโโโโโโโโโโ ")
+ print("โโโโโโโโโโโโ โโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโ ")
+ print("โโโโโโโโโโโ โโโโโโ โโโโโโโโ โโโโโโโ โโโ โโโโโโโโโโโ ")
+ print()
+ # fmt: on
+
+ logger.info("๐ Starting Explore service...")
+
+ global neo4j_driver, config
+ config = ExploreConfig.from_env()
+
+ # Start health server on separate port
+ health_server = HealthServer(8007, get_health_data)
+ health_server.start_background()
+
+ # Initialize Neo4j driver
+ neo4j_driver = AsyncResilientNeo4jDriver(
+ uri=config.neo4j_address,
+ auth=(config.neo4j_username, config.neo4j_password),
+ max_retries=5,
+ encrypted=False,
+ )
+ logger.info("๐ Connected to Neo4j with resilient driver")
+
+ # Create indexes
+ await create_all_indexes(config.neo4j_address, config.neo4j_username, config.neo4j_password)
+
+ logger.info("โ
Explore service ready")
+ yield
+
+ # Shutdown
+ if neo4j_driver:
+ await neo4j_driver.close()
+ health_server.stop()
+ logger.info("โ
Explore service shutdown complete")
+
+
+app = FastAPI(
+ title="Discogsography Explore",
+ version="0.1.0",
+ default_response_class=ORJSONResponse,
+ lifespan=lifespan,
+)
+
+app.add_middleware(
+ CORSMiddleware,
+ allow_origins=["*"],
+ allow_credentials=True,
+ allow_methods=["*"],
+ allow_headers=["*"],
+)
+
+
+# --- Autocomplete cache ---
+
+_autocomplete_cache: dict[tuple[str, str, int], list[dict[str, Any]]] = {}
+_AUTOCOMPLETE_CACHE_MAX = 512
+
+
+def _get_cache_key(query: str, entity_type: str, limit: int) -> tuple[str, str, int]:
+ return (query.lower().strip(), entity_type, limit)
+
+
+# --- API Endpoints ---
+
+
+@app.get("/health")
+async def health_check() -> ORJSONResponse:
+ """Health check endpoint."""
+ return ORJSONResponse(content=get_health_data())
+
+
+@app.get("/api/autocomplete")
+async def autocomplete(
+ q: str = Query(..., min_length=2, description="Search query"),
+ type: str = Query("artist", description="Entity type: artist, genre, label"),
+ limit: int = Query(10, ge=1, le=50, description="Max results"),
+) -> ORJSONResponse:
+ """Autocomplete search for entities."""
+ if not neo4j_driver:
+ return ORJSONResponse(content={"error": "Service not ready"}, status_code=503)
+
+ entity_type = type.lower()
+ if entity_type not in AUTOCOMPLETE_DISPATCH:
+ return ORJSONResponse(content={"error": f"Invalid type: {type}. Must be artist, genre, or label"}, status_code=400)
+
+ # Check cache
+ cache_key = _get_cache_key(q, entity_type, limit)
+ if cache_key in _autocomplete_cache:
+ return ORJSONResponse(content={"results": _autocomplete_cache[cache_key]})
+
+ query_func = AUTOCOMPLETE_DISPATCH[entity_type]
+ results = await query_func(neo4j_driver, q, limit)
+
+ # Cache result (simple bounded cache)
+ if len(_autocomplete_cache) >= _AUTOCOMPLETE_CACHE_MAX:
+ # Remove oldest quarter of entries
+ keys_to_remove = list(_autocomplete_cache.keys())[: _AUTOCOMPLETE_CACHE_MAX // 4]
+ for k in keys_to_remove:
+ del _autocomplete_cache[k]
+ _autocomplete_cache[cache_key] = results
+
+ return ORJSONResponse(content={"results": results})
+
+
+@app.get("/api/explore")
+async def explore(
+ name: str = Query(..., description="Entity name to explore"),
+ type: str = Query("artist", description="Entity type: artist, genre, label"),
+) -> ORJSONResponse:
+ """Get center node with category counts for graph exploration."""
+ if not neo4j_driver:
+ return ORJSONResponse(content={"error": "Service not ready"}, status_code=503)
+
+ entity_type = type.lower()
+ if entity_type not in EXPLORE_DISPATCH:
+ return ORJSONResponse(content={"error": f"Invalid type: {type}. Must be artist, genre, or label"}, status_code=400)
+
+ query_func = EXPLORE_DISPATCH[entity_type]
+ result = await query_func(neo4j_driver, name)
+
+ if not result:
+ return ORJSONResponse(content={"error": f"{type.capitalize()} '{name}' not found"}, status_code=404)
+
+ # Build category nodes based on type
+ categories = _build_categories(entity_type, result)
+
+ return ORJSONResponse(
+ content={
+ "center": {"id": str(result["id"]), "name": result["name"], "type": entity_type},
+ "categories": categories,
+ }
+ )
+
+
+def _build_categories(entity_type: str, result: dict[str, Any]) -> list[dict[str, Any]]:
+ """Build artificial category nodes from explore result."""
+ categories = []
+
+ if entity_type == "artist":
+ categories = [
+ {"id": "cat-releases", "name": "Releases", "category": "releases", "count": result.get("release_count", 0)},
+ {"id": "cat-labels", "name": "Labels", "category": "labels", "count": result.get("label_count", 0)},
+ {"id": "cat-aliases", "name": "Aliases & Members", "category": "aliases", "count": result.get("alias_count", 0)},
+ ]
+ elif entity_type == "genre":
+ categories = [
+ {"id": "cat-artists", "name": "Artists", "category": "artists", "count": result.get("artist_count", 0)},
+ {"id": "cat-labels", "name": "Labels", "category": "labels", "count": result.get("label_count", 0)},
+ {"id": "cat-styles", "name": "Styles", "category": "styles", "count": result.get("style_count", 0)},
+ ]
+ elif entity_type == "label":
+ categories = [
+ {"id": "cat-releases", "name": "Releases", "category": "releases", "count": result.get("release_count", 0)},
+ {"id": "cat-artists", "name": "Artists", "category": "artists", "count": result.get("artist_count", 0)},
+ ]
+
+ return categories
+
+
+@app.get("/api/expand")
+async def expand(
+ node_id: str = Query(..., description="Parent entity name"),
+ type: str = Query(..., description="Parent entity type: artist, genre, label"),
+ category: str = Query(..., description="Category to expand: releases, labels, aliases, artists, styles"),
+ limit: int = Query(50, ge=1, le=200, description="Max results"),
+) -> ORJSONResponse:
+ """Expand a category node to get its children."""
+ if not neo4j_driver:
+ return ORJSONResponse(content={"error": "Service not ready"}, status_code=503)
+
+ entity_type = type.lower()
+ category_lower = category.lower()
+
+ if entity_type not in EXPAND_DISPATCH:
+ return ORJSONResponse(content={"error": f"Invalid type: {type}"}, status_code=400)
+
+ type_categories = EXPAND_DISPATCH[entity_type]
+ if category_lower not in type_categories:
+ valid = ", ".join(type_categories.keys())
+ return ORJSONResponse(content={"error": f"Invalid category '{category}' for type '{type}'. Valid: {valid}"}, status_code=400)
+
+ query_func = type_categories[category_lower]
+ results = await query_func(neo4j_driver, node_id, limit)
+
+ return ORJSONResponse(content={"children": results})
+
+
+@app.get("/api/node/{node_id}")
+async def get_node_details(
+ node_id: str,
+ type: str = Query("artist", description="Node type: artist, release, label, genre, style"),
+) -> ORJSONResponse:
+ """Get full details for a specific node."""
+ if not neo4j_driver:
+ return ORJSONResponse(content={"error": "Service not ready"}, status_code=503)
+
+ entity_type = type.lower()
+ if entity_type not in DETAILS_DISPATCH:
+ return ORJSONResponse(content={"error": f"Invalid type: {type}"}, status_code=400)
+
+ query_func = DETAILS_DISPATCH[entity_type]
+ result = await query_func(neo4j_driver, node_id)
+
+ if not result:
+ return ORJSONResponse(content={"error": f"{type.capitalize()} '{node_id}' not found"}, status_code=404)
+
+ return ORJSONResponse(content=result)
+
+
+@app.get("/api/trends")
+async def get_trends(
+ name: str = Query(..., description="Entity name"),
+ type: str = Query("artist", description="Entity type: artist, genre, label"),
+) -> ORJSONResponse:
+ """Get time-series release counts for an entity."""
+ if not neo4j_driver:
+ return ORJSONResponse(content={"error": "Service not ready"}, status_code=503)
+
+ entity_type = type.lower()
+ if entity_type not in TRENDS_DISPATCH:
+ return ORJSONResponse(content={"error": f"Invalid type: {type}. Must be artist, genre, or label"}, status_code=400)
+
+ query_func = TRENDS_DISPATCH[entity_type]
+ results = await query_func(neo4j_driver, name)
+
+ return ORJSONResponse(
+ content={
+ "name": name,
+ "type": entity_type,
+ "data": results,
+ }
+ )
+
+
+# Mount static files for the UI
+static_dir = Path(__file__).parent / "static"
+app.mount("/", StaticFiles(directory=str(static_dir), html=True), name="static")
+
+
+if __name__ == "__main__":
+ import uvicorn
+
+ setup_logging("explore", log_file=Path("/logs/explore.log"))
+
+ uvicorn.run(
+ "explore.explore:app",
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=8006,
+ reload=False,
+ log_level="info",
+ )
diff --git a/explore/neo4j_indexes.py b/explore/neo4j_indexes.py
new file mode 100644
index 0000000..e73f19a
--- /dev/null
+++ b/explore/neo4j_indexes.py
@@ -0,0 +1,169 @@
+"""Neo4j index management for Explore service.
+
+Creates indexes needed for autocomplete and graph exploration queries.
+Uses IF NOT EXISTS so indexes shared with other services are safe to re-declare.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from neo4j import AsyncDriver, AsyncGraphDatabase
+
+
+logger = logging.getLogger(__name__)
+
+
+INDEXES = [
+ # Full-text indexes for autocomplete
+ {
+ "name": "artist_name_fulltext",
+ "type": "fulltext",
+ "label": "Artist",
+ "properties": ["name"],
+ "description": "Full-text search on artist names",
+ },
+ {
+ "name": "release_title_fulltext",
+ "type": "fulltext",
+ "label": "Release",
+ "properties": ["title"],
+ "description": "Full-text search on release titles",
+ },
+ {
+ "name": "label_name_fulltext",
+ "type": "fulltext",
+ "label": "Label",
+ "properties": ["name"],
+ "description": "Full-text search on label names",
+ },
+ # Range indexes for lookups
+ {
+ "name": "artist_id_index",
+ "type": "range",
+ "label": "Artist",
+ "properties": ["id"],
+ "description": "Fast lookup by artist ID",
+ },
+ {
+ "name": "release_id_index",
+ "type": "range",
+ "label": "Release",
+ "properties": ["id"],
+ "description": "Fast lookup by release ID",
+ },
+ {
+ "name": "label_id_index",
+ "type": "range",
+ "label": "Label",
+ "properties": ["id"],
+ "description": "Fast lookup by label ID",
+ },
+ {
+ "name": "release_year_index",
+ "type": "range",
+ "label": "Release",
+ "properties": ["year"],
+ "description": "Range queries by release year",
+ },
+ {
+ "name": "genre_name_index",
+ "type": "range",
+ "label": "Genre",
+ "properties": ["name"],
+ "description": "Lookup by genre name",
+ },
+ {
+ "name": "style_name_index",
+ "type": "range",
+ "label": "Style",
+ "properties": ["name"],
+ "description": "Lookup by style name",
+ },
+]
+
+
+async def create_index(driver: AsyncDriver, index_def: dict[str, Any]) -> bool:
+ """Create a single index if it doesn't exist.
+
+ Args:
+ driver: Neo4j async driver
+ index_def: Index definition dict
+
+ Returns:
+ True if index was created or already exists, False on error
+ """
+ name = index_def["name"]
+ index_type = index_def["type"]
+ label = index_def["label"]
+ properties = index_def["properties"]
+
+ try:
+ async with driver.session() as session:
+ if index_type == "fulltext":
+ query = f"""
+ CREATE FULLTEXT INDEX {name} IF NOT EXISTS
+ FOR (n:{label})
+ ON EACH [{", ".join([f"n.{prop}" for prop in properties])}]
+ """
+ elif len(properties) == 1:
+ query = f"""
+ CREATE INDEX {name} IF NOT EXISTS
+ FOR (n:{label})
+ ON (n.{properties[0]})
+ """
+ else:
+ props = ", ".join([f"n.{prop}" for prop in properties])
+ query = f"""
+ CREATE INDEX {name} IF NOT EXISTS
+ FOR (n:{label})
+ ON ({props})
+ """
+
+ await session.run(query)
+ logger.info(f"โ
Created index: {name} ({index_def['description']})")
+ return True
+
+ except Exception as e:
+ logger.error(f"โ Failed to create index {name}: {e}")
+ return False
+
+
+async def create_all_indexes(neo4j_address: str, neo4j_username: str, neo4j_password: str) -> None:
+ """Create all defined indexes.
+
+ Args:
+ neo4j_address: Neo4j connection address (bolt://host:port)
+ neo4j_username: Neo4j username
+ neo4j_password: Neo4j password
+ """
+ logger.info("๐ Starting Neo4j index creation for Explore service...")
+
+ driver = AsyncGraphDatabase.driver(neo4j_address, auth=(neo4j_username, neo4j_password))
+
+ try:
+ success_count = 0
+ failure_count = 0
+
+ for index_def in INDEXES:
+ if await create_index(driver, index_def):
+ success_count += 1
+ else:
+ failure_count += 1
+
+ logger.info(f"โ
Index creation complete: {success_count} successful, {failure_count} failed (total: {len(INDEXES)})")
+
+ finally:
+ await driver.close()
+
+
+if __name__ == "__main__":
+ import os
+
+ logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+ neo4j_address = os.getenv("NEO4J_ADDRESS", "bolt://localhost:7687")
+ neo4j_username = os.getenv("NEO4J_USERNAME", "neo4j")
+ neo4j_password = os.getenv("NEO4J_PASSWORD", "password")
+
+ asyncio.run(create_all_indexes(neo4j_address, neo4j_username, neo4j_password))
diff --git a/explore/neo4j_queries.py b/explore/neo4j_queries.py
new file mode 100644
index 0000000..b9d5233
--- /dev/null
+++ b/explore/neo4j_queries.py
@@ -0,0 +1,411 @@
+"""Neo4j Cypher queries for Explore service.
+
+All database queries are defined here to keep the API layer thin.
+"""
+
+from functools import lru_cache
+from typing import Any
+
+from neo4j import AsyncDriver
+
+
+# --- Autocomplete ---
+
+
+async def autocomplete_artist(driver: AsyncDriver, query: str, limit: int = 10) -> list[dict[str, Any]]:
+ """Search artists by name using fulltext index."""
+ cypher = """
+ CALL db.index.fulltext.queryNodes('artist_name_fulltext', $query + '*')
+ YIELD node, score
+ RETURN node.id AS id, node.name AS name, score
+ ORDER BY score DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, parameters={"query": query, "limit": limit})
+ return [dict(record) async for record in result]
+
+
+async def autocomplete_label(driver: AsyncDriver, query: str, limit: int = 10) -> list[dict[str, Any]]:
+ """Search labels by name using fulltext index."""
+ cypher = """
+ CALL db.index.fulltext.queryNodes('label_name_fulltext', $query + '*')
+ YIELD node, score
+ RETURN node.id AS id, node.name AS name, score
+ ORDER BY score DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, parameters={"query": query, "limit": limit})
+ return [dict(record) async for record in result]
+
+
+async def autocomplete_genre(driver: AsyncDriver, query: str, limit: int = 10) -> list[dict[str, Any]]:
+ """Search genres by name prefix."""
+ cypher = """
+ MATCH (g:Genre)
+ WHERE toLower(g.name) STARTS WITH toLower($query)
+ RETURN g.name AS id, g.name AS name, 1.0 AS score
+ ORDER BY g.name
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, parameters={"query": query, "limit": limit})
+ return [dict(record) async for record in result]
+
+
+# --- Explore (center node + category nodes) ---
+
+
+async def explore_artist(driver: AsyncDriver, name: str) -> dict[str, Any] | None:
+ """Get artist center node with category counts."""
+ cypher = """
+ MATCH (a:Artist {name: $name})
+ OPTIONAL MATCH (a)-[:BY]->(r:Release)
+ WITH a, count(DISTINCT r) AS release_count
+ OPTIONAL MATCH (a)-[:BY]->(r2:Release)-[:ON]->(l:Label)
+ WITH a, release_count, count(DISTINCT l) AS label_count
+ OPTIONAL MATCH (a)-[:MEMBER_OF]->(g:Artist)
+ WITH a, release_count, label_count, count(DISTINCT g) AS alias_count
+ OPTIONAL MATCH (a2:Artist)-[:MEMBER_OF]->(a)
+ WITH a, release_count, label_count, alias_count + count(DISTINCT a2) AS alias_count
+ RETURN a.id AS id, a.name AS name,
+ release_count, label_count, alias_count
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=name)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+async def explore_genre(driver: AsyncDriver, name: str) -> dict[str, Any] | None:
+ """Get genre center node with category counts."""
+ cypher = """
+ MATCH (g:Genre {name: $name})
+ OPTIONAL MATCH (a:Artist)-[:IS]->(g)
+ WITH g, count(DISTINCT a) AS artist_count
+ OPTIONAL MATCH (a2:Artist)-[:IS]->(g), (a2)-[:BY]->(r:Release)-[:ON]->(l:Label)
+ WITH g, artist_count, count(DISTINCT l) AS label_count
+ OPTIONAL MATCH (a3:Artist)-[:IS]->(g), (a3)-[:IS]->(s:Style)
+ WITH g, artist_count, label_count, count(DISTINCT s) AS style_count
+ RETURN g.name AS id, g.name AS name,
+ artist_count, label_count, style_count
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=name)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+async def explore_label(driver: AsyncDriver, name: str) -> dict[str, Any] | None:
+ """Get label center node with category counts."""
+ cypher = """
+ MATCH (l:Label {name: $name})
+ OPTIONAL MATCH (r:Release)-[:ON]->(l)
+ WITH l, count(DISTINCT r) AS release_count
+ OPTIONAL MATCH (a:Artist)-[:BY]->(r2:Release)-[:ON]->(l)
+ WITH l, release_count, count(DISTINCT a) AS artist_count
+ RETURN l.id AS id, l.name AS name,
+ release_count, artist_count
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=name)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+# --- Expand (populate category children) ---
+
+
+async def expand_artist_releases(driver: AsyncDriver, artist_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get releases by an artist."""
+ cypher = """
+ MATCH (a:Artist {name: $name})-[:BY]->(r:Release)
+ RETURN r.id AS id, r.title AS name, 'release' AS type, r.year AS year
+ ORDER BY r.year DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=artist_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_artist_labels(driver: AsyncDriver, artist_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get labels associated with an artist via their releases."""
+ cypher = """
+ MATCH (a:Artist {name: $name})-[:BY]->(r:Release)-[:ON]->(l:Label)
+ RETURN DISTINCT l.id AS id, l.name AS name, 'label' AS type, count(r) AS release_count
+ ORDER BY release_count DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=artist_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_artist_aliases(driver: AsyncDriver, artist_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get aliases and group memberships for an artist."""
+ cypher = """
+ MATCH (a:Artist {name: $name})
+ OPTIONAL MATCH (a)-[:MEMBER_OF]->(g:Artist)
+ WITH a, collect(DISTINCT {id: g.id, name: g.name, type: 'artist'}) AS groups
+ OPTIONAL MATCH (m:Artist)-[:MEMBER_OF]->(a)
+ WITH groups, collect(DISTINCT {id: m.id, name: m.name, type: 'artist'}) AS members
+ UNWIND (groups + members) AS alias
+ RETURN DISTINCT alias.id AS id, alias.name AS name, alias.type AS type
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=artist_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_genre_artists(driver: AsyncDriver, genre_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get artists in a genre."""
+ cypher = """
+ MATCH (a:Artist)-[:IS]->(g:Genre {name: $name})
+ RETURN DISTINCT a.id AS id, a.name AS name, 'artist' AS type
+ ORDER BY a.name
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=genre_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_genre_labels(driver: AsyncDriver, genre_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get labels associated with a genre via artists and releases."""
+ cypher = """
+ MATCH (a:Artist)-[:IS]->(g:Genre {name: $name}),
+ (a)-[:BY]->(r:Release)-[:ON]->(l:Label)
+ RETURN DISTINCT l.id AS id, l.name AS name, 'label' AS type, count(DISTINCT r) AS release_count
+ ORDER BY release_count DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=genre_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_genre_styles(driver: AsyncDriver, genre_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get styles (subgenres) associated with a genre."""
+ cypher = """
+ MATCH (a:Artist)-[:IS]->(g:Genre {name: $name}),
+ (a)-[:IS]->(s:Style)
+ RETURN DISTINCT s.name AS id, s.name AS name, 'style' AS type, count(DISTINCT a) AS artist_count
+ ORDER BY artist_count DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=genre_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_label_releases(driver: AsyncDriver, label_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get releases on a label."""
+ cypher = """
+ MATCH (r:Release)-[:ON]->(l:Label {name: $name})
+ RETURN r.id AS id, r.title AS name, 'release' AS type, r.year AS year
+ ORDER BY r.year DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=label_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+async def expand_label_artists(driver: AsyncDriver, label_name: str, limit: int = 50) -> list[dict[str, Any]]:
+ """Get artists on a label."""
+ cypher = """
+ MATCH (a:Artist)-[:BY]->(r:Release)-[:ON]->(l:Label {name: $name})
+ RETURN DISTINCT a.id AS id, a.name AS name, 'artist' AS type, count(DISTINCT r) AS release_count
+ ORDER BY release_count DESC
+ LIMIT $limit
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=label_name, limit=limit)
+ return [dict(record) async for record in result]
+
+
+# --- Node Details ---
+
+
+async def get_artist_details(driver: AsyncDriver, node_id: str) -> dict[str, Any] | None:
+ """Get full details for an artist node."""
+ cypher = """
+ MATCH (a:Artist) WHERE a.id = $id OR a.name = $id
+ OPTIONAL MATCH (a)-[:IS]->(g:Genre)
+ WITH a, collect(DISTINCT g.name) AS genres
+ OPTIONAL MATCH (a)-[:IS]->(s:Style)
+ WITH a, genres, collect(DISTINCT s.name) AS styles
+ OPTIONAL MATCH (a)-[:BY]->(r:Release)
+ WITH a, genres, styles, count(DISTINCT r) AS release_count
+ OPTIONAL MATCH (a)-[:MEMBER_OF]->(grp:Artist)
+ WITH a, genres, styles, release_count, collect(DISTINCT grp.name) AS groups
+ RETURN a.id AS id, a.name AS name, genres, styles, release_count, groups
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, id=node_id)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+async def get_release_details(driver: AsyncDriver, node_id: str) -> dict[str, Any] | None:
+ """Get full details for a release node."""
+ cypher = """
+ MATCH (r:Release) WHERE r.id = $id OR r.title = $id
+ OPTIONAL MATCH (a:Artist)-[:BY]->(r)
+ WITH r, collect(DISTINCT a.name) AS artists
+ OPTIONAL MATCH (r)-[:ON]->(l:Label)
+ WITH r, artists, collect(DISTINCT l.name) AS labels
+ OPTIONAL MATCH (r)-[:HAS_GENRE]->(g:Genre)
+ WITH r, artists, labels, collect(DISTINCT g.name) AS genres
+ OPTIONAL MATCH (r)-[:HAS_STYLE]->(s:Style)
+ WITH r, artists, labels, genres, collect(DISTINCT s.name) AS styles
+ RETURN r.id AS id, r.title AS name, r.year AS year, r.country AS country,
+ artists, labels, genres, styles
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, id=node_id)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+async def get_label_details(driver: AsyncDriver, node_id: str) -> dict[str, Any] | None:
+ """Get full details for a label node."""
+ cypher = """
+ MATCH (l:Label) WHERE l.id = $id OR l.name = $id
+ OPTIONAL MATCH (r:Release)-[:ON]->(l)
+ WITH l, count(DISTINCT r) AS release_count
+ RETURN l.id AS id, l.name AS name, release_count
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, id=node_id)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+async def get_genre_details(driver: AsyncDriver, node_id: str) -> dict[str, Any] | None:
+ """Get full details for a genre node."""
+ cypher = """
+ MATCH (g:Genre {name: $id})
+ OPTIONAL MATCH (a:Artist)-[:IS]->(g)
+ WITH g, count(DISTINCT a) AS artist_count
+ RETURN g.name AS id, g.name AS name, artist_count
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, id=node_id)
+ record = await result.single()
+ if not record:
+ return None
+ return dict(record)
+
+
+# --- Trends (time-series) ---
+
+
+async def trends_artist(driver: AsyncDriver, name: str) -> list[dict[str, Any]]:
+ """Get release count by year for an artist."""
+ cypher = """
+ MATCH (a:Artist {name: $name})-[:BY]->(r:Release)
+ WHERE r.year IS NOT NULL AND r.year > 0
+ RETURN r.year AS year, count(r) AS count
+ ORDER BY r.year
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=name)
+ return [dict(record) async for record in result]
+
+
+async def trends_genre(driver: AsyncDriver, name: str) -> list[dict[str, Any]]:
+ """Get release count by year for a genre."""
+ cypher = """
+ MATCH (r:Release)-[:HAS_GENRE]->(g:Genre {name: $name})
+ WHERE r.year IS NOT NULL AND r.year > 0
+ RETURN r.year AS year, count(r) AS count
+ ORDER BY r.year
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=name)
+ return [dict(record) async for record in result]
+
+
+async def trends_label(driver: AsyncDriver, name: str) -> list[dict[str, Any]]:
+ """Get release count by year for a label."""
+ cypher = """
+ MATCH (r:Release)-[:ON]->(l:Label {name: $name})
+ WHERE r.year IS NOT NULL AND r.year > 0
+ RETURN r.year AS year, count(r) AS count
+ ORDER BY r.year
+ """
+ async with driver.session() as session:
+ result = await session.run(cypher, name=name)
+ return [dict(record) async for record in result]
+
+
+# --- Dispatch helpers ---
+
+# LRU cache for autocomplete results
+_autocomplete_cache_size = 256
+
+
+@lru_cache(maxsize=_autocomplete_cache_size)
+def _autocomplete_cache_key(query: str, entity_type: str, limit: int) -> tuple[str, str, int]:
+ """Create a hashable cache key for autocomplete (used by the caller for LRU)."""
+ return (query.lower(), entity_type, limit)
+
+
+EXPLORE_DISPATCH: dict[str, Any] = {
+ "artist": explore_artist,
+ "genre": explore_genre,
+ "label": explore_label,
+}
+
+AUTOCOMPLETE_DISPATCH: dict[str, Any] = {
+ "artist": autocomplete_artist,
+ "genre": autocomplete_genre,
+ "label": autocomplete_label,
+}
+
+EXPAND_DISPATCH: dict[str, dict[str, Any]] = {
+ "artist": {
+ "releases": expand_artist_releases,
+ "labels": expand_artist_labels,
+ "aliases": expand_artist_aliases,
+ },
+ "genre": {
+ "artists": expand_genre_artists,
+ "labels": expand_genre_labels,
+ "styles": expand_genre_styles,
+ },
+ "label": {
+ "releases": expand_label_releases,
+ "artists": expand_label_artists,
+ },
+}
+
+DETAILS_DISPATCH: dict[str, Any] = {
+ "artist": get_artist_details,
+ "release": get_release_details,
+ "label": get_label_details,
+ "genre": get_genre_details,
+ "style": get_genre_details,
+}
+
+TRENDS_DISPATCH: dict[str, Any] = {
+ "artist": trends_artist,
+ "genre": trends_genre,
+ "label": trends_label,
+}
diff --git a/explore/pyproject.toml b/explore/pyproject.toml
new file mode 100644
index 0000000..5cacba8
--- /dev/null
+++ b/explore/pyproject.toml
@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "discogsography-explore"
+version = "0.1.0"
+description = "Interactive graph exploration and trends visualization for Discogsography"
+authors = [{name = "Robert Wlodarczyk", email = "robert@simplicityguy.com"}]
+readme = "README.md"
+requires-python = ">=3.13"
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Developers",
+ "Operating System :: OS Independent",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.13",
+]
+license = {text = "MIT"}
+dependencies = [
+ "fastapi>=0.115.6",
+ "neo4j>=5.15.0",
+ "orjson>=3.9.0",
+ "pydantic>=2.10.5",
+ "python-multipart>=0.0.20",
+ "structlog>=24.0.0",
+ "uvicorn[standard]>=0.34.0",
+]
+
+[project.scripts]
+explore = "explore:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
diff --git a/explore/static/css/styles.css b/explore/static/css/styles.css
new file mode 100644
index 0000000..568a738
--- /dev/null
+++ b/explore/static/css/styles.css
@@ -0,0 +1,306 @@
+:root {
+ --bg-primary: #0a0e27;
+ --bg-secondary: #151934;
+ --bg-card: #1e2139;
+ --text-primary: #e4e6eb;
+ --text-secondary: #b0b3b8;
+ --accent-blue: #1877f2;
+ --accent-green: #42b883;
+ --accent-yellow: #f0db4f;
+ --accent-red: #e74c3c;
+ --border-color: #2d3051;
+ --node-artist: #1DB954;
+ --node-release: #FF6B6B;
+ --node-label: #6c757d;
+ --node-genre: #ffc107;
+ --node-category: #4A90D9;
+}
+
+body {
+ background-color: var(--bg-primary);
+ color: var(--text-primary);
+ overflow: hidden;
+ height: 100vh;
+}
+
+/* Navbar */
+.navbar {
+ z-index: 1000;
+}
+
+/* Search container */
+.search-container {
+ position: relative;
+ width: 400px;
+}
+
+.search-container .input-group {
+ width: 100%;
+}
+
+#searchInput {
+ background-color: var(--bg-card);
+ border-color: var(--border-color);
+ color: var(--text-primary);
+}
+
+#searchInput:focus {
+ background-color: var(--bg-secondary);
+ border-color: var(--accent-blue);
+ color: var(--text-primary);
+ box-shadow: 0 0 0 0.2rem rgba(24, 119, 242, 0.25);
+}
+
+#searchInput::placeholder {
+ color: var(--text-secondary);
+}
+
+/* Autocomplete dropdown */
+.autocomplete-dropdown {
+ display: none;
+ position: absolute;
+ top: 100%;
+ left: 0;
+ right: 0;
+ z-index: 1050;
+ background-color: var(--bg-card);
+ border: 1px solid var(--border-color);
+ border-top: none;
+ border-radius: 0 0 6px 6px;
+ max-height: 300px;
+ overflow-y: auto;
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+
+.autocomplete-dropdown.show {
+ display: block;
+}
+
+.autocomplete-item {
+ padding: 10px 14px;
+ cursor: pointer;
+ border-bottom: 1px solid var(--border-color);
+ transition: background-color 0.15s;
+}
+
+.autocomplete-item:last-child {
+ border-bottom: none;
+}
+
+.autocomplete-item:hover,
+.autocomplete-item.active {
+ background-color: var(--bg-secondary);
+}
+
+.autocomplete-item .name {
+ color: var(--text-primary);
+ font-weight: 500;
+}
+
+.autocomplete-item .score {
+ color: var(--text-secondary);
+ font-size: 12px;
+ float: right;
+}
+
+/* Main content */
+.main-content {
+ height: calc(100vh - 56px);
+ position: relative;
+}
+
+.pane {
+ display: none;
+ height: 100%;
+}
+
+.pane.active {
+ display: flex;
+}
+
+/* Graph container */
+.graph-container {
+ flex: 1;
+ position: relative;
+ overflow: hidden;
+}
+
+#graphSvg {
+ width: 100%;
+ height: 100%;
+ background-color: var(--bg-primary);
+}
+
+.graph-placeholder,
+.trends-placeholder {
+ position: absolute;
+ top: 50%;
+ left: 50%;
+ transform: translate(-50%, -50%);
+ text-align: center;
+}
+
+.graph-placeholder.hidden,
+.trends-placeholder.hidden {
+ display: none;
+}
+
+/* Graph legend */
+.graph-legend {
+ position: absolute;
+ bottom: 20px;
+ left: 20px;
+ background-color: rgba(30, 33, 57, 0.9);
+ border: 1px solid var(--border-color);
+ border-radius: 8px;
+ padding: 10px 14px;
+ font-size: 13px;
+}
+
+.legend-item {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ margin-bottom: 4px;
+}
+
+.legend-item:last-child {
+ margin-bottom: 0;
+}
+
+.legend-dot {
+ width: 12px;
+ height: 12px;
+ border-radius: 50%;
+ display: inline-block;
+}
+
+.legend-rect {
+ border-radius: 3px;
+}
+
+/* Info panel */
+.info-panel {
+ width: 0;
+ overflow: hidden;
+ background-color: var(--bg-secondary);
+ border-left: 1px solid var(--border-color);
+ transition: width 0.3s ease;
+ flex-shrink: 0;
+}
+
+.info-panel.open {
+ width: 350px;
+}
+
+.info-panel-header {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ padding: 16px;
+ border-bottom: 1px solid var(--border-color);
+}
+
+.info-panel-header h5 {
+ margin: 0;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+
+.info-panel-body {
+ padding: 16px;
+ overflow-y: auto;
+ height: calc(100% - 60px);
+}
+
+.detail-section {
+ margin-bottom: 16px;
+}
+
+.detail-section h6 {
+ color: var(--text-secondary);
+ font-size: 12px;
+ text-transform: uppercase;
+ margin-bottom: 6px;
+}
+
+.detail-tags {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 4px;
+}
+
+.detail-tag {
+ background-color: var(--bg-card);
+ border: 1px solid var(--border-color);
+ border-radius: 4px;
+ padding: 2px 8px;
+ font-size: 12px;
+ color: var(--text-primary);
+}
+
+.detail-stat {
+ display: flex;
+ justify-content: space-between;
+ padding: 6px 0;
+ border-bottom: 1px solid var(--border-color);
+ font-size: 14px;
+}
+
+.detail-stat:last-child {
+ border-bottom: none;
+}
+
+.detail-stat .label {
+ color: var(--text-secondary);
+}
+
+.detail-stat .value {
+ color: var(--accent-blue);
+ font-weight: 600;
+}
+
+/* Trends container */
+.trends-container {
+ width: 100%;
+ height: 100%;
+ position: relative;
+ padding: 20px;
+}
+
+#trendsChart {
+ width: 100%;
+ height: 100%;
+}
+
+/* D3 node styles */
+.node-label {
+ font-size: 11px;
+ fill: var(--text-primary);
+ pointer-events: none;
+ text-anchor: middle;
+ dominant-baseline: central;
+}
+
+.node-label-bg {
+ fill: rgba(10, 14, 39, 0.7);
+ rx: 3;
+ ry: 3;
+}
+
+.link {
+ stroke: var(--border-color);
+ stroke-opacity: 0.6;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+ .search-container {
+ width: 250px;
+ }
+
+ .info-panel.open {
+ width: 280px;
+ }
+}
diff --git a/explore/static/index.html b/explore/static/index.html
new file mode 100644
index 0000000..24430ee
--- /dev/null
+++ b/explore/static/index.html
@@ -0,0 +1,106 @@
+
+
+
+
+
+ Discogsography Explore
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Artist
+
Release
+
Label
+
Genre/Style
+
Category
+
+
+
+
Search for an artist, genre, or label to start exploring
+
+
+
+
+
+
+
Click a node to see details
+
+
+
+
+
+
+
+
+
+
+
Search for an entity to see release trends over time
+
+
+
+
Loading...
';
+ panel.classList.add('open');
+
+ const details = await window.apiClient.getNodeDetails(nodeId, type);
+ if (!details) {
+ body.innerHTML = 'No details available
';
+ return;
+ }
+
+ title.textContent = details.name || nodeId;
+ body.innerHTML = this._renderDetails(details, type);
+ }
+
+ _renderDetails(details, type) {
+ let html = '';
+
+ if (type === 'artist') {
+ html += this._detailStat('Releases', details.release_count || 0);
+ if (details.genres && details.genres.length) {
+ html += this._detailTags('Genres', details.genres);
+ }
+ if (details.styles && details.styles.length) {
+ html += this._detailTags('Styles', details.styles);
+ }
+ if (details.groups && details.groups.length) {
+ html += this._detailTags('Groups', details.groups);
+ }
+ } else if (type === 'release') {
+ if (details.year) html += this._detailStat('Year', details.year);
+ if (details.country) html += this._detailStat('Country', details.country);
+ if (details.artists && details.artists.length) {
+ html += this._detailTags('Artists', details.artists);
+ }
+ if (details.labels && details.labels.length) {
+ html += this._detailTags('Labels', details.labels);
+ }
+ if (details.genres && details.genres.length) {
+ html += this._detailTags('Genres', details.genres);
+ }
+ if (details.styles && details.styles.length) {
+ html += this._detailTags('Styles', details.styles);
+ }
+ } else if (type === 'label') {
+ html += this._detailStat('Releases', details.release_count || 0);
+ } else if (type === 'genre' || type === 'style') {
+ html += this._detailStat('Artists', details.artist_count || 0);
+ }
+
+ return html || 'No additional details
';
+ }
+
+ _detailStat(label, value) {
+ return `${label}${typeof value === 'number' ? value.toLocaleString() : value}
`;
+ }
+
+ _detailTags(label, tags) {
+ const tagsHtml = tags.map(t => `${this._escapeHtml(t)}`).join('');
+ return ``;
+ }
+
+ _escapeHtml(text) {
+ const div = document.createElement('div');
+ div.textContent = text;
+ return div.innerHTML;
+ }
+}
+
+// Initialize when DOM is ready
+document.addEventListener('DOMContentLoaded', () => {
+ window.exploreApp = new ExploreApp();
+});
diff --git a/explore/static/js/autocomplete.js b/explore/static/js/autocomplete.js
new file mode 100644
index 0000000..f4c35af
--- /dev/null
+++ b/explore/static/js/autocomplete.js
@@ -0,0 +1,135 @@
+/**
+ * Autocomplete handler with debouncing and keyboard navigation.
+ */
+class Autocomplete {
+ constructor() {
+ this.input = document.getElementById('searchInput');
+ this.dropdown = document.getElementById('autocompleteDropdown');
+ this.debounceTimer = null;
+ this.debounceMs = 300;
+ this.minChars = 2;
+ this.activeIndex = -1;
+ this.results = [];
+ this.onSelect = null;
+
+ this._bindEvents();
+ }
+
+ _bindEvents() {
+ this.input.addEventListener('input', () => this._onInput());
+ this.input.addEventListener('keydown', (e) => this._onKeydown(e));
+
+ // Close dropdown on outside click
+ document.addEventListener('click', (e) => {
+ if (!this.input.contains(e.target) && !this.dropdown.contains(e.target)) {
+ this.close();
+ }
+ });
+ }
+
+ _onInput() {
+ clearTimeout(this.debounceTimer);
+ const query = this.input.value.trim();
+
+ if (query.length < this.minChars) {
+ this.close();
+ return;
+ }
+
+ this.debounceTimer = setTimeout(() => this._search(query), this.debounceMs);
+ }
+
+ async _search(query) {
+ const type = window.exploreApp ? window.exploreApp.searchType : 'artist';
+ this.results = await window.apiClient.autocomplete(query, type);
+ this.activeIndex = -1;
+ this._render();
+ }
+
+ _render() {
+ if (this.results.length === 0) {
+ this.close();
+ return;
+ }
+
+ this.dropdown.innerHTML = this.results.map((item, index) => `
+
+ ${this._escapeHtml(item.name)}
+
+ `).join('');
+
+ // Bind click events
+ this.dropdown.querySelectorAll('.autocomplete-item').forEach(el => {
+ el.addEventListener('click', () => {
+ const idx = parseInt(el.dataset.index);
+ this._selectItem(idx);
+ });
+ });
+
+ this.dropdown.classList.add('show');
+ }
+
+ _onKeydown(e) {
+ if (!this.dropdown.classList.contains('show')) {
+ if (e.key === 'Enter') {
+ e.preventDefault();
+ const query = this.input.value.trim();
+ if (query && this.onSelect) {
+ this.onSelect(query);
+ }
+ }
+ return;
+ }
+
+ switch (e.key) {
+ case 'ArrowDown':
+ e.preventDefault();
+ this.activeIndex = Math.min(this.activeIndex + 1, this.results.length - 1);
+ this._render();
+ break;
+ case 'ArrowUp':
+ e.preventDefault();
+ this.activeIndex = Math.max(this.activeIndex - 1, -1);
+ this._render();
+ break;
+ case 'Enter':
+ e.preventDefault();
+ if (this.activeIndex >= 0) {
+ this._selectItem(this.activeIndex);
+ } else {
+ const query = this.input.value.trim();
+ if (query && this.onSelect) {
+ this.close();
+ this.onSelect(query);
+ }
+ }
+ break;
+ case 'Escape':
+ this.close();
+ break;
+ }
+ }
+
+ _selectItem(index) {
+ const item = this.results[index];
+ if (item) {
+ this.input.value = item.name;
+ this.close();
+ if (this.onSelect) {
+ this.onSelect(item.name);
+ }
+ }
+ }
+
+ close() {
+ this.dropdown.classList.remove('show');
+ this.activeIndex = -1;
+ }
+
+ _escapeHtml(text) {
+ const div = document.createElement('div');
+ div.textContent = text;
+ return div.innerHTML;
+ }
+}
diff --git a/explore/static/js/graph.js b/explore/static/js/graph.js
new file mode 100644
index 0000000..2e7a2d3
--- /dev/null
+++ b/explore/static/js/graph.js
@@ -0,0 +1,306 @@
+/**
+ * D3.js force-directed graph visualization.
+ */
+class GraphVisualization {
+ constructor(containerId) {
+ this.container = document.getElementById(containerId);
+ this.svg = d3.select('#graphSvg');
+ this.placeholder = document.getElementById('graphPlaceholder');
+
+ this.nodes = [];
+ this.links = [];
+ this.simulation = null;
+ this.g = null;
+ this.zoom = null;
+
+ // Track expanded categories
+ this.expandedCategories = new Set();
+
+ // Current center entity
+ this.centerName = null;
+ this.centerType = null;
+
+ // Callbacks
+ this.onNodeClick = null;
+
+ this._initSvg();
+ }
+
+ _initSvg() {
+ const width = this.container.clientWidth;
+ const height = this.container.clientHeight;
+
+ this.svg
+ .attr('width', width)
+ .attr('height', height);
+
+ // Zoom behavior
+ this.zoom = d3.zoom()
+ .scaleExtent([0.1, 4])
+ .on('zoom', (event) => {
+ this.g.attr('transform', event.transform);
+ });
+
+ this.svg.call(this.zoom);
+
+ // Main group for zoom/pan
+ this.g = this.svg.append('g');
+
+ // Arrow marker for links
+ this.svg.append('defs').append('marker')
+ .attr('id', 'arrowhead')
+ .attr('viewBox', '-0 -5 10 10')
+ .attr('refX', 20)
+ .attr('refY', 0)
+ .attr('orient', 'auto')
+ .attr('markerWidth', 6)
+ .attr('markerHeight', 6)
+ .append('path')
+ .attr('d', 'M 0,-5 L 10,0 L 0,5')
+ .attr('fill', '#2d3051');
+
+ // Handle resize
+ window.addEventListener('resize', () => this._onResize());
+ }
+
+ _onResize() {
+ const width = this.container.clientWidth;
+ const height = this.container.clientHeight;
+ this.svg.attr('width', width).attr('height', height);
+ if (this.simulation) {
+ this.simulation.force('center', d3.forceCenter(width / 2, height / 2));
+ this.simulation.alpha(0.3).restart();
+ }
+ }
+
+ _getNodeColor(node) {
+ if (node.isCategory) return 'var(--node-category)';
+ switch (node.type) {
+ case 'artist': return 'var(--node-artist)';
+ case 'release': return 'var(--node-release)';
+ case 'label': return 'var(--node-label)';
+ case 'genre':
+ case 'style': return 'var(--node-genre)';
+ default: return '#888';
+ }
+ }
+
+ _getNodeRadius(node) {
+ if (node.isCenter) return 28;
+ if (node.isCategory) return 22;
+ return 14;
+ }
+
+ /**
+ * Set explore data (center + categories).
+ */
+ setExploreData(data) {
+ this.placeholder.classList.add('hidden');
+ this.nodes = [];
+ this.links = [];
+ this.expandedCategories.clear();
+
+ const center = data.center;
+ this.centerName = center.name;
+ this.centerType = center.type;
+
+ // Center node
+ const centerNode = {
+ id: `center-${center.id}`,
+ name: center.name,
+ type: center.type,
+ isCenter: true,
+ isCategory: false,
+ fx: this.container.clientWidth / 2,
+ fy: this.container.clientHeight / 2,
+ };
+ this.nodes.push(centerNode);
+
+ // Category nodes
+ data.categories.forEach(cat => {
+ const catNode = {
+ id: cat.id,
+ name: `${cat.name} (${cat.count})`,
+ displayName: cat.name,
+ type: 'category',
+ isCenter: false,
+ isCategory: true,
+ category: cat.category,
+ count: cat.count,
+ parentName: center.name,
+ parentType: center.type,
+ };
+ this.nodes.push(catNode);
+ this.links.push({ source: centerNode.id, target: catNode.id });
+ });
+
+ this._render();
+
+ // Auto-expand categories
+ data.categories.forEach(cat => {
+ if (cat.count > 0) {
+ this._expandCategory(cat.id, center.name, center.type, cat.category);
+ }
+ });
+ }
+
+ async _expandCategory(categoryId, parentName, parentType, category) {
+ if (this.expandedCategories.has(categoryId)) return;
+ this.expandedCategories.add(categoryId);
+
+ const children = await window.apiClient.expand(parentName, parentType, category, 30);
+
+ children.forEach(child => {
+ const childId = `child-${child.type}-${child.id}`;
+ // Avoid duplicate nodes
+ if (this.nodes.find(n => n.id === childId)) return;
+
+ this.nodes.push({
+ id: childId,
+ name: child.name,
+ type: child.type,
+ isCenter: false,
+ isCategory: false,
+ nodeId: String(child.id),
+ });
+ this.links.push({ source: categoryId, target: childId });
+ });
+
+ this._render();
+ }
+
+ _render() {
+ const width = this.container.clientWidth;
+ const height = this.container.clientHeight;
+
+ // Clear previous
+ this.g.selectAll('*').remove();
+
+ // Create simulation
+ this.simulation = d3.forceSimulation(this.nodes)
+ .force('link', d3.forceLink(this.links).id(d => d.id).distance(d => {
+ if (d.source.isCenter || d.target.isCenter) return 120;
+ if (d.source.isCategory || d.target.isCategory) return 80;
+ return 60;
+ }))
+ .force('charge', d3.forceManyBody().strength(d => {
+ if (d.isCenter) return -400;
+ if (d.isCategory) return -200;
+ return -80;
+ }))
+ .force('center', d3.forceCenter(width / 2, height / 2))
+ .force('collision', d3.forceCollide().radius(d => this._getNodeRadius(d) + 5));
+
+ // Links
+ const link = this.g.append('g')
+ .selectAll('line')
+ .data(this.links)
+ .join('line')
+ .attr('class', 'link')
+ .attr('stroke-width', 1);
+
+ // Node groups
+ const node = this.g.append('g')
+ .selectAll('g')
+ .data(this.nodes)
+ .join('g')
+ .style('cursor', 'pointer')
+ .call(d3.drag()
+ .on('start', (event, d) => this._dragStarted(event, d))
+ .on('drag', (event, d) => this._dragged(event, d))
+ .on('end', (event, d) => this._dragEnded(event, d)))
+ .on('click', (event, d) => this._onNodeClicked(event, d));
+
+ // Node shapes
+ node.each(function(d) {
+ const el = d3.select(this);
+ const radius = d.isCenter ? 28 : d.isCategory ? 22 : 14;
+
+ if (d.isCategory) {
+ // Rounded rectangle for category nodes
+ el.append('rect')
+ .attr('x', -radius)
+ .attr('y', -radius * 0.7)
+ .attr('width', radius * 2)
+ .attr('height', radius * 1.4)
+ .attr('rx', 6)
+ .attr('ry', 6)
+ .attr('fill', 'var(--node-category)')
+ .attr('stroke', '#fff')
+ .attr('stroke-width', 1.5);
+ } else {
+ // Circle for regular nodes
+ el.append('circle')
+ .attr('r', radius)
+ .attr('fill', d.isCenter ? 'var(--node-' + d.type + ')' :
+ d.type === 'artist' ? 'var(--node-artist)' :
+ d.type === 'release' ? 'var(--node-release)' :
+ d.type === 'label' ? 'var(--node-label)' :
+ d.type === 'genre' || d.type === 'style' ? 'var(--node-genre)' : '#888')
+ .attr('stroke', d.isCenter ? '#fff' : 'rgba(255,255,255,0.3)')
+ .attr('stroke-width', d.isCenter ? 3 : 1);
+ }
+ });
+
+ // Labels
+ node.append('text')
+ .attr('class', 'node-label')
+ .attr('dy', d => d.isCategory ? 0 : this._getNodeRadius(d) + 14)
+ .text(d => {
+ const name = d.displayName || d.name;
+ return name.length > 20 ? name.substring(0, 18) + '...' : name;
+ })
+ .style('font-size', d => d.isCenter ? '13px' : d.isCategory ? '11px' : '10px')
+ .style('font-weight', d => d.isCenter ? '700' : '400');
+
+ // Simulation tick
+ this.simulation.on('tick', () => {
+ link
+ .attr('x1', d => d.source.x)
+ .attr('y1', d => d.source.y)
+ .attr('x2', d => d.target.x)
+ .attr('y2', d => d.target.y);
+
+ node.attr('transform', d => `translate(${d.x},${d.y})`);
+ });
+ }
+
+ _dragStarted(event, d) {
+ if (!event.active) this.simulation.alphaTarget(0.3).restart();
+ d.fx = d.x;
+ d.fy = d.y;
+ }
+
+ _dragged(event, d) {
+ d.fx = event.x;
+ d.fy = event.y;
+ }
+
+ _dragEnded(event, d) {
+ if (!event.active) this.simulation.alphaTarget(0);
+ if (!d.isCenter) {
+ d.fx = null;
+ d.fy = null;
+ }
+ }
+
+ _onNodeClicked(event, d) {
+ event.stopPropagation();
+
+ if (d.isCategory) return;
+
+ if (this.onNodeClick) {
+ const nodeId = d.nodeId || d.name;
+ this.onNodeClick(nodeId, d.type);
+ }
+ }
+
+ clear() {
+ this.nodes = [];
+ this.links = [];
+ this.expandedCategories.clear();
+ this.g.selectAll('*').remove();
+ if (this.simulation) this.simulation.stop();
+ this.placeholder.classList.remove('hidden');
+ }
+}
diff --git a/explore/static/js/trends.js b/explore/static/js/trends.js
new file mode 100644
index 0000000..1dc8e21
--- /dev/null
+++ b/explore/static/js/trends.js
@@ -0,0 +1,89 @@
+/**
+ * Plotly.js time-series chart for release trends.
+ */
+class TrendsChart {
+ constructor(containerId) {
+ this.container = document.getElementById(containerId);
+ this.placeholder = document.getElementById('trendsPlaceholder');
+ this.hasData = false;
+ }
+
+ /**
+ * Render trends data.
+ * @param {Object} data - Trends response { name, type, data: [{year, count}] }
+ */
+ render(data) {
+ if (!data || !data.data || data.data.length === 0) {
+ this.clear();
+ return;
+ }
+
+ this.placeholder.classList.add('hidden');
+ this.hasData = true;
+
+ const years = data.data.map(d => d.year);
+ const counts = data.data.map(d => d.count);
+
+ // Pad x-axis range
+ const minYear = Math.min(...years) - 3;
+ const maxYear = Math.max(...years) + 3;
+
+ const trace = {
+ x: years,
+ y: counts,
+ type: 'scatter',
+ mode: 'lines+markers',
+ name: `${data.name} releases`,
+ line: {
+ color: '#1877f2',
+ width: 2,
+ },
+ marker: {
+ color: '#1877f2',
+ size: 6,
+ },
+ fill: 'tozeroy',
+ fillcolor: 'rgba(24, 119, 242, 0.1)',
+ };
+
+ const layout = {
+ title: {
+ text: `Release Timeline: ${data.name}`,
+ font: { color: '#e4e6eb', size: 18 },
+ },
+ xaxis: {
+ title: { text: 'Year', font: { color: '#b0b3b8' } },
+ range: [minYear, maxYear],
+ tickfont: { color: '#b0b3b8' },
+ gridcolor: '#2d3051',
+ linecolor: '#2d3051',
+ },
+ yaxis: {
+ title: { text: 'Number of Releases', font: { color: '#b0b3b8' } },
+ tickfont: { color: '#b0b3b8' },
+ gridcolor: '#2d3051',
+ linecolor: '#2d3051',
+ rangemode: 'tozero',
+ },
+ plot_bgcolor: '#0a0e27',
+ paper_bgcolor: '#0a0e27',
+ font: { color: '#e4e6eb' },
+ margin: { t: 60, r: 30, b: 60, l: 60 },
+ hovermode: 'x unified',
+ };
+
+ const config = {
+ responsive: true,
+ displayModeBar: true,
+ modeBarButtonsToRemove: ['lasso2d', 'select2d'],
+ };
+
+ Plotly.newPlot(this.container, [trace], layout, config);
+ }
+
+ clear() {
+ Plotly.purge(this.container);
+ this.placeholder.classList.remove('hidden');
+ this.hasData = false;
+ }
+}
diff --git a/justfile b/justfile
index 91043bb..4442c8c 100755
--- a/justfile
+++ b/justfile
@@ -122,6 +122,9 @@ test-parallel:
uv run pytest tests/discovery/ -m 'not e2e' -v > /tmp/test-discovery.log 2>&1 &
pid_discovery=$!
+ uv run pytest tests/explore/ -m 'not e2e' -v > /tmp/test-explore.log 2>&1 &
+ pid_explore=$!
+
uv run pytest tests/extractor/ -v > /tmp/test-pyextractor.log 2>&1 &
pid_pyextractor=$!
@@ -142,6 +145,7 @@ test-parallel:
wait $pid_common || { echo "โ Common tests failed"; cat /tmp/test-common.log; failed=1; }
wait $pid_dashboard || { echo "โ Dashboard tests failed"; cat /tmp/test-dashboard.log; failed=1; }
wait $pid_discovery || { echo "โ Discovery tests failed"; cat /tmp/test-discovery.log; failed=1; }
+ wait $pid_explore || { echo "โ Explore tests failed"; cat /tmp/test-explore.log; failed=1; }
wait $pid_pyextractor || { echo "โ PyExtractor tests failed"; cat /tmp/test-pyextractor.log; failed=1; }
wait $pid_graphinator || { echo "โ Graphinator tests failed"; cat /tmp/test-graphinator.log; failed=1; }
wait $pid_tableinator || { echo "โ Tableinator tests failed"; cat /tmp/test-tableinator.log; failed=1; }
@@ -180,6 +184,11 @@ test-dashboard:
test-discovery:
uv run pytest tests/discovery/ -m 'not e2e' -v
+# Run explore service tests
+[group('test')]
+test-explore:
+ uv run pytest tests/explore/ -m 'not e2e' -v
+
# Run Python extractor tests
[group('test')]
test-pyextractor:
@@ -209,6 +218,11 @@ test-tableinator:
dashboard:
uv run python dashboard/dashboard.py
+# Run the explore service (graph exploration and trends)
+[group('services')]
+explore:
+ uv run python -m explore.explore
+
# Run the discovery service (AI-powered music intelligence)
[group('services')]
discovery:
@@ -312,6 +326,7 @@ build:
docker-compose build \
dashboard \
discovery \
+ explore \
pyextractor \
rustextractor \
graphinator \
diff --git a/pyproject.toml b/pyproject.toml
index f96c00e..0d00e0d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -75,6 +75,15 @@ utilities = [
"psutil>=5.9.0",
"requests>=2.31.0",
]
+explore = [
+ "fastapi>=0.115.6",
+ "neo4j>=5.15.0",
+ "orjson>=3.9.0",
+ "pydantic>=2.10.5",
+ "python-multipart>=0.0.20",
+ "structlog>=24.0.0",
+ "uvicorn[standard]>=0.34.0",
+]
discovery = [
# Web framework dependencies
"fastapi>=0.115.6",
@@ -102,7 +111,7 @@ discovery = [
"asyncpg>=0.29.0", # Async PostgreSQL driver for SQLAlchemy
]
all = [
- "discogsography[dashboard,discovery,pyextractor,graphinator,tableinator,dev,utilities]",
+ "discogsography[dashboard,discovery,explore,pyextractor,graphinator,tableinator,dev,utilities]",
]
[tool.ruff.format]
@@ -117,7 +126,7 @@ docstring-code-line-length = "dynamic"
lines-after-imports = 2
combine-as-imports = true
split-on-trailing-comma = true
-known-first-party = ["common", "dashboard", "discovery", "extractor", "graphinator", "tableinator"]
+known-first-party = ["common", "dashboard", "discovery", "explore", "extractor", "graphinator", "tableinator"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
force-sort-within-sections = true
@@ -155,6 +164,7 @@ ignore = [
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]
+"*/explore.py" = ["T201"] # Allow print statements for ASCII art
"*/extractor.py" = ["T201"] # Allow print statements for ASCII art
"*/graphinator.py" = ["T201"] # Allow print statements for ASCII art
"*/tableinator.py" = ["T201"] # Allow print statements for ASCII art
@@ -217,6 +227,7 @@ module = [
"discovery.api_ml",
"discovery.api_realtime",
"discovery.api_search",
+ "explore.explore",
]
disallow_untyped_decorators = false
@@ -232,7 +243,7 @@ disallow_untyped_calls = false
disallow_untyped_defs = false
[tool.coverage.run]
-source = ["common", "dashboard", "discovery", "extractor/pyextractor", "graphinator", "tableinator"]
+source = ["common", "dashboard", "discovery", "explore", "extractor/pyextractor", "graphinator", "tableinator"]
omit = ["*/tests/*", "*/__init__.py"]
[tool.coverage.report]
@@ -311,7 +322,7 @@ split_on_trailing_comma = true
# uv workspace configuration
[tool.uv.workspace]
-members = ["common", "dashboard", "discovery", "extractor/pyextractor", "graphinator", "tableinator"]
+members = ["common", "dashboard", "discovery", "explore", "extractor/pyextractor", "graphinator", "tableinator"]
# Environment restrictions for uv to avoid iOS and other incompatible platforms
[tool.uv]
diff --git a/scripts/update-project.sh b/scripts/update-project.sh
index 38a442a..51b4fed 100755
--- a/scripts/update-project.sh
+++ b/scripts/update-project.sh
@@ -593,7 +593,7 @@ update_python_packages() {
backup_file "pyproject.toml"
# Backup all pyproject.toml files including nested ones
- for service in common dashboard discovery graphinator tableinator; do
+ for service in common dashboard discovery explore graphinator tableinator; do
if [[ -f "$service/pyproject.toml" ]]; then
backup_file "$service/pyproject.toml"
fi
@@ -862,6 +862,7 @@ show_file_report() {
echo " โ common/pyproject.toml"
echo " โ dashboard/pyproject.toml"
echo " โ discovery/pyproject.toml"
+ echo " โ explore/pyproject.toml"
echo " โ extractor/pyextractor/pyproject.toml"
echo " โ extractor/rustextractor/pyproject.toml (tools only - Rust project)"
echo " โ graphinator/pyproject.toml"
@@ -874,6 +875,7 @@ show_file_report() {
echo "๐ณ Docker Configuration:"
echo " โ dashboard/Dockerfile"
echo " โ discovery/Dockerfile"
+ echo " โ explore/Dockerfile"
echo " โ extractor/pyextractor/Dockerfile"
echo " โ extractor/rustextractor/Dockerfile"
echo " โ graphinator/Dockerfile"
@@ -925,6 +927,7 @@ verify_components() {
"common/pyproject.toml"
"dashboard/pyproject.toml"
"discovery/pyproject.toml"
+ "explore/pyproject.toml"
"extractor/pyextractor/pyproject.toml"
"extractor/rustextractor/pyproject.toml"
"graphinator/pyproject.toml"
@@ -945,6 +948,7 @@ verify_components() {
local dockerfile_list=(
"dashboard/Dockerfile"
"discovery/Dockerfile"
+ "explore/Dockerfile"
"extractor/pyextractor/Dockerfile"
"extractor/rustextractor/Dockerfile"
"graphinator/Dockerfile"
diff --git a/tests/dashboard/test_dashboard_app.py b/tests/dashboard/test_dashboard_app.py
index cb99ede..84c893e 100644
--- a/tests/dashboard/test_dashboard_app.py
+++ b/tests/dashboard/test_dashboard_app.py
@@ -400,8 +400,8 @@ async def mock_get(_url: str) -> Mock:
statuses = await app.get_service_statuses()
- # Should have 4 services
- assert len(statuses) == 4
+ # Should have 3 services (extractor, graphinator, tableinator)
+ assert len(statuses) == 3
# All should be healthy
for status in statuses:
@@ -425,19 +425,15 @@ async def mock_get(_url: str) -> Mock:
call_count += 1
response = Mock()
if call_count == 1:
- # First service healthy
+ # First service (extractor) healthy
response.status_code = 200
response.json = Mock(return_value={"status": "healthy"})
elif call_count == 2:
- # Second service returns error code
+ # Second service (graphinator) returns error code
response.status_code = 500
- elif call_count == 3:
- # Third service raises exception
- raise httpx.ConnectError("Connection failed")
else:
- # Fourth service healthy
- response.status_code = 200
- response.json = Mock(return_value={"status": "healthy"})
+ # Third service (tableinator) raises exception
+ raise httpx.ConnectError("Connection failed")
return response
with patch("httpx.AsyncClient") as mock_client_class:
@@ -449,13 +445,12 @@ async def mock_get(_url: str) -> Mock:
statuses = await app.get_service_statuses()
- assert len(statuses) == 4
+ assert len(statuses) == 3
assert statuses[0].status == "healthy"
assert statuses[1].status == "unhealthy"
assert statuses[1].error == "HTTP 500"
assert statuses[2].status == "unknown"
assert "Connection failed" in statuses[2].error
- assert statuses[3].status == "healthy"
@pytest.mark.asyncio
async def test_get_queue_info_success(self) -> None:
@@ -1007,314 +1002,6 @@ def test_prometheus_metrics(self) -> None:
assert len(response.text) > 0
-class TestDiscoveryProxyEndpoints:
- """Test Discovery API proxy endpoints."""
-
- @pytest.mark.asyncio
- async def test_get_ml_status_success(self) -> None:
- """Test ML status proxy endpoint success."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_ml_status
-
- mock_response_data = {"status": "healthy", "model": "loaded"}
-
- async def mock_get(_url: str) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.get = mock_get
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.get("/api/discovery/ml/status")(get_ml_status)
-
- with TestClient(test_app) as client:
- response = client.get("/api/discovery/ml/status")
- assert response.status_code == 200
- data = response.json()
- assert data["status"] == "healthy"
-
- @pytest.mark.asyncio
- async def test_get_ml_status_error(self) -> None:
- """Test ML status proxy endpoint error."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_ml_status
-
- async def mock_get(_url: str) -> Mock:
- raise Exception("Discovery service unavailable")
-
- with (
- patch("httpx.AsyncClient") as mock_client_class,
- patch("dashboard.dashboard.logger") as _mock_logger,
- ):
- mock_client = AsyncMock()
- mock_client.get = mock_get
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.get("/api/discovery/ml/status")(get_ml_status)
-
- with TestClient(test_app) as client:
- response = client.get("/api/discovery/ml/status")
- assert response.status_code == 503
- data = response.json()
- assert "error" in data
-
- @pytest.mark.asyncio
- async def test_get_collaborative_recommendations(self) -> None:
- """Test collaborative recommendations proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_collaborative_recommendations
-
- mock_response_data = {"recommendations": [{"id": "1", "score": 0.95}]}
-
- async def mock_post(_url: str, **_kwargs: Any) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.post = mock_post
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.post("/api/discovery/ml/recommend/collaborative")(get_collaborative_recommendations)
-
- with TestClient(test_app) as client:
- response = client.post("/api/discovery/ml/recommend/collaborative?artist_id=Beatles&limit=10")
- assert response.status_code == 200
- data = response.json()
- assert "recommendations" in data
-
- @pytest.mark.asyncio
- async def test_get_hybrid_recommendations(self) -> None:
- """Test hybrid recommendations proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_hybrid_recommendations
-
- mock_response_data = {"recommendations": []}
-
- async def mock_post(_url: str, **_kwargs: Any) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.post = mock_post
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.post("/api/discovery/ml/recommend/hybrid")(get_hybrid_recommendations)
-
- with TestClient(test_app) as client:
- response = client.post("/api/discovery/ml/recommend/hybrid")
- assert response.status_code == 200
-
- @pytest.mark.asyncio
- async def test_get_search_status(self) -> None:
- """Test search status proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_search_status
-
- mock_response_data = {"status": "healthy", "indexed": 1000}
-
- async def mock_get(_url: str) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.get = mock_get
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.get("/api/discovery/search/status")(get_search_status)
-
- with TestClient(test_app) as client:
- response = client.get("/api/discovery/search/status")
- assert response.status_code == 200
-
- @pytest.mark.asyncio
- async def test_get_search_stats(self) -> None:
- """Test search stats proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_search_stats
-
- mock_response_data = {"queries": 500, "avg_time": 0.25}
-
- async def mock_get(_url: str) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.get = mock_get
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.get("/api/discovery/search/stats")(get_search_stats)
-
- with TestClient(test_app) as client:
- response = client.get("/api/discovery/search/stats")
- assert response.status_code == 200
-
- @pytest.mark.asyncio
- async def test_get_graph_status(self) -> None:
- """Test graph status proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_graph_status
-
- mock_response_data = {"status": "healthy", "algorithms": ["pagerank"]}
-
- async def mock_get(_url: str) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.get = mock_get
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.get("/api/discovery/graph/status")(get_graph_status)
-
- with TestClient(test_app) as client:
- response = client.get("/api/discovery/graph/status")
- assert response.status_code == 200
-
- @pytest.mark.asyncio
- async def test_get_centrality_metrics(self) -> None:
- """Test centrality metrics proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_centrality_metrics
-
- mock_response_data = {"results": [{"node": "A", "score": 0.95}]}
-
- async def mock_post(_url: str, **_kwargs: Any) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.post = mock_post
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.post("/api/discovery/graph/centrality")(get_centrality_metrics)
-
- with TestClient(test_app) as client:
- response = client.post("/api/discovery/graph/centrality")
- assert response.status_code == 200
-
- @pytest.mark.asyncio
- async def test_get_realtime_status(self) -> None:
- """Test realtime status proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_realtime_status
-
- mock_response_data = {"status": "healthy", "stream_active": True}
-
- async def mock_get(_url: str) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.get = mock_get
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.get("/api/discovery/realtime/status")(get_realtime_status)
-
- with TestClient(test_app) as client:
- response = client.get("/api/discovery/realtime/status")
- assert response.status_code == 200
-
- @pytest.mark.asyncio
- async def test_get_trending(self) -> None:
- """Test trending items proxy endpoint."""
- from fastapi import FastAPI
- from fastapi.responses import ORJSONResponse
-
- from dashboard.dashboard import get_trending
-
- mock_response_data = {"trending": [{"name": "Artist1", "score": 100}]}
-
- async def mock_post(_url: str, **_kwargs: Any) -> Mock:
- response = Mock()
- response.status_code = 200
- response.json = Mock(return_value=mock_response_data)
- return response
-
- with patch("httpx.AsyncClient") as mock_client_class:
- mock_client = AsyncMock()
- mock_client.post = mock_post
- mock_client.__aenter__ = AsyncMock(return_value=mock_client)
- mock_client.__aexit__ = AsyncMock(return_value=None)
- mock_client_class.return_value = mock_client
-
- test_app = FastAPI(default_response_class=ORJSONResponse)
- test_app.post("/api/discovery/realtime/trending")(get_trending)
-
- with TestClient(test_app) as client:
- response = client.post("/api/discovery/realtime/trending")
- assert response.status_code == 200
-
-
class TestWebSocketEndpoint:
"""Test WebSocket connection handling."""
diff --git a/tests/explore/__init__.py b/tests/explore/__init__.py
new file mode 100644
index 0000000..f09a488
--- /dev/null
+++ b/tests/explore/__init__.py
@@ -0,0 +1 @@
+"""Tests for the Explore service."""
diff --git a/tests/explore/conftest.py b/tests/explore/conftest.py
new file mode 100644
index 0000000..9ebc305
--- /dev/null
+++ b/tests/explore/conftest.py
@@ -0,0 +1,230 @@
+"""Fixtures for Explore service tests."""
+
+import os
+
+
+# Set environment variables BEFORE importing explore modules
+os.environ.setdefault("NEO4J_ADDRESS", "bolt://localhost:7687")
+os.environ.setdefault("NEO4J_USERNAME", "neo4j")
+os.environ.setdefault("NEO4J_PASSWORD", "testpassword")
+
+from collections.abc import AsyncGenerator, Generator
+from contextlib import asynccontextmanager
+import subprocess
+import sys
+import time
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import httpx
+import pytest
+
+
+@pytest.fixture
+def mock_neo4j_driver() -> MagicMock:
+ """Create a mock Neo4j async driver."""
+ driver = MagicMock()
+
+ # Setup async session context manager
+ mock_session = AsyncMock()
+ mock_result = AsyncMock()
+
+ # Make session work as async context manager
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=False)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ # Make result iterable (for list comprehension async for)
+ mock_result.__aiter__ = MagicMock(return_value=iter([]))
+ mock_result.single = AsyncMock(return_value=None)
+
+ driver.session = MagicMock(return_value=mock_session)
+ driver.close = AsyncMock()
+
+ return driver
+
+
+@pytest.fixture
+def mock_neo4j_session(mock_neo4j_driver: MagicMock) -> AsyncMock:
+ """Get the mock session from the mock driver."""
+ session: AsyncMock = mock_neo4j_driver.session()
+ return session
+
+
+@pytest.fixture
+def test_client(mock_neo4j_driver: MagicMock) -> Generator[TestClient]:
+ """Create a test client with mocked Neo4j driver, bypassing real lifespan."""
+ import explore.explore as explore_module
+ from explore.explore import app
+
+ # Replace the lifespan with a no-op so we don't try to connect to Neo4j
+ @asynccontextmanager
+ async def mock_lifespan(_app: FastAPI) -> AsyncGenerator[None]:
+ yield
+
+ original_lifespan = app.router.lifespan_context
+ app.router.lifespan_context = mock_lifespan
+
+ # Patch the module-level driver
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = mock_neo4j_driver
+
+ # Clear autocomplete cache between tests
+ explore_module._autocomplete_cache.clear()
+
+ with TestClient(app, raise_server_exceptions=False) as client:
+ yield client
+
+ # Restore
+ explore_module.neo4j_driver = original_driver
+ app.router.lifespan_context = original_lifespan
+
+
+@pytest.fixture
+def sample_artist_autocomplete() -> list[dict[str, Any]]:
+ """Sample autocomplete results for artists."""
+ return [
+ {"id": "1", "name": "Radiohead", "score": 9.5},
+ {"id": "2", "name": "Radio Dept.", "score": 7.2},
+ {"id": "3", "name": "Radiator Hospital", "score": 5.1},
+ ]
+
+
+@pytest.fixture
+def sample_explore_artist() -> dict[str, Any]:
+ """Sample explore result for an artist."""
+ return {
+ "id": "1",
+ "name": "Radiohead",
+ "release_count": 42,
+ "label_count": 5,
+ "alias_count": 2,
+ }
+
+
+@pytest.fixture
+def sample_explore_genre() -> dict[str, Any]:
+ """Sample explore result for a genre."""
+ return {
+ "id": "Rock",
+ "name": "Rock",
+ "artist_count": 1000,
+ "label_count": 200,
+ "style_count": 50,
+ }
+
+
+@pytest.fixture
+def sample_explore_label() -> dict[str, Any]:
+ """Sample explore result for a label."""
+ return {
+ "id": "100",
+ "name": "Warp Records",
+ "release_count": 500,
+ "artist_count": 120,
+ }
+
+
+@pytest.fixture
+def sample_expand_releases() -> list[dict[str, Any]]:
+ """Sample expand results for releases."""
+ return [
+ {"id": "10", "name": "OK Computer", "type": "release", "year": 1997},
+ {"id": "11", "name": "Kid A", "type": "release", "year": 2000},
+ {"id": "12", "name": "In Rainbows", "type": "release", "year": 2007},
+ ]
+
+
+@pytest.fixture
+def sample_artist_details() -> dict[str, Any]:
+ """Sample artist details."""
+ return {
+ "id": "1",
+ "name": "Radiohead",
+ "genres": ["Rock", "Electronic"],
+ "styles": ["Alternative Rock", "Art Rock"],
+ "release_count": 42,
+ "groups": [],
+ }
+
+
+@pytest.fixture
+def sample_trends_data() -> list[dict[str, Any]]:
+ """Sample trends time-series data."""
+ return [
+ {"year": 1993, "count": 1},
+ {"year": 1995, "count": 2},
+ {"year": 1997, "count": 1},
+ {"year": 2000, "count": 1},
+ {"year": 2003, "count": 1},
+ ]
+
+
+# E2E fixtures
+
+
+@pytest.fixture(scope="session")
+def test_server() -> Generator[str]:
+ """Start explore test server for E2E tests."""
+ port = 8006
+ server_url = f"http://localhost:{port}"
+
+ process = subprocess.Popen( # noqa: S603
+ [
+ sys.executable,
+ "-m",
+ "uvicorn",
+ "tests.explore.explore_test_app:create_test_app",
+ "--factory",
+ "--host",
+ "127.0.0.1",
+ "--port",
+ str(port),
+ ],
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ )
+
+ # Wait for server readiness
+ max_retries = 40
+ for _i in range(max_retries):
+ try:
+ response = httpx.get(f"{server_url}/health", timeout=2.0)
+ if response.status_code == 200:
+ break
+ except (httpx.ConnectError, httpx.TimeoutException):
+ pass
+ time.sleep(0.5)
+ else:
+ process.terminate()
+ stdout, stderr = process.communicate(timeout=5)
+ raise RuntimeError(f"Test server failed to start.\nStdout: {stdout.decode()}\nStderr: {stderr.decode()}")
+
+ yield server_url
+
+ process.terminate()
+ try:
+ process.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ process.kill()
+ process.wait()
+
+
+@pytest.fixture(scope="session")
+def browser_context_args() -> dict[str, Any]:
+ """Configure browser context for E2E tests."""
+ return {
+ "viewport": {"width": 1280, "height": 720},
+ "ignore_https_errors": True,
+ }
+
+
+@pytest.fixture(scope="session")
+def browser_type_launch_args() -> dict[str, Any]:
+ """Configure browser launch arguments."""
+ return {
+ "headless": True,
+ "args": ["--no-sandbox", "--disable-gpu"],
+ }
diff --git a/tests/explore/explore_test_app.py b/tests/explore/explore_test_app.py
new file mode 100644
index 0000000..789d725
--- /dev/null
+++ b/tests/explore/explore_test_app.py
@@ -0,0 +1,165 @@
+"""Test application factory for Explore service E2E tests."""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Query
+from fastapi.responses import ORJSONResponse
+from fastapi.staticfiles import StaticFiles
+
+
+# Mock Neo4j data
+MOCK_AUTOCOMPLETE_RESULTS: dict[str, list[dict[str, Any]]] = {
+ "artist": [
+ {"id": "1", "name": "Radiohead", "score": 9.5},
+ {"id": "2", "name": "Radio Dept.", "score": 7.2},
+ ],
+ "genre": [
+ {"id": "Rock", "name": "Rock", "score": 1.0},
+ {"id": "Rockabilly", "name": "Rockabilly", "score": 1.0},
+ ],
+ "label": [
+ {"id": "100", "name": "Warp Records", "score": 9.0},
+ {"id": "101", "name": "Warp", "score": 7.0},
+ ],
+}
+
+MOCK_EXPLORE_RESULTS: dict[str, dict[str, Any]] = {
+ "artist": {
+ "id": "1",
+ "name": "Radiohead",
+ "release_count": 42,
+ "label_count": 5,
+ "alias_count": 2,
+ },
+ "genre": {
+ "id": "Rock",
+ "name": "Rock",
+ "artist_count": 1000,
+ "label_count": 200,
+ "style_count": 50,
+ },
+ "label": {
+ "id": "100",
+ "name": "Warp Records",
+ "release_count": 500,
+ "artist_count": 120,
+ },
+}
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
+ """Manage test app lifecycle."""
+ yield
+
+
+def create_test_app() -> FastAPI:
+ """Create a test instance of the Explore FastAPI app."""
+ app = FastAPI(
+ title="Discogsography Explore Test",
+ version="0.1.0",
+ default_response_class=ORJSONResponse,
+ lifespan=lifespan,
+ )
+
+ @app.get("/health")
+ async def health_check() -> ORJSONResponse:
+ return ORJSONResponse(
+ content={
+ "status": "healthy",
+ "service": "explore",
+ "timestamp": datetime.now(UTC).isoformat(),
+ }
+ )
+
+ @app.get("/api/autocomplete")
+ async def autocomplete(
+ q: str = Query(..., min_length=2),
+ type: str = Query("artist"),
+ limit: int = Query(10, ge=1, le=50),
+ ) -> ORJSONResponse:
+ entity_type = type.lower()
+ results = MOCK_AUTOCOMPLETE_RESULTS.get(entity_type, [])
+ filtered = [r for r in results if q.lower() in r["name"].lower()][:limit]
+ return ORJSONResponse(content={"results": filtered})
+
+ @app.get("/api/explore")
+ async def explore(
+ name: str = Query(...), # noqa: ARG001
+ type: str = Query("artist"),
+ ) -> ORJSONResponse:
+ entity_type = type.lower()
+ result = MOCK_EXPLORE_RESULTS.get(entity_type)
+ if not result:
+ return ORJSONResponse(content={"error": "Not found"}, status_code=404)
+
+ from explore.explore import _build_categories
+
+ categories = _build_categories(entity_type, result)
+ return ORJSONResponse(
+ content={
+ "center": {"id": str(result["id"]), "name": result["name"], "type": entity_type},
+ "categories": categories,
+ }
+ )
+
+ @app.get("/api/expand")
+ async def expand(
+ node_id: str = Query(...), # noqa: ARG001
+ type: str = Query(...), # noqa: ARG001
+ category: str = Query(...), # noqa: ARG001
+ limit: int = Query(50, ge=1, le=200), # noqa: ARG001
+ ) -> ORJSONResponse:
+ return ORJSONResponse(
+ content={
+ "children": [
+ {"id": "10", "name": "OK Computer", "type": "release"},
+ {"id": "11", "name": "Kid A", "type": "release"},
+ ]
+ }
+ )
+
+ @app.get("/api/node/{node_id}")
+ async def get_node_details(
+ node_id: str,
+ type: str = Query("artist"), # noqa: ARG001
+ ) -> ORJSONResponse:
+ return ORJSONResponse(
+ content={
+ "id": node_id,
+ "name": "Radiohead",
+ "genres": ["Rock", "Electronic"],
+ "styles": ["Alternative Rock", "Art Rock"],
+ "release_count": 42,
+ "groups": [],
+ }
+ )
+
+ @app.get("/api/trends")
+ async def get_trends(
+ name: str = Query(...),
+ type: str = Query("artist"),
+ ) -> ORJSONResponse:
+ return ORJSONResponse(
+ content={
+ "name": name,
+ "type": type.lower(),
+ "data": [
+ {"year": 1993, "count": 1},
+ {"year": 1995, "count": 2},
+ {"year": 1997, "count": 1},
+ {"year": 2000, "count": 1},
+ {"year": 2003, "count": 1},
+ ],
+ }
+ )
+
+ # Serve static files from explore module (html=True serves index.html at root)
+ static_dir = Path(__file__).parent.parent.parent / "explore" / "static"
+ app.mount("/", StaticFiles(directory=str(static_dir), html=True), name="static")
+
+ return app
diff --git a/tests/explore/test_explore_api.py b/tests/explore/test_explore_api.py
new file mode 100644
index 0000000..d1d1b17
--- /dev/null
+++ b/tests/explore/test_explore_api.py
@@ -0,0 +1,590 @@
+"""Tests for Explore service API endpoints."""
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from fastapi.testclient import TestClient
+import pytest
+
+
+class TestHealthEndpoint:
+ """Test the health check endpoint."""
+
+ def test_health_returns_200(self, test_client: TestClient) -> None:
+ response = test_client.get("/health")
+ assert response.status_code == 200
+ data = response.json()
+ assert data["service"] == "explore"
+ assert "timestamp" in data
+
+ def test_health_status_healthy(self, test_client: TestClient) -> None:
+ response = test_client.get("/health")
+ data = response.json()
+ assert data["status"] == "healthy"
+
+
+class TestAutocompleteEndpoint:
+ """Test the autocomplete endpoint."""
+
+ def test_autocomplete_artist_success(
+ self,
+ test_client: TestClient,
+ sample_artist_autocomplete: list[dict[str, Any]],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_artist_autocomplete)
+
+ with patch.dict("explore.explore.AUTOCOMPLETE_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/autocomplete?q=radio&type=artist&limit=10")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert "results" in data
+ assert len(data["results"]) == 3
+
+ def test_autocomplete_minimum_length(self, test_client: TestClient) -> None:
+ response = test_client.get("/api/autocomplete?q=a")
+ assert response.status_code == 422 # Validation error
+
+ def test_autocomplete_invalid_type(self, test_client: TestClient) -> None:
+ response = test_client.get("/api/autocomplete?q=test&type=invalid")
+ assert response.status_code == 400
+ data = response.json()
+ assert "error" in data
+
+ def test_autocomplete_genre(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[{"id": "Rock", "name": "Rock", "score": 1.0}])
+
+ with patch.dict("explore.explore.AUTOCOMPLETE_DISPATCH", {"genre": mock_func}):
+ response = test_client.get("/api/autocomplete?q=rock&type=genre")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert "results" in data
+
+ def test_autocomplete_label(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[{"id": "100", "name": "Warp Records", "score": 9.0}])
+
+ with patch.dict("explore.explore.AUTOCOMPLETE_DISPATCH", {"label": mock_func}):
+ response = test_client.get("/api/autocomplete?q=warp&type=label")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert "results" in data
+
+ def test_autocomplete_caching(self, test_client: TestClient) -> None:
+ """Test that repeated queries use the cache."""
+ mock_func = AsyncMock(return_value=[{"id": "1", "name": "Radiohead", "score": 9.5}])
+
+ with patch.dict("explore.explore.AUTOCOMPLETE_DISPATCH", {"artist": mock_func}):
+ # First call
+ response1 = test_client.get("/api/autocomplete?q=cachetest&type=artist")
+ assert response1.status_code == 200
+
+ # Second call (should use cache, not call the function again)
+ response2 = test_client.get("/api/autocomplete?q=cachetest&type=artist")
+ assert response2.status_code == 200
+
+ # The function should only be called once
+ assert mock_func.call_count == 1
+
+ def test_autocomplete_service_not_ready(self, test_client: TestClient) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = None
+
+ response = test_client.get("/api/autocomplete?q=test&type=artist")
+ assert response.status_code == 503
+
+ explore_module.neo4j_driver = original_driver
+
+ def test_autocomplete_cache_eviction(self, test_client: TestClient) -> None:
+ """Test that cache evicts oldest entries when full."""
+ import explore.explore as explore_module
+
+ # Set a small cache max to trigger eviction
+ original_max = explore_module._AUTOCOMPLETE_CACHE_MAX
+ explore_module._AUTOCOMPLETE_CACHE_MAX = 4
+ explore_module._autocomplete_cache.clear()
+
+ mock_func = AsyncMock(return_value=[{"id": "1", "name": "Test", "score": 1.0}])
+ with patch.dict("explore.explore.AUTOCOMPLETE_DISPATCH", {"artist": mock_func}):
+ # Fill cache beyond max to trigger eviction
+ for i in range(5):
+ response = test_client.get(f"/api/autocomplete?q=evict{i}&type=artist")
+ assert response.status_code == 200
+
+ # Cache should have been evicted (oldest quarter removed)
+ assert len(explore_module._autocomplete_cache) <= 4
+
+ explore_module._AUTOCOMPLETE_CACHE_MAX = original_max
+ explore_module._autocomplete_cache.clear()
+
+
+class TestExploreEndpoint:
+ """Test the explore endpoint."""
+
+ def test_explore_artist_success(
+ self,
+ test_client: TestClient,
+ sample_explore_artist: dict[str, Any],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_explore_artist)
+
+ with patch.dict("explore.explore.EXPLORE_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/explore?name=Radiohead&type=artist")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert "center" in data
+ assert data["center"]["name"] == "Radiohead"
+ assert data["center"]["type"] == "artist"
+ assert "categories" in data
+ assert len(data["categories"]) == 3 # releases, labels, aliases
+
+ def test_explore_genre_success(
+ self,
+ test_client: TestClient,
+ sample_explore_genre: dict[str, Any],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_explore_genre)
+
+ with patch.dict("explore.explore.EXPLORE_DISPATCH", {"genre": mock_func}):
+ response = test_client.get("/api/explore?name=Rock&type=genre")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["center"]["name"] == "Rock"
+ assert len(data["categories"]) == 3 # artists, labels, styles
+
+ def test_explore_label_success(
+ self,
+ test_client: TestClient,
+ sample_explore_label: dict[str, Any],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_explore_label)
+
+ with patch.dict("explore.explore.EXPLORE_DISPATCH", {"label": mock_func}):
+ response = test_client.get("/api/explore?name=Warp%20Records&type=label")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["center"]["name"] == "Warp Records"
+ assert len(data["categories"]) == 2 # releases, artists
+
+ def test_explore_not_found(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=None)
+
+ with patch.dict("explore.explore.EXPLORE_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/explore?name=NonExistent&type=artist")
+
+ assert response.status_code == 404
+
+ def test_explore_invalid_type(self, test_client: TestClient) -> None:
+ response = test_client.get("/api/explore?name=Test&type=invalid")
+ assert response.status_code == 400
+
+ def test_explore_service_not_ready(self, test_client: TestClient) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = None
+
+ response = test_client.get("/api/explore?name=Test&type=artist")
+ assert response.status_code == 503
+
+ explore_module.neo4j_driver = original_driver
+
+ def test_explore_category_counts(
+ self,
+ test_client: TestClient,
+ sample_explore_artist: dict[str, Any],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_explore_artist)
+
+ with patch.dict("explore.explore.EXPLORE_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/explore?name=Radiohead&type=artist")
+
+ data = response.json()
+ categories = {c["category"]: c["count"] for c in data["categories"]}
+ assert categories["releases"] == 42
+ assert categories["labels"] == 5
+ assert categories["aliases"] == 2
+
+
+class TestExpandEndpoint:
+ """Test the expand endpoint."""
+
+ def test_expand_artist_releases(
+ self,
+ test_client: TestClient,
+ sample_expand_releases: list[dict[str, Any]],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_expand_releases)
+
+ with patch.dict("explore.explore.EXPAND_DISPATCH", {"artist": {"releases": mock_func}}):
+ response = test_client.get("/api/expand?node_id=Radiohead&type=artist&category=releases")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert "children" in data
+ assert len(data["children"]) == 3
+
+ def test_expand_invalid_type(self, test_client: TestClient) -> None:
+ response = test_client.get("/api/expand?node_id=Test&type=invalid&category=releases")
+ assert response.status_code == 400
+
+ def test_expand_service_not_ready(self, test_client: TestClient) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = None
+
+ response = test_client.get("/api/expand?node_id=Test&type=artist&category=releases")
+ assert response.status_code == 503
+
+ explore_module.neo4j_driver = original_driver
+
+ def test_expand_invalid_category(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[])
+ with patch.dict("explore.explore.EXPAND_DISPATCH", {"artist": {"releases": mock_func, "labels": mock_func, "aliases": mock_func}}):
+ response = test_client.get("/api/expand?node_id=Test&type=artist&category=invalid")
+
+ assert response.status_code == 400
+ data = response.json()
+ assert "Valid:" in data["error"]
+
+ def test_expand_genre_artists(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[{"id": "1", "name": "Radiohead", "type": "artist"}])
+
+ with patch.dict("explore.explore.EXPAND_DISPATCH", {"genre": {"artists": mock_func}}):
+ response = test_client.get("/api/expand?node_id=Rock&type=genre&category=artists")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert len(data["children"]) == 1
+
+ def test_expand_label_releases(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[{"id": "10", "name": "OK Computer", "type": "release", "year": 1997}])
+
+ with patch.dict("explore.explore.EXPAND_DISPATCH", {"label": {"releases": mock_func}}):
+ response = test_client.get("/api/expand?node_id=Parlophone&type=label&category=releases")
+
+ assert response.status_code == 200
+
+ def test_expand_with_limit(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[])
+
+ with patch.dict("explore.explore.EXPAND_DISPATCH", {"artist": {"releases": mock_func}}):
+ response = test_client.get("/api/expand?node_id=Test&type=artist&category=releases&limit=5")
+
+ assert response.status_code == 200
+ mock_func.assert_called_once()
+ # Verify the limit was passed
+ call_args = mock_func.call_args
+ assert call_args[0][1] == "Test"
+ assert call_args[0][2] == 5
+
+
+class TestNodeDetailsEndpoint:
+ """Test the node details endpoint."""
+
+ def test_get_artist_details(
+ self,
+ test_client: TestClient,
+ sample_artist_details: dict[str, Any],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_artist_details)
+
+ with patch.dict("explore.explore.DETAILS_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/node/1?type=artist")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["name"] == "Radiohead"
+ assert "genres" in data
+ assert "styles" in data
+
+ def test_get_release_details(self, test_client: TestClient) -> None:
+ release_data = {
+ "id": "10",
+ "name": "OK Computer",
+ "year": 1997,
+ "country": "UK",
+ "artists": ["Radiohead"],
+ "labels": ["Parlophone"],
+ "genres": ["Rock"],
+ "styles": ["Alternative Rock"],
+ }
+ mock_func = AsyncMock(return_value=release_data)
+
+ with patch.dict("explore.explore.DETAILS_DISPATCH", {"release": mock_func}):
+ response = test_client.get("/api/node/10?type=release")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["year"] == 1997
+
+ def test_get_node_not_found(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=None)
+
+ with patch.dict("explore.explore.DETAILS_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/node/nonexistent?type=artist")
+
+ assert response.status_code == 404
+
+ def test_get_node_invalid_type(self, test_client: TestClient) -> None:
+ response = test_client.get("/api/node/1?type=invalid")
+ assert response.status_code == 400
+
+ def test_get_node_service_not_ready(self, test_client: TestClient) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = None
+
+ response = test_client.get("/api/node/1?type=artist")
+ assert response.status_code == 503
+
+ explore_module.neo4j_driver = original_driver
+
+ def test_get_genre_details(self, test_client: TestClient) -> None:
+ genre_data = {"id": "Rock", "name": "Rock", "artist_count": 1000}
+ mock_func = AsyncMock(return_value=genre_data)
+
+ with patch.dict("explore.explore.DETAILS_DISPATCH", {"genre": mock_func}):
+ response = test_client.get("/api/node/Rock?type=genre")
+
+ assert response.status_code == 200
+
+ def test_get_label_details(self, test_client: TestClient) -> None:
+ label_data = {"id": "100", "name": "Warp Records", "release_count": 500}
+ mock_func = AsyncMock(return_value=label_data)
+
+ with patch.dict("explore.explore.DETAILS_DISPATCH", {"label": mock_func}):
+ response = test_client.get("/api/node/100?type=label")
+
+ assert response.status_code == 200
+
+
+class TestTrendsEndpoint:
+ """Test the trends endpoint."""
+
+ def test_trends_artist_success(
+ self,
+ test_client: TestClient,
+ sample_trends_data: list[dict[str, Any]],
+ ) -> None:
+ mock_func = AsyncMock(return_value=sample_trends_data)
+
+ with patch.dict("explore.explore.TRENDS_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/trends?name=Radiohead&type=artist")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["name"] == "Radiohead"
+ assert data["type"] == "artist"
+ assert len(data["data"]) == 5
+
+ def test_trends_genre(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[{"year": 2000, "count": 100}])
+
+ with patch.dict("explore.explore.TRENDS_DISPATCH", {"genre": mock_func}):
+ response = test_client.get("/api/trends?name=Rock&type=genre")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["type"] == "genre"
+
+ def test_trends_label(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[{"year": 1990, "count": 50}])
+
+ with patch.dict("explore.explore.TRENDS_DISPATCH", {"label": mock_func}):
+ response = test_client.get("/api/trends?name=Warp%20Records&type=label")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["type"] == "label"
+
+ def test_trends_invalid_type(self, test_client: TestClient) -> None:
+ response = test_client.get("/api/trends?name=Test&type=invalid")
+ assert response.status_code == 400
+
+ def test_trends_service_not_ready(self, test_client: TestClient) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = None
+
+ response = test_client.get("/api/trends?name=Test&type=artist")
+ assert response.status_code == 503
+
+ explore_module.neo4j_driver = original_driver
+
+ def test_trends_empty_results(self, test_client: TestClient) -> None:
+ mock_func = AsyncMock(return_value=[])
+
+ with patch.dict("explore.explore.TRENDS_DISPATCH", {"artist": mock_func}):
+ response = test_client.get("/api/trends?name=Unknown&type=artist")
+
+ assert response.status_code == 200
+ data = response.json()
+ assert data["data"] == []
+
+
+class TestBuildCategories:
+ """Test the _build_categories helper function."""
+
+ def test_build_artist_categories(self) -> None:
+ from explore.explore import _build_categories
+
+ result = {
+ "id": "1",
+ "name": "Test",
+ "release_count": 10,
+ "label_count": 3,
+ "alias_count": 1,
+ }
+ categories = _build_categories("artist", result)
+ assert len(categories) == 3
+ cat_map = {c["category"]: c for c in categories}
+ assert cat_map["releases"]["count"] == 10
+ assert cat_map["labels"]["count"] == 3
+ assert cat_map["aliases"]["count"] == 1
+
+ def test_build_genre_categories(self) -> None:
+ from explore.explore import _build_categories
+
+ result = {
+ "id": "Rock",
+ "name": "Rock",
+ "artist_count": 500,
+ "label_count": 100,
+ "style_count": 25,
+ }
+ categories = _build_categories("genre", result)
+ assert len(categories) == 3
+ cat_map = {c["category"]: c for c in categories}
+ assert cat_map["artists"]["count"] == 500
+ assert cat_map["styles"]["count"] == 25
+
+ def test_build_label_categories(self) -> None:
+ from explore.explore import _build_categories
+
+ result = {
+ "id": "100",
+ "name": "Test Label",
+ "release_count": 200,
+ "artist_count": 50,
+ }
+ categories = _build_categories("label", result)
+ assert len(categories) == 2
+
+ def test_build_unknown_type(self) -> None:
+ from explore.explore import _build_categories
+
+ categories = _build_categories("unknown", {"id": "x", "name": "x"})
+ assert categories == []
+
+
+class TestStaticFiles:
+ """Test static file serving."""
+
+ def test_index_html_served(self, test_client: TestClient) -> None:
+ response = test_client.get("/")
+ assert response.status_code == 200
+ assert "text/html" in response.headers.get("content-type", "")
+
+ def test_css_served(self, test_client: TestClient) -> None:
+ response = test_client.get("/css/styles.css")
+ assert response.status_code == 200
+
+ def test_js_files_served(self, test_client: TestClient) -> None:
+ js_files = ["js/app.js", "js/api-client.js", "js/autocomplete.js", "js/graph.js", "js/trends.js"]
+ for js_file in js_files:
+ response = test_client.get(f"/{js_file}")
+ assert response.status_code == 200, f"Failed to serve {js_file}"
+
+
+class TestGetHealthData:
+ """Test the get_health_data helper function."""
+
+ def test_health_data_when_driver_exists(self) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = MagicMock()
+
+ data = explore_module.get_health_data()
+ assert data["status"] == "healthy"
+ assert data["service"] == "explore"
+ assert "timestamp" in data
+
+ explore_module.neo4j_driver = original_driver
+
+ def test_health_data_when_driver_none(self) -> None:
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+ explore_module.neo4j_driver = None
+
+ data = explore_module.get_health_data()
+ assert data["status"] == "starting"
+
+ explore_module.neo4j_driver = original_driver
+
+
+class TestGetCacheKey:
+ """Test the _get_cache_key helper function."""
+
+ def test_cache_key_lowercases(self) -> None:
+ from explore.explore import _get_cache_key
+
+ key = _get_cache_key("Radiohead", "artist", 10)
+ assert key == ("radiohead", "artist", 10)
+
+ def test_cache_key_strips_whitespace(self) -> None:
+ from explore.explore import _get_cache_key
+
+ key = _get_cache_key(" radio ", "artist", 10)
+ assert key == ("radio", "artist", 10)
+
+
+class TestLifespan:
+ """Test the application lifespan context manager."""
+
+ @pytest.mark.asyncio
+ async def test_lifespan_startup_and_shutdown(self) -> None:
+ from explore.explore import app, lifespan
+
+ mock_driver = MagicMock()
+ mock_driver.close = AsyncMock()
+
+ with (
+ patch("explore.explore.ExploreConfig") as mock_config_class,
+ patch("explore.explore.HealthServer") as mock_health_server_class,
+ patch("explore.explore.AsyncResilientNeo4jDriver", return_value=mock_driver),
+ patch("explore.explore.create_all_indexes", new_callable=AsyncMock),
+ ):
+ mock_config = MagicMock()
+ mock_config.neo4j_address = "bolt://localhost:7687"
+ mock_config.neo4j_username = "neo4j"
+ mock_config.neo4j_password = "password"
+ mock_config_class.from_env.return_value = mock_config
+
+ mock_health_server = MagicMock()
+ mock_health_server_class.return_value = mock_health_server
+
+ import explore.explore as explore_module
+
+ original_driver = explore_module.neo4j_driver
+
+ async with lifespan(app):
+ # During lifespan, driver should be set
+ assert explore_module.neo4j_driver is mock_driver
+
+ # After lifespan, driver close should have been called
+ mock_driver.close.assert_awaited_once()
+ mock_health_server.stop.assert_called_once()
+
+ explore_module.neo4j_driver = original_driver
diff --git a/tests/explore/test_explore_ui.py b/tests/explore/test_explore_ui.py
new file mode 100644
index 0000000..d8da5e7
--- /dev/null
+++ b/tests/explore/test_explore_ui.py
@@ -0,0 +1,335 @@
+"""E2E browser tests for the Explore service UI."""
+
+import re
+
+from playwright.sync_api import Page, expect
+import pytest
+
+
+@pytest.mark.e2e
+@pytest.mark.usefixtures("test_server")
+class TestExploreUI:
+ """End-to-end tests for the Explore service web interface."""
+
+ def test_page_loads(self, page: Page, test_server: str) -> None:
+ """Test that the explore page loads successfully."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+ expect(page).to_have_title(re.compile("Explore", re.IGNORECASE))
+
+ def test_navbar_visible(self, page: Page, test_server: str) -> None:
+ """Test that the navigation bar is visible."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ navbar = page.locator("nav")
+ expect(navbar).to_be_visible(timeout=5000)
+
+ def test_search_input_visible(self, page: Page, test_server: str) -> None:
+ """Test that the search input is visible."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ search_input = page.locator("#searchInput")
+ expect(search_input).to_be_visible(timeout=5000)
+
+ def test_search_type_dropdown(self, page: Page, test_server: str) -> None:
+ """Test the search type dropdown works."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ # Find the search type button
+ type_btn = page.locator("#searchTypeBtn")
+ expect(type_btn).to_be_visible(timeout=5000)
+ expect(type_btn).to_have_text("Artist")
+
+ def test_pane_switching(self, page: Page, test_server: str) -> None:
+ """Test switching between Explore and Trends panes."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ # Explore pane should be active by default
+ explore_pane = page.locator("#explorePane")
+ expect(explore_pane).to_have_class(re.compile("active"), timeout=5000)
+
+ # Click Trends tab
+ trends_link = page.locator("[data-pane='trends']")
+ trends_link.click()
+
+ # Trends pane should now be active
+ trends_pane = page.locator("#trendsPane")
+ expect(trends_pane).to_have_class(re.compile("active"), timeout=5000)
+
+ # Click Explore tab again
+ explore_link = page.locator("[data-pane='explore']")
+ explore_link.click()
+ expect(explore_pane).to_have_class(re.compile("active"), timeout=5000)
+
+ def test_graph_placeholder_visible(self, page: Page, test_server: str) -> None:
+ """Test that the graph placeholder is shown before search."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ placeholder = page.locator("#graphPlaceholder")
+ expect(placeholder).to_be_visible(timeout=5000)
+
+ def test_health_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the health API endpoint from browser."""
+ response = page.request.get(f"{test_server}/health")
+ assert response.ok
+ data = response.json()
+ assert data["service"] == "explore"
+ assert data["status"] == "healthy"
+
+ def test_responsive_layout(self, page: Page, test_server: str) -> None:
+ """Test that the page responds to viewport changes."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ # Desktop viewport
+ page.set_viewport_size({"width": 1280, "height": 720})
+ search_input = page.locator("#searchInput")
+ expect(search_input).to_be_visible(timeout=5000)
+
+ # Mobile viewport
+ page.set_viewport_size({"width": 375, "height": 667})
+ expect(search_input).to_be_visible(timeout=5000)
+
+ def test_info_panel_hidden_by_default(self, page: Page, test_server: str) -> None:
+ """Test that the info panel is hidden before any node is clicked."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ info_panel = page.locator("#infoPanel")
+ # The panel exists but should not have the 'open' class
+ expect(info_panel).not_to_have_class(re.compile("open"), timeout=5000)
+
+
+@pytest.mark.e2e
+@pytest.mark.usefixtures("test_server")
+class TestExploreAPIEndpoints:
+ """E2E tests for Explore API endpoints."""
+
+ def test_autocomplete_artist_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the autocomplete API returns artist results."""
+ response = page.request.get(f"{test_server}/api/autocomplete?q=radio&type=artist")
+ assert response.ok
+ data = response.json()
+ assert "results" in data
+ assert isinstance(data["results"], list)
+
+ def test_autocomplete_genre_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the autocomplete API returns genre results."""
+ response = page.request.get(f"{test_server}/api/autocomplete?q=rock&type=genre")
+ assert response.ok
+ data = response.json()
+ assert "results" in data
+
+ def test_autocomplete_label_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the autocomplete API returns label results."""
+ response = page.request.get(f"{test_server}/api/autocomplete?q=warp&type=label")
+ assert response.ok
+ data = response.json()
+ assert "results" in data
+
+ def test_explore_artist_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the explore API returns artist graph data."""
+ response = page.request.get(f"{test_server}/api/explore?name=Radiohead&type=artist")
+ assert response.ok
+ data = response.json()
+ assert "center" in data
+ assert "categories" in data
+ assert data["center"]["type"] == "artist"
+ assert len(data["categories"]) == 3 # releases, labels, aliases
+
+ def test_explore_genre_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the explore API returns genre graph data."""
+ response = page.request.get(f"{test_server}/api/explore?name=Rock&type=genre")
+ assert response.ok
+ data = response.json()
+ assert data["center"]["type"] == "genre"
+ assert len(data["categories"]) == 3 # artists, labels, styles
+
+ def test_explore_label_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the explore API returns label graph data."""
+ response = page.request.get(f"{test_server}/api/explore?name=Warp%20Records&type=label")
+ assert response.ok
+ data = response.json()
+ assert data["center"]["type"] == "label"
+ assert len(data["categories"]) == 2 # releases, artists
+
+ def test_expand_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the expand API returns child nodes."""
+ response = page.request.get(f"{test_server}/api/expand?node_id=Radiohead&type=artist&category=releases")
+ assert response.ok
+ data = response.json()
+ assert "children" in data
+ assert isinstance(data["children"], list)
+ assert len(data["children"]) > 0
+
+ def test_node_details_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the node details API returns full node info."""
+ response = page.request.get(f"{test_server}/api/node/1?type=artist")
+ assert response.ok
+ data = response.json()
+ assert "name" in data
+ assert "genres" in data
+ assert isinstance(data["genres"], list)
+
+ def test_trends_endpoint(self, page: Page, test_server: str) -> None:
+ """Test the trends API returns time-series data."""
+ response = page.request.get(f"{test_server}/api/trends?name=Radiohead&type=artist")
+ assert response.ok
+ data = response.json()
+ assert data["name"] == "Radiohead"
+ assert data["type"] == "artist"
+ assert "data" in data
+ assert isinstance(data["data"], list)
+ assert len(data["data"]) > 0
+ # Verify time-series structure
+ assert "year" in data["data"][0]
+ assert "count" in data["data"][0]
+
+
+@pytest.mark.e2e
+@pytest.mark.usefixtures("test_server")
+class TestExploreSearchInteraction:
+ """E2E tests for search interaction and autocomplete UI."""
+
+ def test_search_type_switching(self, page: Page, test_server: str) -> None:
+ """Test switching between search types via dropdown."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ type_btn = page.locator("#searchTypeBtn")
+ expect(type_btn).to_have_text("Artist", timeout=5000)
+
+ # Open dropdown and click Genre
+ type_btn.click()
+ genre_item = page.locator("[data-type='genre']")
+ expect(genre_item).to_be_visible(timeout=5000)
+ genre_item.click()
+ expect(type_btn).to_have_text("Genre", timeout=5000)
+
+ # Switch to Label
+ type_btn.click()
+ label_item = page.locator("[data-type='label']")
+ expect(label_item).to_be_visible(timeout=5000)
+ label_item.click()
+ expect(type_btn).to_have_text("Label", timeout=5000)
+
+ # Switch back to Artist
+ type_btn.click()
+ artist_item = page.locator("[data-type='artist']")
+ expect(artist_item).to_be_visible(timeout=5000)
+ artist_item.click()
+ expect(type_btn).to_have_text("Artist", timeout=5000)
+
+ def test_autocomplete_shows_results(self, page: Page, test_server: str) -> None:
+ """Test that typing in search shows autocomplete results."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ search_input = page.locator("#searchInput")
+ search_input.fill("Radio")
+
+ # Wait for autocomplete debounce (300ms) and results to appear
+ dropdown = page.locator("#autocompleteDropdown")
+ expect(dropdown).to_have_class(re.compile("show"), timeout=5000)
+
+ # Should have autocomplete items
+ items = page.locator(".autocomplete-item")
+ expect(items.first).to_be_visible(timeout=5000)
+
+ def test_autocomplete_item_click_triggers_search(self, page: Page, test_server: str) -> None:
+ """Test that clicking an autocomplete item triggers a search."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ search_input = page.locator("#searchInput")
+ search_input.fill("Radio")
+
+ # Wait for autocomplete results
+ dropdown = page.locator("#autocompleteDropdown")
+ expect(dropdown).to_have_class(re.compile("show"), timeout=5000)
+
+ # Click the first result
+ first_item = page.locator(".autocomplete-item").first
+ expect(first_item).to_be_visible(timeout=5000)
+ first_item.click()
+
+ # Dropdown should close after selection
+ expect(dropdown).not_to_have_class(re.compile("show"), timeout=5000)
+
+ # Search input should have the selected name
+ expect(search_input).not_to_have_value("", timeout=5000)
+
+ def test_graph_appears_after_search(self, page: Page, test_server: str) -> None:
+ """Test that the graph appears after performing a search."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ search_input = page.locator("#searchInput")
+ search_input.fill("Radio")
+
+ # Wait for autocomplete and click first result
+ dropdown = page.locator("#autocompleteDropdown")
+ expect(dropdown).to_have_class(re.compile("show"), timeout=5000)
+ page.locator(".autocomplete-item").first.click()
+
+ # Graph SVG should have content (nodes) after search
+ svg = page.locator("#graphSvg")
+ expect(svg).to_be_visible(timeout=5000)
+
+ # Wait for graph to render - look for SVG child elements (circles/rects for nodes)
+ page.wait_for_timeout(1000) # Give D3 time to render
+ # The placeholder should be hidden after data loads
+ placeholder = page.locator("#graphPlaceholder")
+ expect(placeholder).to_be_hidden(timeout=5000)
+
+ def test_trends_pane_search(self, page: Page, test_server: str) -> None:
+ """Test searching on the Trends pane loads chart data."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ # Switch to trends pane
+ trends_link = page.locator("[data-pane='trends']")
+ trends_link.click()
+
+ trends_pane = page.locator("#trendsPane")
+ expect(trends_pane).to_have_class(re.compile("active"), timeout=5000)
+
+ # Type search query and select from autocomplete
+ search_input = page.locator("#searchInput")
+ search_input.fill("Radio")
+
+ dropdown = page.locator("#autocompleteDropdown")
+ expect(dropdown).to_have_class(re.compile("show"), timeout=5000)
+ page.locator(".autocomplete-item").first.click()
+
+ # Trends placeholder should be hidden after data loads
+ page.wait_for_timeout(1000) # Give Plotly time to render
+ placeholder = page.locator("#trendsPlaceholder")
+ expect(placeholder).to_be_hidden(timeout=5000)
+
+ def test_graph_legend_visible(self, page: Page, test_server: str) -> None:
+ """Test that the graph legend is visible on the explore pane."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ legend = page.locator("#graphLegend")
+ expect(legend).to_be_visible(timeout=5000)
+
+ # Check legend items
+ legend_items = page.locator(".legend-item")
+ expect(legend_items).to_have_count(5, timeout=5000) # Artist, Release, Label, Genre/Style, Category
+
+ def test_trends_placeholder_visible(self, page: Page, test_server: str) -> None:
+ """Test that the trends placeholder is visible before search."""
+ page.goto(test_server, wait_until="domcontentloaded", timeout=10000)
+
+ # Switch to trends pane
+ trends_link = page.locator("[data-pane='trends']")
+ trends_link.click()
+
+ placeholder = page.locator("#trendsPlaceholder")
+ expect(placeholder).to_be_visible(timeout=5000)
+
+ def test_static_css_loads(self, page: Page, test_server: str) -> None:
+ """Test that custom CSS file is served correctly."""
+ response = page.request.get(f"{test_server}/css/styles.css")
+ assert response.ok
+ assert "text/css" in response.headers.get("content-type", "")
+
+ def test_static_js_files_load(self, page: Page, test_server: str) -> None:
+ """Test that all JavaScript files are served correctly."""
+ js_files = ["js/app.js", "js/api-client.js", "js/autocomplete.js", "js/graph.js", "js/trends.js"]
+ for js_file in js_files:
+ response = page.request.get(f"{test_server}/{js_file}")
+ assert response.ok, f"Failed to load {js_file}"
diff --git a/tests/explore/test_neo4j_indexes.py b/tests/explore/test_neo4j_indexes.py
new file mode 100644
index 0000000..9978af4
--- /dev/null
+++ b/tests/explore/test_neo4j_indexes.py
@@ -0,0 +1,186 @@
+"""Tests for Explore service Neo4j index creation."""
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from explore.neo4j_indexes import INDEXES, create_all_indexes, create_index
+
+
+@pytest.fixture
+def mock_driver() -> MagicMock:
+ """Create a mock async Neo4j driver."""
+ driver = MagicMock()
+ mock_session = AsyncMock()
+
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=False)
+ mock_session.run = AsyncMock()
+
+ driver.session = MagicMock(return_value=mock_session)
+ driver.close = AsyncMock()
+ return driver
+
+
+class TestIndexDefinitions:
+ """Test that index definitions are properly configured."""
+
+ def test_indexes_not_empty(self) -> None:
+ assert len(INDEXES) > 0
+
+ def test_all_indexes_have_required_fields(self) -> None:
+ for index_def in INDEXES:
+ assert "name" in index_def
+ assert "type" in index_def
+ assert "label" in index_def
+ assert "properties" in index_def
+ assert "description" in index_def
+
+ def test_fulltext_indexes_exist(self) -> None:
+ fulltext = [i for i in INDEXES if i["type"] == "fulltext"]
+ assert len(fulltext) >= 3 # artist, release, label
+
+ def test_range_indexes_exist(self) -> None:
+ range_indexes = [i for i in INDEXES if i["type"] == "range"]
+ assert len(range_indexes) >= 4 # id indexes + year + genre + style
+
+
+class TestCreateIndex:
+ """Test the create_index function."""
+
+ @pytest.mark.asyncio
+ async def test_create_fulltext_index(self, mock_driver: MagicMock) -> None:
+ index_def: dict[str, Any] = {
+ "name": "test_fulltext",
+ "type": "fulltext",
+ "label": "Artist",
+ "properties": ["name"],
+ "description": "Test fulltext index",
+ }
+ result = await create_index(mock_driver, index_def)
+ assert result is True
+
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run.assert_called_once()
+ query = mock_session.run.call_args[0][0]
+ assert "FULLTEXT" in query
+ assert "IF NOT EXISTS" in query
+
+ @pytest.mark.asyncio
+ async def test_create_single_property_range_index(self, mock_driver: MagicMock) -> None:
+ index_def: dict[str, Any] = {
+ "name": "test_range",
+ "type": "range",
+ "label": "Release",
+ "properties": ["id"],
+ "description": "Test range index",
+ }
+ result = await create_index(mock_driver, index_def)
+ assert result is True
+
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run.assert_called_once()
+ query = mock_session.run.call_args[0][0]
+ assert "IF NOT EXISTS" in query
+ assert "FULLTEXT" not in query
+
+ @pytest.mark.asyncio
+ async def test_create_multi_property_range_index(self, mock_driver: MagicMock) -> None:
+ index_def: dict[str, Any] = {
+ "name": "test_multi",
+ "type": "range",
+ "label": "Release",
+ "properties": ["year", "country"],
+ "description": "Test multi-property index",
+ }
+ result = await create_index(mock_driver, index_def)
+ assert result is True
+
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run.assert_called_once()
+ query = mock_session.run.call_args[0][0]
+ assert "n.year" in query
+ assert "n.country" in query
+
+ @pytest.mark.asyncio
+ async def test_create_index_failure(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(side_effect=Exception("Connection refused"))
+
+ index_def: dict[str, Any] = {
+ "name": "test_fail",
+ "type": "range",
+ "label": "Artist",
+ "properties": ["id"],
+ "description": "Should fail",
+ }
+ result = await create_index(mock_driver, index_def)
+ assert result is False
+
+
+class TestCreateAllIndexes:
+ """Test the create_all_indexes function."""
+
+ @pytest.mark.asyncio
+ async def test_create_all_indexes_success(self) -> None:
+ mock_driver = MagicMock()
+ mock_session = AsyncMock()
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=False)
+ mock_session.run = AsyncMock()
+ mock_driver.session = MagicMock(return_value=mock_session)
+ mock_driver.close = AsyncMock()
+
+ with patch("explore.neo4j_indexes.AsyncGraphDatabase") as mock_gdb:
+ mock_gdb.driver.return_value = mock_driver
+ await create_all_indexes("bolt://localhost:7687", "neo4j", "password")
+
+ mock_gdb.driver.assert_called_once_with("bolt://localhost:7687", auth=("neo4j", "password"))
+ mock_driver.close.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_create_all_indexes_with_failures(self) -> None:
+ """Test that create_all_indexes counts successes and failures."""
+ call_count = 0
+
+ mock_driver = MagicMock()
+ mock_session = AsyncMock()
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=False)
+
+ async def side_effect_run(*args: Any, **kwargs: Any) -> None: # noqa: ARG001
+ nonlocal call_count
+ call_count += 1
+ # Fail every 3rd call
+ if call_count % 3 == 0:
+ raise Exception("Simulated failure")
+
+ mock_session.run = AsyncMock(side_effect=side_effect_run)
+ mock_driver.session = MagicMock(return_value=mock_session)
+ mock_driver.close = AsyncMock()
+
+ with patch("explore.neo4j_indexes.AsyncGraphDatabase") as mock_gdb:
+ mock_gdb.driver.return_value = mock_driver
+ await create_all_indexes("bolt://localhost:7687", "neo4j", "password")
+
+ # Driver should always be closed, even with failures
+ mock_driver.close.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_create_all_indexes_closes_driver_on_error(self) -> None:
+ """Test that driver is closed even when all indexes fail."""
+ mock_driver = MagicMock()
+ mock_session = AsyncMock()
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=False)
+ mock_session.run = AsyncMock(side_effect=Exception("All fail"))
+ mock_driver.session = MagicMock(return_value=mock_session)
+ mock_driver.close = AsyncMock()
+
+ with patch("explore.neo4j_indexes.AsyncGraphDatabase") as mock_gdb:
+ mock_gdb.driver.return_value = mock_driver
+ await create_all_indexes("bolt://localhost:7687", "neo4j", "password")
+
+ # Driver must be closed in finally block
+ mock_driver.close.assert_awaited_once()
diff --git a/tests/explore/test_neo4j_queries.py b/tests/explore/test_neo4j_queries.py
new file mode 100644
index 0000000..172f0c0
--- /dev/null
+++ b/tests/explore/test_neo4j_queries.py
@@ -0,0 +1,475 @@
+"""Tests for Explore service Neo4j query functions."""
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from explore.neo4j_queries import (
+ AUTOCOMPLETE_DISPATCH,
+ DETAILS_DISPATCH,
+ EXPAND_DISPATCH,
+ EXPLORE_DISPATCH,
+ TRENDS_DISPATCH,
+ _autocomplete_cache_key,
+ autocomplete_artist,
+ autocomplete_genre,
+ autocomplete_label,
+ expand_artist_aliases,
+ expand_artist_labels,
+ expand_artist_releases,
+ expand_genre_artists,
+ expand_genre_labels,
+ expand_genre_styles,
+ expand_label_artists,
+ expand_label_releases,
+ explore_artist,
+ explore_genre,
+ explore_label,
+ get_artist_details,
+ get_genre_details,
+ get_label_details,
+ get_release_details,
+ trends_artist,
+ trends_genre,
+ trends_label,
+)
+
+
+@pytest.fixture
+def mock_driver() -> MagicMock:
+ """Create a mock async Neo4j driver."""
+ driver = MagicMock()
+ mock_session = AsyncMock()
+ mock_result = AsyncMock()
+
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=False)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ mock_result.single = AsyncMock(return_value=None)
+
+ driver.session = MagicMock(return_value=mock_session)
+ return driver
+
+
+def _make_async_iterable(items: list[dict[str, Any]]) -> AsyncMock:
+ """Create an async iterable mock result from a list of dicts."""
+ mock_result = AsyncMock()
+
+ class AsyncIter:
+ def __init__(self) -> None:
+ self.items = iter(items)
+
+ def __aiter__(self) -> "AsyncIter":
+ return self
+
+ async def __anext__(self) -> dict[str, Any]:
+ try:
+ return next(self.items)
+ except StopIteration:
+ raise StopAsyncIteration from None
+
+ mock_result.__aiter__ = lambda _self: AsyncIter()
+ mock_result.single = AsyncMock(return_value=None)
+ return mock_result
+
+
+class TestDispatchTables:
+ """Test that dispatch tables are properly configured."""
+
+ def test_autocomplete_dispatch_keys(self) -> None:
+ assert set(AUTOCOMPLETE_DISPATCH.keys()) == {"artist", "genre", "label"}
+
+ def test_explore_dispatch_keys(self) -> None:
+ assert set(EXPLORE_DISPATCH.keys()) == {"artist", "genre", "label"}
+
+ def test_expand_dispatch_keys(self) -> None:
+ assert set(EXPAND_DISPATCH.keys()) == {"artist", "genre", "label"}
+ assert set(EXPAND_DISPATCH["artist"].keys()) == {"releases", "labels", "aliases"}
+ assert set(EXPAND_DISPATCH["genre"].keys()) == {"artists", "labels", "styles"}
+ assert set(EXPAND_DISPATCH["label"].keys()) == {"releases", "artists"}
+
+ def test_details_dispatch_keys(self) -> None:
+ assert set(DETAILS_DISPATCH.keys()) == {"artist", "release", "label", "genre", "style"}
+
+ def test_trends_dispatch_keys(self) -> None:
+ assert set(TRENDS_DISPATCH.keys()) == {"artist", "genre", "label"}
+
+ def test_autocomplete_dispatch_functions(self) -> None:
+ assert AUTOCOMPLETE_DISPATCH["artist"] is autocomplete_artist
+ assert AUTOCOMPLETE_DISPATCH["genre"] is autocomplete_genre
+ assert AUTOCOMPLETE_DISPATCH["label"] is autocomplete_label
+
+ def test_explore_dispatch_functions(self) -> None:
+ assert EXPLORE_DISPATCH["artist"] is explore_artist
+ assert EXPLORE_DISPATCH["genre"] is explore_genre
+ assert EXPLORE_DISPATCH["label"] is explore_label
+
+ def test_expand_dispatch_functions(self) -> None:
+ assert EXPAND_DISPATCH["artist"]["releases"] is expand_artist_releases
+ assert EXPAND_DISPATCH["artist"]["labels"] is expand_artist_labels
+ assert EXPAND_DISPATCH["artist"]["aliases"] is expand_artist_aliases
+ assert EXPAND_DISPATCH["genre"]["artists"] is expand_genre_artists
+ assert EXPAND_DISPATCH["genre"]["labels"] is expand_genre_labels
+ assert EXPAND_DISPATCH["genre"]["styles"] is expand_genre_styles
+ assert EXPAND_DISPATCH["label"]["releases"] is expand_label_releases
+ assert EXPAND_DISPATCH["label"]["artists"] is expand_label_artists
+
+
+class TestAutocompleteQueries:
+ """Test autocomplete query functions."""
+
+ @pytest.mark.asyncio
+ async def test_autocomplete_artist(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "1", "name": "Radiohead", "score": 9.5}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await autocomplete_artist(mock_driver, "radio", 10)
+ assert len(results) == 1
+ assert results[0]["name"] == "Radiohead"
+
+ @pytest.mark.asyncio
+ async def test_autocomplete_label(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "100", "name": "Warp Records", "score": 9.0}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await autocomplete_label(mock_driver, "warp", 10)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_autocomplete_genre(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "Rock", "name": "Rock", "score": 1.0}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await autocomplete_genre(mock_driver, "rock", 10)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_autocomplete_empty(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable([]))
+
+ results = await autocomplete_artist(mock_driver, "zzzzz", 10)
+ assert results == []
+
+
+class TestExploreQueries:
+ """Test explore query functions."""
+
+ @pytest.mark.asyncio
+ async def test_explore_artist_found(self, mock_driver: MagicMock) -> None:
+ expected = {"id": "1", "name": "Radiohead", "release_count": 42, "label_count": 5, "alias_count": 2}
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await explore_artist(mock_driver, "Radiohead")
+ assert result is not None
+ assert result["name"] == "Radiohead"
+ assert result["release_count"] == 42
+
+ @pytest.mark.asyncio
+ async def test_explore_artist_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await explore_artist(mock_driver, "NonExistent")
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_explore_genre(self, mock_driver: MagicMock) -> None:
+ expected = {"id": "Rock", "name": "Rock", "artist_count": 1000, "label_count": 200, "style_count": 50}
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await explore_genre(mock_driver, "Rock")
+ assert result is not None
+ assert result["artist_count"] == 1000
+
+ @pytest.mark.asyncio
+ async def test_explore_genre_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await explore_genre(mock_driver, "NonExistent")
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_explore_label(self, mock_driver: MagicMock) -> None:
+ expected = {"id": "100", "name": "Warp Records", "release_count": 500, "artist_count": 120}
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await explore_label(mock_driver, "Warp Records")
+ assert result is not None
+ assert result["release_count"] == 500
+
+ @pytest.mark.asyncio
+ async def test_explore_label_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await explore_label(mock_driver, "NonExistent")
+ assert result is None
+
+
+class TestExpandQueries:
+ """Test expand query functions."""
+
+ @pytest.mark.asyncio
+ async def test_expand_artist_releases(self, mock_driver: MagicMock) -> None:
+ expected = [
+ {"id": "10", "name": "OK Computer", "type": "release", "year": 1997},
+ {"id": "11", "name": "Kid A", "type": "release", "year": 2000},
+ ]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_artist_releases(mock_driver, "Radiohead", 50)
+ assert len(results) == 2
+
+ @pytest.mark.asyncio
+ async def test_expand_artist_labels(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "200", "name": "Parlophone", "type": "label", "release_count": 10}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_artist_labels(mock_driver, "Radiohead", 50)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_expand_artist_aliases(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "5", "name": "On a Friday", "type": "artist"}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_artist_aliases(mock_driver, "Radiohead", 50)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_expand_genre_artists(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "1", "name": "Radiohead", "type": "artist"}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_genre_artists(mock_driver, "Rock", 50)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_expand_genre_labels(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable([]))
+
+ results = await expand_genre_labels(mock_driver, "Rock", 50)
+ assert results == []
+
+ @pytest.mark.asyncio
+ async def test_expand_genre_styles(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "Alternative Rock", "name": "Alternative Rock", "type": "style", "artist_count": 500}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_genre_styles(mock_driver, "Rock", 50)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_expand_label_releases(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "10", "name": "OK Computer", "type": "release", "year": 1997}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_label_releases(mock_driver, "Parlophone", 50)
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_expand_label_artists(self, mock_driver: MagicMock) -> None:
+ expected = [{"id": "1", "name": "Radiohead", "type": "artist", "release_count": 10}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await expand_label_artists(mock_driver, "Parlophone", 50)
+ assert len(results) == 1
+
+
+class TestNodeDetailsQueries:
+ """Test node details query functions."""
+
+ @pytest.mark.asyncio
+ async def test_get_artist_details_found(self, mock_driver: MagicMock) -> None:
+ expected = {
+ "id": "1",
+ "name": "Radiohead",
+ "genres": ["Rock", "Electronic"],
+ "styles": ["Alternative Rock"],
+ "release_count": 42,
+ "groups": [],
+ }
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_artist_details(mock_driver, "1")
+ assert result is not None
+ assert result["name"] == "Radiohead"
+ assert "genres" in result
+
+ @pytest.mark.asyncio
+ async def test_get_artist_details_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_artist_details(mock_driver, "nonexistent")
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_get_release_details(self, mock_driver: MagicMock) -> None:
+ expected = {
+ "id": "10",
+ "name": "OK Computer",
+ "year": 1997,
+ "country": "UK",
+ "artists": ["Radiohead"],
+ "labels": ["Parlophone"],
+ "genres": ["Rock"],
+ "styles": ["Alternative Rock"],
+ }
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_release_details(mock_driver, "10")
+ assert result is not None
+ assert result["year"] == 1997
+
+ @pytest.mark.asyncio
+ async def test_get_label_details(self, mock_driver: MagicMock) -> None:
+ expected = {"id": "100", "name": "Warp Records", "release_count": 500}
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_label_details(mock_driver, "100")
+ assert result is not None
+ assert result["release_count"] == 500
+
+ @pytest.mark.asyncio
+ async def test_get_genre_details(self, mock_driver: MagicMock) -> None:
+ expected = {"id": "Rock", "name": "Rock", "artist_count": 1000}
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=expected)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_genre_details(mock_driver, "Rock")
+ assert result is not None
+ assert result["artist_count"] == 1000
+
+ @pytest.mark.asyncio
+ async def test_get_release_details_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_release_details(mock_driver, "nonexistent")
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_get_label_details_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_label_details(mock_driver, "nonexistent")
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_get_genre_details_not_found(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_result = AsyncMock()
+ mock_result.single = AsyncMock(return_value=None)
+ mock_session.run = AsyncMock(return_value=mock_result)
+
+ result = await get_genre_details(mock_driver, "nonexistent")
+ assert result is None
+
+
+class TestTrendsQueries:
+ """Test trends query functions."""
+
+ @pytest.mark.asyncio
+ async def test_trends_artist(self, mock_driver: MagicMock) -> None:
+ expected = [
+ {"year": 1993, "count": 1},
+ {"year": 1997, "count": 1},
+ {"year": 2000, "count": 1},
+ ]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await trends_artist(mock_driver, "Radiohead")
+ assert len(results) == 3
+
+ @pytest.mark.asyncio
+ async def test_trends_genre(self, mock_driver: MagicMock) -> None:
+ expected = [{"year": 2000, "count": 100}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await trends_genre(mock_driver, "Rock")
+ assert len(results) == 1
+
+ @pytest.mark.asyncio
+ async def test_trends_label(self, mock_driver: MagicMock) -> None:
+ expected = [{"year": 1990, "count": 50}, {"year": 2000, "count": 100}]
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable(expected))
+
+ results = await trends_label(mock_driver, "Warp Records")
+ assert len(results) == 2
+
+ @pytest.mark.asyncio
+ async def test_trends_empty(self, mock_driver: MagicMock) -> None:
+ mock_session = mock_driver.session().__aenter__.return_value
+ mock_session.run = AsyncMock(return_value=_make_async_iterable([]))
+
+ results = await trends_artist(mock_driver, "Unknown")
+ assert results == []
+
+
+class TestAutocompleteCacheKey:
+ """Test the _autocomplete_cache_key helper."""
+
+ def test_cache_key_lowercases_query(self) -> None:
+ result = _autocomplete_cache_key("Radiohead", "artist", 10)
+ assert result == ("radiohead", "artist", 10)
+
+ def test_cache_key_preserves_type_and_limit(self) -> None:
+ result = _autocomplete_cache_key("rock", "genre", 25)
+ assert result == ("rock", "genre", 25)
+
+ def test_cache_key_same_inputs_same_output(self) -> None:
+ result1 = _autocomplete_cache_key("test", "label", 5)
+ result2 = _autocomplete_cache_key("test", "label", 5)
+ assert result1 == result2
diff --git a/uv.lock b/uv.lock
index 98bcac9..c87b31b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -24,6 +24,7 @@ members = [
"discogsography-common",
"discogsography-dashboard",
"discogsography-discovery",
+ "discogsography-explore",
"discogsography-extractor",
"discogsography-graphinator",
"discogsography-tableinator",
@@ -412,6 +413,7 @@ all = [
{ name = "onnx", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "onnxruntime", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "optimum", extra = ["onnxruntime"], marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "orjson", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "pandas", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "pika", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "playwright", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
@@ -434,6 +436,7 @@ all = [
{ name = "sentence-transformers", extra = ["onnx"], marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "slowapi", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "sqlalchemy", extra = ["asyncio"], marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "structlog", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "types-psutil", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "types-tqdm", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "types-xmltodict", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
@@ -493,6 +496,15 @@ discovery = [
{ name = "uvicorn", extra = ["standard"], marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
{ name = "websockets", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
]
+explore = [
+ { name = "fastapi", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "neo4j", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "orjson", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "pydantic", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "python-multipart", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "structlog", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "uvicorn", extra = ["standard"], marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+]
graphinator = [
{ name = "neo4j", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
]
@@ -537,9 +549,10 @@ requires-dist = [
{ name = "bandit", marker = "extra == 'dev'", specifier = ">=1.7.0" },
{ name = "black", marker = "extra == 'dev'", specifier = ">=24.0.0" },
{ name = "dict-hash", specifier = ">=1.1.0" },
- { name = "discogsography", extras = ["dashboard", "discovery", "pyextractor", "graphinator", "tableinator", "dev", "utilities"], marker = "extra == 'all'" },
+ { name = "discogsography", extras = ["dashboard", "discovery", "explore", "pyextractor", "graphinator", "tableinator", "dev", "utilities"], marker = "extra == 'all'" },
{ name = "fastapi", marker = "extra == 'dashboard'", specifier = ">=0.115.6" },
{ name = "fastapi", marker = "extra == 'discovery'", specifier = ">=0.115.6" },
+ { name = "fastapi", marker = "extra == 'explore'", specifier = ">=0.115.6" },
{ name = "httpx", marker = "extra == 'dashboard'", specifier = ">=0.27.0" },
{ name = "httpx", marker = "extra == 'discovery'", specifier = ">=0.27.0" },
{ name = "isort", marker = "extra == 'dev'", specifier = ">=5.13.0" },
@@ -548,6 +561,7 @@ requires-dist = [
{ name = "neo4j", specifier = ">=5.0.0" },
{ name = "neo4j", marker = "extra == 'dashboard'", specifier = ">=5.15.0" },
{ name = "neo4j", marker = "extra == 'discovery'", specifier = ">=5.15.0" },
+ { name = "neo4j", marker = "extra == 'explore'", specifier = ">=5.15.0" },
{ name = "neo4j", marker = "extra == 'graphinator'", specifier = ">=5.15.0" },
{ name = "networkx", marker = "extra == 'discovery'", specifier = ">=3.2.1" },
{ name = "numpy", marker = "extra == 'discovery'", specifier = ">=1.26.0" },
@@ -555,6 +569,7 @@ requires-dist = [
{ name = "onnxruntime", marker = "extra == 'discovery'", specifier = ">=1.16.0" },
{ name = "optimum", extras = ["onnxruntime"], marker = "extra == 'discovery'", specifier = ">=1.13.0" },
{ name = "orjson", specifier = ">=3.9.0" },
+ { name = "orjson", marker = "extra == 'explore'", specifier = ">=3.9.0" },
{ name = "pandas", marker = "extra == 'discovery'", specifier = ">=2.1.0" },
{ name = "pika", specifier = ">=1.3.0" },
{ name = "pika", marker = "extra == 'pyextractor'", specifier = ">=1.3.0" },
@@ -570,6 +585,7 @@ requires-dist = [
{ name = "psycopg", extras = ["binary"], marker = "extra == 'tableinator'", specifier = ">=3.1.0" },
{ name = "pydantic", marker = "extra == 'dashboard'", specifier = ">=2.10.5" },
{ name = "pydantic", marker = "extra == 'discovery'", specifier = ">=2.10.5" },
+ { name = "pydantic", marker = "extra == 'explore'", specifier = ">=2.10.5" },
{ name = "pytest", marker = "extra == 'dev'", specifier = ">=7.4.0" },
{ name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24.0" },
{ name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.1.0" },
@@ -577,6 +593,7 @@ requires-dist = [
{ name = "pytest-timeout", marker = "extra == 'dev'", specifier = ">=2.4.0" },
{ name = "python-multipart", marker = "extra == 'dashboard'", specifier = ">=0.0.20" },
{ name = "python-multipart", marker = "extra == 'discovery'", specifier = ">=0.0.20" },
+ { name = "python-multipart", marker = "extra == 'explore'", specifier = ">=0.0.20" },
{ name = "redis", extras = ["hiredis"], specifier = ">=6.2.0" },
{ name = "redis", extras = ["hiredis"], marker = "extra == 'discovery'", specifier = ">=5.0.0" },
{ name = "requests", marker = "extra == 'pyextractor'", specifier = ">=2.31.0" },
@@ -587,17 +604,19 @@ requires-dist = [
{ name = "slowapi", marker = "extra == 'discovery'", specifier = ">=0.1.9" },
{ name = "sqlalchemy", extras = ["asyncio"], marker = "extra == 'discovery'", specifier = ">=2.0.0" },
{ name = "structlog", specifier = ">=24.0.0" },
+ { name = "structlog", marker = "extra == 'explore'", specifier = ">=24.0.0" },
{ name = "tqdm", specifier = ">=4.65.0" },
{ name = "types-psutil", marker = "extra == 'dev'", specifier = ">=6.1.0.20241102" },
{ name = "types-tqdm", marker = "extra == 'dev'", specifier = ">=4.67.0.20250516" },
{ name = "types-xmltodict", marker = "extra == 'dev'", specifier = ">=0.14.0.20241009" },
{ name = "uvicorn", extras = ["standard"], marker = "extra == 'dashboard'", specifier = ">=0.34.0" },
{ name = "uvicorn", extras = ["standard"], marker = "extra == 'discovery'", specifier = ">=0.34.0" },
+ { name = "uvicorn", extras = ["standard"], marker = "extra == 'explore'", specifier = ">=0.34.0" },
{ name = "websockets", marker = "extra == 'dashboard'", specifier = ">=14.2" },
{ name = "websockets", marker = "extra == 'discovery'", specifier = ">=14.2" },
{ name = "xmltodict", marker = "extra == 'pyextractor'", specifier = ">=0.13.0" },
]
-provides-extras = ["dashboard", "pyextractor", "graphinator", "tableinator", "dev", "utilities", "discovery", "all"]
+provides-extras = ["dashboard", "pyextractor", "graphinator", "tableinator", "dev", "utilities", "explore", "discovery", "all"]
[package.metadata.requires-dev]
dev = [
@@ -743,6 +762,31 @@ requires-dist = [
{ name = "websockets", specifier = ">=14.2" },
]
+[[package]]
+name = "discogsography-explore"
+version = "0.1.0"
+source = { editable = "explore" }
+dependencies = [
+ { name = "fastapi", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "neo4j", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "orjson", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "pydantic", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "python-multipart", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "structlog", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+ { name = "uvicorn", extra = ["standard"], marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+]
+
+[package.metadata]
+requires-dist = [
+ { name = "fastapi", specifier = ">=0.115.6" },
+ { name = "neo4j", specifier = ">=5.15.0" },
+ { name = "orjson", specifier = ">=3.9.0" },
+ { name = "pydantic", specifier = ">=2.10.5" },
+ { name = "python-multipart", specifier = ">=0.0.20" },
+ { name = "structlog", specifier = ">=24.0.0" },
+ { name = "uvicorn", extras = ["standard"], specifier = ">=0.34.0" },
+]
+
[[package]]
name = "discogsography-extractor"
version = "0.1.0"
@@ -2779,7 +2823,7 @@ dependencies = [
{ name = "typing-extensions", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'x86_64' and sys_platform == 'darwin') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
]
wheels = [
- { url = "https://files.pythonhosted.org/packages/a4/1b/af5fccb50c341bd69dc016769503cb0857c1423fbe9343410dfeb65240f2/torch-2.10.0-1-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:7350f6652dfd761f11f9ecb590bfe95b573e2961f7a242eccb3c8e78348d26fe", size = 79498248, upload-time = "2026-02-06T17:37:31.982Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/23/2c9fe0c9c27f7f6cb865abcea8a4568f29f00acaeadfc6a37f6801f84cb4/torch-2.10.0-2-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:e521c9f030a3774ed770a9c011751fb47c4d12029a3d6522116e48431f2ff89e", size = 79498254, upload-time = "2026-02-10T21:44:44.095Z" },
{ url = "https://files.pythonhosted.org/packages/c9/6f/f2e91e34e3fcba2e3fc8d8f74e7d6c22e74e480bbd1db7bc8900fdf3e95c/torch-2.10.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:5c4d217b14741e40776dd7074d9006fd28b8a97ef5654db959d8635b2fe5f29b", size = 146004247, upload-time = "2026-01-21T16:24:29.335Z" },
{ url = "https://files.pythonhosted.org/packages/98/fb/5160261aeb5e1ee12ee95fe599d0541f7c976c3701d607d8fc29e623229f/torch-2.10.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:6b71486353fce0f9714ca0c9ef1c850a2ae766b409808acd58e9678a3edb7738", size = 915716445, upload-time = "2026-01-21T16:22:45.353Z" },
{ url = "https://files.pythonhosted.org/packages/1a/0b/39929b148f4824bc3ad6f9f72a29d4ad865bcf7ebfc2fa67584773e083d2/torch-2.10.0-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:3202429f58309b9fa96a614885eace4b7995729f44beb54d3e4a47773649d382", size = 79851305, upload-time = "2026-01-21T16:24:09.209Z" },