Skip to content

Commit 5ac1044

Browse files
Robbie1977Robbie1977
authored
Merge pull request #29 from VirtualFlyBrain/dev
Cache Improvements
2 parents 23a5ee0 + f4b8cad commit 5ac1044

15 files changed

Lines changed: 2486 additions & 56 deletions

‎.github/workflows/performance-test.yml‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
name: Performance Test
2+
3+
on:
4+
push:
5+
branches: [ main, dev ]
6+
pull_request:
7+
branches: [ main, dev ]
8+
workflow_dispatch: # Enables manual triggering
9+
schedule:
10+
- cron: '0 2 * * *' # Runs daily at 2 AM UTC
11+
12+
jobs:
13+
performance:
14+
name: "Performance Test"
15+
runs-on: ubuntu-latest
16+
timeout-minutes: 60 # Set a timeout to prevent jobs from running indefinitely
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@v4
23+
with:
24+
python-version: '3.8'
25+
26+
- name: Install dependencies
27+
run: |
28+
python -m pip install --upgrade pip
29+
python -m pip install --upgrade -r requirements.txt
30+
python -m pip install .
31+
32+
- name: Run Performance Test
33+
run: |
34+
export PYTHONPATH=$PYTHONPATH:$PWD/
35+
echo "Running performance test for term info queries..."
36+
python -m unittest -v src.test.term_info_queries_test.TermInfoQueriesTest.test_term_info_performance 2>&1 | tee performance_test_output.log
37+
continue-on-error: true # Continue even if performance thresholds are exceeded
38+
39+
- name: Create Performance Report
40+
if: always() # Always run this step, even if the test fails
41+
run: |
42+
# Create performance.md file
43+
cat > performance.md << EOF
44+
# VFBquery Performance Test Results
45+
46+
**Test Date:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')
47+
**Git Commit:** ${{ github.sha }}
48+
**Branch:** ${{ github.ref_name }}
49+
**Workflow Run:** ${{ github.run_id }}
50+
51+
## Test Overview
52+
53+
This performance test measures the execution time of VFB term info queries for specific terms:
54+
55+
- **FBbt_00003748**: mushroom body (anatomical class)
56+
- **VFB_00101567**: individual anatomy data
57+
58+
## Performance Thresholds
59+
60+
- Maximum single query time: 2 seconds
61+
- Maximum total time for both queries: 4 seconds
62+
63+
## Test Results
64+
65+
```
66+
$(cat performance_test_output.log)
67+
```
68+
69+
## Summary
70+
71+
EOF
72+
73+
# Extract timing information from the test output
74+
if grep -q "Performance Test Results:" performance_test_output.log; then
75+
echo "✅ **Test Status**: Performance test completed" >> performance.md
76+
echo "" >> performance.md
77+
78+
# Extract timing data
79+
if grep -q "FBbt_00003748 query took:" performance_test_output.log; then
80+
TIMING1=$(grep "FBbt_00003748 query took:" performance_test_output.log | sed 's/.*took: \([0-9.]*\) seconds.*/\1/')
81+
echo "- **FBbt_00003748 Query Time**: ${TIMING1} seconds" >> performance.md
82+
fi
83+
84+
if grep -q "VFB_00101567 query took:" performance_test_output.log; then
85+
TIMING2=$(grep "VFB_00101567 query took:" performance_test_output.log | sed 's/.*took: \([0-9.]*\) seconds.*/\1/')
86+
echo "- **VFB_00101567 Query Time**: ${TIMING2} seconds" >> performance.md
87+
fi
88+
89+
if grep -q "Total time for both queries:" performance_test_output.log; then
90+
TOTAL_TIME=$(grep "Total time for both queries:" performance_test_output.log | sed 's/.*queries: \([0-9.]*\) seconds.*/\1/')
91+
echo "- **Total Query Time**: ${TOTAL_TIME} seconds" >> performance.md
92+
fi
93+
94+
# Check if test passed or failed
95+
if grep -q "OK" performance_test_output.log; then
96+
echo "" >> performance.md
97+
echo "🎉 **Result**: All performance thresholds met!" >> performance.md
98+
elif grep -q "FAILED" performance_test_output.log; then
99+
echo "" >> performance.md
100+
echo "⚠️ **Result**: Some performance thresholds exceeded or test failed" >> performance.md
101+
fi
102+
else
103+
echo "❌ **Test Status**: Performance test failed to run properly" >> performance.md
104+
fi
105+
106+
echo "" >> performance.md
107+
echo "---" >> performance.md
108+
echo "*Last updated: $(date -u '+%Y-%m-%d %H:%M:%S UTC')*" >> performance.md
109+
110+
# Also add to GitHub step summary
111+
echo "## Performance Test Report" >> $GITHUB_STEP_SUMMARY
112+
echo "Performance results have been saved to performance.md" >> $GITHUB_STEP_SUMMARY
113+
echo "" >> $GITHUB_STEP_SUMMARY
114+
cat performance.md >> $GITHUB_STEP_SUMMARY
115+
116+
- name: Commit Performance Report
117+
if: always()
118+
run: |
119+
git config --local user.email "action@github.com"
120+
git config --local user.name "GitHub Action"
121+
git add performance.md
122+
git diff --staged --quiet || git commit -m "Update performance test results [skip ci]"
123+
124+
- name: Push Performance Report
125+
if: always()
126+
uses: ad-m/github-push-action@master
127+
with:
128+
github_token: ${{ secrets.GITHUB_TOKEN }}
129+
branch: ${{ github.ref }}

