.---.
/| .--. ..... __ __ ___ _________ .... | | .....
|| || .-'' '. | |/ .' .\ |.' '-. | | .-'' '.
|| .--. .| .| / .-''"'-. . | .-. .-. '\ .'```'. '. | | / .-''"'-. .
|| __ | | .' |_ .' |_ / /\ | | | | | | \ | \ | |/ /\ \
||/' '. | | .' | .' || || | | | | | | | | || || |
|:/ '. '| |'--. .-' '--. .-'\ .-------------'| | | | | | | \ / . | |\ .-------------' || | || | | | | | \ '-.____...---.| | | | | | | |\'-.-' .' | | \ '-.____...---.
||\ / '|__| | | | | . .' |__| |__| |__| | | '-....-' | | . .' |/\'..' / | '.' | '.' ''-...... -' .' '. '---' ''-...... -' ' '-' | / | / '-----------' '-' `'-'
▎▌▎
▏▏▎▇█▅▍
▏▍▌▂▇███▅▋▏
▏▊▌▌▌▆██████▇▌▏
▏▎▌▍▍▌▋▋▋▃▇███████▂▌▏
▍▌▌▊▌▌▋▂▍▌▃▇▇█████████▇▂▍▏
▎▌▎▌▋▌▌▉▁▌▍▌▌▉▂▇████████████▆▊▏
▎▎▌▊▌▍▊▋▍▍▊▊▍▌▌▊▉▅▂▅██████████████▅▉▉▊
▍▌▉▂▍▊▌▍▎▌▉▍▍▍▍▌▉▄▊█▅██████████████████▅▏
▋▃▂▍▉▉▍▌▉▉▌▍▋▌▌▁▉▄▄▆▅▅███▇██████████████▋
▏▎▎▃▍▌▁▍▍▍▃▍▍▍▍▌▉▄▆██████████████████████▃▎▎
▎▌▍▍▍▍▍▍▍▍▋▊▃▅▉▅▅▅▅▅▅▅▅▅▅▅▅▇▇▆█████████████▅
▏▌▋▊▃▂▂▂▂▁▁▂▂▃▃▇██████████████████████████▅▎
▍▋█▆▄▄▄▅▋▁█▆▁████▆████████▃███▄█████████▌
▋▋█▊▏▎▏ ▋▉██▉██▅▃██████▇██▂███▂████████▇
▏▎▉▌█▋▌▃▁▎▌▌██▉██▊▅██▁▌▄█▅▄█▃███▁█████████▋
▎▌▍▅▍█▋▉█▁▋▊▋██▊██▄██▅▊▍▂▅▇▆█▁███▁█████████▇▋
▎▋▏▃▇▍█▋▉█▁▊▊▉██▊██▂██▅▎▏▌▆▇▃█▃███▁██████████▇▌
▏▌▋▅█▇▍█▋▂█▁▋▊▉██▁██▂██▉▏ ▏▃▇▃█▁███▅███████████▇▌
▊▊▂██▇▍█▋▁█▁▋▊▃██▁██▂██▇▄▊▆▅▇▃█▁▇██▂████████████▅▏
▎▆████▇▍█▋▁▊▉▌▊▂██▁██▂███▇▂▇█▇▃█▁███▃█████████████
▏▉▅▄█▃▍▁▁▏ ▌▌▄█▅▃▇█▃███████▇▃█▂▆█▇▃███████████▉▎
▎▎▉▁▋▍▌▉▋▋▋▉▋▁▄▄▄▅▆▄▅▆▆▆▅▆▆▅▅▆▄▆▆▆▇███████████▇▊
▍▎▋▆▅▅▅▅▅▆▆▇▆▇███████████████████████████████████▄▏
▎▋▌██▄▌▌▋▌▌▌▌▌▌▊▋▊▃▅▆▇▆████████████████████████████▃▏
▊▍▃███▉▂██████▉██▆▃████▅▆▇██████▄███▆███████████████▋
▏▍▉▆████▄▊█▊▎▍▎▎▁███▂██▆▂▇██████▆█▃███▄██████████████▊▏
▎▄▇█████▄▍█▋▌▃▉▎▋▉██▁██▁▇██████▇▃█▁███▁███████████▆▉▎
▍▅█▇▂▊▃█▅▋█▋▊█▁▋▉▃██▁██▆███████▇▇█▁███▂████████████▂
▎▋▍▂███▄▋█▌▁█▁▋▁▅██▁██▃███████▇▄█▂███▂█████████████▋
▎▎▉▊▄████▄▋█▋▁█▁▊▊▆██▂██▃████▇██▇▃█▁███▂█████████████▇▍
▏▋▊▆███████▄▋█▋▉▅▉▊▉███▉██▃██▇▆█▉█▇▃█▁███▇██████████████▆▎
▎▄▇█████████▄▋█▋▉▁▁▋▉███▁██▃███████▇▄█▂███████████████████▂
▉██████████▂▋█▁▌▍▍▍▊▄█▇▁▇█▃███████▇▄█▂▆█████████████████▇▎▏▎▋▏
▎▌▋▄▅▄▁▉▅██▅▃▋▋▅▆▋▊▁▃▍▄▅▁▅▃█▅▆▅▄▄▄▄▄▄▄▇▃█▅▂████████████▇▇▅▂▄████▄▌▏
▍▊▆█████▂▌▍▉▆▇▅▃▊▍▁▃▄▅▉▊▃▆▇▁█▅▄▄▄▄▄▄▄▄▄▅▄█████▁▊██████▂▍▌▅█████████▄▏
▍▁▆█████▅▋▋▁▇██▄▉▌▉▇▇▇▉▍▉█▇█▇▁██▆▅▅▅▅▆▆▆▆▆▃███▆▄▄█████▆▌▉▅████████████▇▋
▏▌▉▄▄▂▂▂▂▂▂▊▁▂▂▂▂▉▋▉▁▃▃▂▊▊▃▂▂▁▃▇▁█▆▄▄▅▅▄▄▄▄▄▅▃▆▃▃▁▂▂▃▃▃▂▂▂▅▆▆▇▆▆▇██████████▅▃▋
▏▍▊▊▉▊▋▉▁▁▁▊▊▉▉▂▂▂▂▅▂▁▂▃▄▄▃▅▅▅▄▄▅▆▁█▇▆▅▅▅▅▅▅▅▅▆▃█▄▄▄▄▅▄▅▅▄▄▅▅█▆▆▆▆▅▆███▆████████▄▎
▍ ▊▊▋▎▊▊▊▁▏ ▊▌ ▎▃▅▅▅▄▄▅▅▅▅▄▄▆▆██▂█▇▅▅▅▅▅▅▅▅▅▅▂█▇▅▄▅█▅▅▄▆███████████████████████▅
▏▊▍█▅▉█▂▁▄▆▅▄██▃▁▆████████████████▂█▅▅▅▅▅▅▅▅▅▅▅▂█████████████████████████████████▂
▉▇▄▏▋▉▋▅▁▎▄▇▃▇██▃▅▃██████████████▂█▇▇▇▆▆▆▇▇▇▇▆▄█████████████████████████████████▌
▎█▊▉▂▋▅▇▇▇▁▉▆██▆▌▅█▇▃▆██████▇████▄█▅▄▄▄▄▄▄▄▄▅▆▃████████████████████████████████▄
▋▆████▄█████▄▃▆██████████████████▇▇▇▇▇▇▆▆▆▆▆▆▇████████████████▆▁▃████████████▅▌
▏▎▎▎▎▎▎▎▎▋▃█████▂▌▎▎▎▎▎▎▎▎▎▎▎▎▎▎▍▍▍▍▍▍▍▍▎▎▎▎▎▎▎▎▎▎▎▎▎▎▎▎▎▎▎▎▁▅█████▂▎▎▎▎▎▎▎▎▏
▏▊▂▊ ▎▉▂▃▊▏ ▎▋▊▍▏ ▌▌▌▎▏
▏▍▍▍▍▍▏ ▏▍▋▋▋▍
## BitHarbor
BitHarbor is a FastAPI-based media server focused on content-addressed storage, deterministic embeddings, and ANN-backed search across movies and music.
### Highlights
- BLAKE3 hashes identify all stored media and vectors
- Sentence-BERT provides reproducible text embeddings per media type
- DiskANN-ready vector index (currently falls back to exact cosine search)
- SQLite via SQLAlchemy for a lightweight catalog
### Quick Start
1. **Install dependencies**
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
-
Configure environment
- Copy
config.example.yamltoconfig.yamland adjust paths - Create a
.envwithTMDB_API_KEY,TMDB_ACCESS_TOKEN, optional Jamendo credentials, and storage locations (RAID_PATH,VECTOR_DB_PATH)
- Copy
-
Initialize the database
python -m db.init
-
Run the API
uvicorn app.main:app --reload
-
Test ingestion (optional)
- Use
/api/v1/movies/catalog/searchto match TMDb + Internet Archive results - Download and ingest via
/api/v1/movies/catalog/download - Verify local search at
/api/v1/movies/local/search
- Use
See TODO.md for the current roadmap and open tasks.