A Flask-based web server that serves Biblical Hebrew Scripture (BHSA) passage data on demand for the Biblical Meaning Maps (BMM) application. This server provides access to the ETCBC BHSA dataset through a simple web interface and REST API.
- 🚀 Easy Setup - Simple installation with Poetry
- 📖 BHSA Integration - Direct access to ETCBC Biblical Hebrew data
- 🌐 Web Interface - Built-in HTML interface for passage analysis
- 🔌 REST API - JSON API for programmatic access
- 💾 Local Data Support - Automatically detects and uses local BHSA data
- 🔒 Workshop Ready - Designed for local network workshops
- Python 3.8+ (Python 3.9+ recommended)
- Poetry (for dependency management)
- ~500MB disk space (for BHSA data, if downloading)
- Internet connection (for first-time data download, optional if using local data)
If you don't have Poetry installed:
# macOS/Linux
curl -sSL https://install.python-poetry.org | python3 -
# Or follow the official guide: https://python-poetry.org/docs/#installationgit clone https://github.com/shemaobt/mm_poc.git
cd mm_pocpoetry installThis will install all required dependencies including:
- Flask (web framework)
- Flask-CORS (cross-origin support)
- Text-Fabric (BHSA data access)
poetry run python bmm_server.pyThe server will:
- Check for local BHSA data in
text-fabric-data/github/ETCBC/bhsa/ - Use local data if found, or download from GitHub if not
- Start the Flask server on
http://localhost:5000
# Specify a custom port
poetry run python bmm_server.py --port 8080
# Use a custom BHSA data path
poetry run python bmm_server.py --bhsa-path /path/to/bhsa/app
# Specify host (default: 0.0.0.0 for network access)
poetry run python bmm_server.py --host 127.0.0.1
# Combine options
poetry run python bmm_server.py --port 8080 --bhsa-path ~/bhsa-data/appOn first run, if no local BHSA data is found, the server will attempt to download it from GitHub. This can take 10-30 minutes depending on your connection.
To speed up the download, set a GitHub token:
export GITHUB_TOKEN=your_github_personal_access_token
poetry run python bmm_server.pyGet a token at: https://github.com/settings/tokens (no special permissions needed)
Once the server is running, you'll see output like:
============================================================
BMM SERVER READY
============================================================
Share this URL with workshop participants:
http://192.168.1.100:5000
Or use localhost for your own browser:
http://localhost:5000
- Local access: Open
http://localhost:5000in your browser - Network access: Use the IP address shown (e.g.,
http://192.168.1.100:5000)
Serves the main HTML application interface.
Check server and BHSA loading status.
Response:
{
"status": "ok",
"bhsa_loaded": true
}Extract passage data from BHSA.
Parameters:
ref(required): Biblical reference (e.g., "Ruth 1:1-6", "Gen 1:1-5", "Psalm 23:1-6")
Response:
{
"reference": "Ruth 1:1-6",
"source_lang": "hbo",
"clauses": [
{
"clause_id": 1,
"verse": 1,
"text": "וַיְהִי בִּימֵי שְׁפֹט הַשֹּׁפְטִים",
"gloss": "And it came to pass in the days when the judges judged",
"clause_type": "Way0",
"is_mainline": true,
"chain_position": "initial",
"lemma": "היה",
"subjects": ["ימים"],
"objects": [],
...
}
]
}List all available books in the BHSA dataset.
Response:
{
"books": ["Genesis", "Exodus", "Leviticus", ...]
}The server automatically detects BHSA data in the following location:
text-fabric-data/github/ETCBC/bhsa/
├── app/
│ ├── app.py
│ └── config.yaml
└── tf/
└── 2021/
└── *.tf files
If you have BHSA data elsewhere, you can:
-
Symlink it to the expected location:
ln -s /path/to/your/bhsa-data text-fabric-data/github/ETCBC/bhsa
-
Use
--bhsa-pathto point directly to the app directory:poetry run python bmm_server.py --bhsa-path /path/to/bhsa/app
-
Set
TF_DATAenvironment variable:export TF_DATA=/path/to/text-fabric-data poetry run python bmm_server.py
mm_poc/
├── bmm_server.py # Main Flask server
├── bmm_v5_2_unified.html # Web application interface
├── generate_assets.py # Asset generation script
├── pyproject.toml # Poetry dependencies
├── .gitignore # Git ignore rules
└── text-fabric-data/ # BHSA data (gitignored)
For development, you might want to enable Flask's debug mode. Edit bmm_server.py and change:
app.run(host=args.host, port=args.port, debug=True, threaded=True)Or add a --debug flag to the argument parser.
Key dependencies are managed via Poetry:
- Flask 3.0+ - Web framework
- Flask-CORS 4.0+ - Cross-origin resource sharing
- Text-Fabric - BHSA data access library
- PyGithub <2.0.0 - GitHub API (for data download)
If port 5000 is already in use (common on macOS with AirPlay):
# Use a different port
poetry run python bmm_server.py --port 8080
# Or disable AirPlay Receiver in System Settings > General > AirDrop & HandoffRate Limit Errors:
# Set GitHub token
export GITHUB_TOKEN=your_token
poetry run python bmm_server.pyData Not Found:
- Ensure
text-fabric-data/github/ETCBC/bhsa/exists with proper structure - Or use
--bhsa-pathto specify location - Check that both
app/andtf/directories exist
Connection Issues:
- Verify internet connection (for first-time download)
- Check firewall settings
- Ensure sufficient disk space (~500MB)
- Ensure server is bound to
0.0.0.0(default) - Check firewall allows incoming connections on the port
- Verify all devices are on the same network
- Try accessing via
localhostfirst to verify server is running
If you encounter RateLimitOverview or similar errors:
-
Ensure PyGithub version is compatible:
poetry show pygithub
-
Update dependencies:
poetry update
- Python: 3.8 or higher (3.9+ recommended)
- Disk Space: ~500MB for BHSA data
- Memory: Minimum 2GB RAM recommended
- Network: Required only for first-time data download
[Add your license information here]
[Add contribution guidelines here]
For issues and questions, please open an issue on GitHub: https://github.com/shemaobt/mm_poc