‎CACHING.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# VFBquery Caching Guide
2+
3+
VFBquery includes intelligent caching for optimal performance. Caching is **enabled by default** with production-ready settings.
4+
5+
## Default Behavior
6+
7+
VFBquery automatically enables caching when imported:
8+
9+
```python
10+
import vfbquery as vfb
11+
12+
# Caching is already active with optimal settings:
13+
# - 3-month cache duration
14+
# - 2GB memory cache with LRU eviction
15+
# - Persistent disk storage
16+
# - Zero configuration required
17+
18+
result = vfb.get_term_info('FBbt_00003748') # Cached automatically
19+
```
20+
21+
## Runtime Configuration
22+
23+
Adjust cache settings while your application is running:
24+
25+
```python
26+
import vfbquery as vfb
27+
28+
# Modify cache duration
29+
vfb.set_cache_ttl(720) # 1 month
30+
vfb.set_cache_ttl(24) # 1 day
31+
32+
# Adjust memory limits
33+
vfb.set_cache_memory_limit(512) # 512MB
34+
vfb.set_cache_max_items(5000) # 5K items
35+
36+
# Toggle disk persistence
37+
vfb.disable_disk_cache() # Memory-only
38+
vfb.enable_disk_cache() # Restore persistence
39+
```
40+
41+
### Environment Control
42+
43+
Disable caching globally if needed:
44+
45+
```bash
46+
export VFBQUERY_CACHE_ENABLED=false
47+
```
48+
49+
## Performance Benefits
50+
51+
VFBquery caching provides significant performance improvements:
52+
53+
```python
54+
import vfbquery as vfb
55+
56+
# First query: builds cache (~1-2 seconds)
57+
result1 = vfb.get_term_info('FBbt_00003748')
58+
59+
# Subsequent queries: served from cache (<0.1 seconds)
60+
result2 = vfb.get_term_info('FBbt_00003748') # 54,000x faster!
61+
```
62+
63+
**Typical Performance:**
64+
65+
- First query: 1-2 seconds
66+
- Cached queries: <0.1 seconds
67+
- Speedup: Up to 54,000x for complex queries
68+
69+
## Monitoring Cache Performance
70+
71+
```python
72+
import vfbquery as vfb
73+
74+
# Get cache statistics
75+
stats = vfb.get_vfbquery_cache_stats()
76+
print(f"Hit rate: {stats['hit_rate_percent']}%")
77+
print(f"Memory used: {stats['memory_cache_size_mb']}MB")
78+
print(f"Cache items: {stats['memory_cache_items']}")
79+
80+
# Get current configuration
81+
config = vfb.get_cache_config()
82+
print(f"TTL: {config['cache_ttl_hours']} hours")
83+
print(f"Memory limit: {config['memory_cache_size_mb']}MB")
84+
```
85+
86+
## Usage Examples
87+
88+
### Production Applications
89+
90+
```python
91+
import vfbquery as vfb
92+
93+
# Caching is enabled automatically with optimal defaults
94+
# Adjust only if your application has specific needs
95+
96+
# Example: Long-running server with limited memory
97+
vfb.set_cache_memory_limit(512) # 512MB limit
98+
vfb.set_cache_ttl(168) # 1 week TTL
99+
```
100+
101+
### Jupyter Notebooks
102+
103+
```python
104+
import vfbquery as vfb
105+
106+
# Caching works automatically in notebooks
107+
# Data persists between kernel restarts
108+
109+
result = vfb.get_term_info('FBbt_00003748') # Fast on repeated runs
110+
instances = vfb.get_instances('FBbt_00003748') # Cached automatically
111+
```
112+
113+
## Benefits
114+
115+
- **Dramatic Performance**: 54,000x speedup for repeated queries
116+
- **Zero Configuration**: Works out of the box with optimal settings
117+
- **Persistent Storage**: Cache survives Python restarts
118+
- **Memory Efficient**: LRU eviction prevents memory bloat
119+
- **Multi-layer Caching**: Optimizes SOLR queries, parsing, and results
120+
- **Production Ready**: 3-month TTL matches VFB_connect behavior
121+
122+
## Best Practices
123+
124+
- **Monitor performance**: Use `get_vfbquery_cache_stats()` regularly
125+
- **Adjust for your use case**: Tune memory limits for long-running applications
126+
- **Consider data freshness**: Shorter TTL for frequently changing data
127+
- **Disable when needed**: Use environment variable if caching isn't desired

‎README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -97,25 +97,25 @@ vfb.get_term_info('FBbt_00003748')
9797
"id": "VFB_00102107",
9898
"label": "[ME on JRC2018Unisex adult brain](VFB_00102107)",
9999
"tags": "Nervous_system|Adult|Visual_system|Synaptic_neuropil_domain",
100-
"thumbnail": "[![ME on JRC2018Unisex adult brain aligned to JRC2018U](http://www.virtualflybrain.org/data/VFB/i/0010/2107/VFB_00101567/thumbnail.png 'ME on JRC2018Unisex adult brain aligned to JRC2018U')](VFB_00101567,VFB_00102107)"
100+
"thumbnail": "[![ME on JRC2018Unisex adult brain aligned to JRC2018Unisex](http://www.virtualflybrain.org/data/VFB/i/0010/2107/VFB_00101567/thumbnail.png 'ME on JRC2018Unisex adult brain aligned to JRC2018Unisex')](VFB_00101567,VFB_00102107)"
101101
},
102102
{
103103
"id": "VFB_00101385",
104104
"label": "[ME%28R%29 on JRC_FlyEM_Hemibrain](VFB_00101385)",
105105
"tags": "Nervous_system|Adult|Visual_system|Synaptic_neuropil_domain",
106-
"thumbnail": "[![ME%28R%29 on JRC_FlyEM_Hemibrain aligned to JRCFIB2018Fum](http://www.virtualflybrain.org/data/VFB/i/0010/1385/VFB_00101384/thumbnail.png 'ME(R) on JRC_FlyEM_Hemibrain aligned to JRCFIB2018Fum')](VFB_00101384,VFB_00101385)"
106+
"thumbnail": "[![ME(R) on JRC_FlyEM_Hemibrain aligned to JRC_FlyEM_Hemibrain](http://www.virtualflybrain.org/data/VFB/i/0010/1385/VFB_00101384/thumbnail.png 'ME(R) on JRC_FlyEM_Hemibrain aligned to JRC_FlyEM_Hemibrain')](VFB_00101384,VFB_00101385)"
107107
},
108108
{
109109
"id": "VFB_00030810",
110110
"label": "[medulla on adult brain template Ito2014](VFB_00030810)",
111-
"tags": "Nervous_system|Visual_system|Adult|Synaptic_neuropil_domain",
111+
"tags": "Nervous_system|Adult|Visual_system|Synaptic_neuropil_domain",
112112
"thumbnail": "[![medulla on adult brain template Ito2014 aligned to adult brain template Ito2014](http://www.virtualflybrain.org/data/VFB/i/0003/0810/VFB_00030786/thumbnail.png 'medulla on adult brain template Ito2014 aligned to adult brain template Ito2014')](VFB_00030786,VFB_00030810)"
113113
},
114114
{
115115
"id": "VFB_00030624",
116116
"label": "[medulla on adult brain template JFRC2](VFB_00030624)",
117-
"tags": "Nervous_system|Visual_system|Adult|Synaptic_neuropil_domain",
118-
"thumbnail": "[![medulla on adult brain template JFRC2 aligned to JFRC2](http://www.virtualflybrain.org/data/VFB/i/0003/0624/VFB_00017894/thumbnail.png 'medulla on adult brain template JFRC2 aligned to JFRC2')](VFB_00017894,VFB_00030624)"
117+
"tags": "Nervous_system|Adult|Visual_system|Synaptic_neuropil_domain",
118+
"thumbnail": "[![medulla on adult brain template JFRC2 aligned to adult brain template JFRC2](http://www.virtualflybrain.org/data/VFB/i/0003/0624/VFB_00017894/thumbnail.png 'medulla on adult brain template JFRC2 aligned to adult brain template JFRC2')](VFB_00017894,VFB_00030624)"
119119
}
120120
]
121121
},
@@ -1292,4 +1292,4 @@ vfb.get_templates(return_dataframe=False)
12921292
],
12931293
"count": 10
12941294
}
1295-
```
1295+
```

‎performance.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# VFBquery Performance Test Results
2+
3+
**Test Date:** 2025-09-10 17:17:58 UTC
4+
**Git Commit:** 969a842bbe07ad6e7631c8598ce5ec96f2ee493a
5+
**Branch:** dev
6+
**Workflow Run:** 17621490396
7+
8+
## Test Overview
9+
10+
This performance test measures the execution time of VFB term info queries for specific terms:
11+
12+
- **FBbt_00003748**: mushroom body (anatomical class)
13+
- **VFB_00101567**: individual anatomy data
14+
15+
## Performance Thresholds
16+
17+
- Maximum single query time: 2 seconds
18+
- Maximum total time for both queries: 4 seconds
19+
20+
## Test Results
21+
22+
23+
24+
## Summary
25+
26+
✅ **Test Status**: Performance test completed
27+
28+
- **FBbt_00003748 Query Time**: 1.2426 seconds
29+
- **VFB_00101567 Query Time**: 0.9094 seconds
30+
- **Total Query Time**: 2.1520 seconds
31+
32+
🎉 **Result**: All performance thresholds met!
33+
34+
---
35+
*Last updated: 2025-09-10 17:17:58 UTC*

‎src/test/term_info_queries_test.py‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,64 @@ def test_term_info_serialization_pub(self):
524524
self.assertFalse("filemeta" in serialized)
525525
self.assertFalse("template" in serialized)
526526

527+
def test_term_info_performance(self):
528+
"""
529+
Performance test for specific term info queries.
530+
Tests the execution time for FBbt_00003748 and VFB_00101567.
531+
"""
532+
import vfbquery as vfb
533+
534+
# Test performance for FBbt_00003748 (mushroom body)
535+
start_time = time.time()
536+
result_1 = vfb.get_term_info('FBbt_00003748')
537+
duration_1 = time.time() - start_time
538+
539+
# Test performance for VFB_00101567 (individual anatomy)
540+
start_time = time.time()
541+
result_2 = vfb.get_term_info('VFB_00101567')
542+
duration_2 = time.time() - start_time
543+
544+
# Print performance metrics for GitHub Actions logs
545+
print(f"\n" + "="*50)
546+
print(f"Performance Test Results:")
547+
print(f"="*50)
548+
print(f"FBbt_00003748 query took: {duration_1:.4f} seconds")
549+
print(f"VFB_00101567 query took: {duration_2:.4f} seconds")
550+
print(f"Total time for both queries: {duration_1 + duration_2:.4f} seconds")
551+
552+
# Performance categories
553+
total_time = duration_1 + duration_2
554+
if total_time < 1.0:
555+
performance_level = "🟢 Excellent (< 1 second)"
556+
elif total_time < 2.0:
557+
performance_level = "🟡 Good (1-2 seconds)"
558+
elif total_time < 4.0:
559+
performance_level = "🟠 Acceptable (2-4 seconds)"
560+
else:
561+
performance_level = "🔴 Slow (> 4 seconds)"
562+
563+
print(f"Performance Level: {performance_level}")
564+
print(f"="*50)
565+
566+
# Basic assertions to ensure the queries succeeded
567+
self.assertIsNotNone(result_1, "FBbt_00003748 query returned None")
568+
self.assertIsNotNone(result_2, "VFB_00101567 query returned None")
569+
570+
# Performance assertions - fail if queries take too long
571+
# These thresholds are based on observed performance characteristics
572+
max_single_query_time = 2.0 # seconds
573+
max_total_time = 4.0 # seconds (2 queries * 2 seconds each)
574+
575+
self.assertLess(duration_1, max_single_query_time,
576+
f"FBbt_00003748 query took {duration_1:.4f}s, exceeding {max_single_query_time}s threshold")
577+
self.assertLess(duration_2, max_single_query_time,
578+
f"VFB_00101567 query took {duration_2:.4f}s, exceeding {max_single_query_time}s threshold")
579+
self.assertLess(duration_1 + duration_2, max_total_time,
580+
f"Total query time {duration_1 + duration_2:.4f}s exceeds {max_total_time}s threshold")
581+
582+
# Log success
583+
print("Performance test completed successfully!")
584+
527585

528586
class TestVariable:
529587

0 commit comments

Comments
 (0)