## ๐ Overview
Senju (ๅๆ, "thousand hands") is a web service for haiku poetry generation and sharing, with image-to-haiku functionality.
## โจ Features
- **๐ AI-Powered Haiku Generation**: Create beautiful three-line haiku poetry from text prompts
- **๐ผ๏ธ Image-to-Haiku**: Turn uploaded images into poetic haiku (experimental)
- **๐ Browse Existing Haiku**: Gallery view of previously generated poetry
- **๐พ Persistent Storage**: All generated haiku are stored for future retrieval
- **๐ฅ๏ธ Web Interface**: Clean, efficient, minimalist user experience for human interaction
- **๐ Accessibility**: Text-to-speech integration for haikus
## ๐ง Installation
```bash
# Clone the repository
git clone https://github.com/senju1337/senju.git
cd senju
docker compose up
```
Docker desktop users on windows might need to change the line seperator from CRLF to LF of the file
`entrypoint.sh`
### ๐ Dependencies
- Python
- Flask
- TinyDB
- PyTorch
- Transformers
- Pillow
See `pyproject.toml` for a complete list of dependencies.
#### Text To Speech
The speech synthesis uses the functionalities of your Operating System. Depending on your System, you might need to install additional software to use speech synthesis. On Debian GNU/Linux, you need to do the following:
```bash
apt install espeakup speech-dispatcher
```
Senju uses [`window.speechSynthesis`](https://developer.mozilla.org/en-US/docs/Web/API/Window/speechSynthesis) for TTS.
## ๐ฏ Architecture
Senju is built around several key components:
- **Flask Application**: Core web framework providing routing and template rendering
- **Haiku Generator**: Interfaces with a machine learning model for poetry creation
- **Image Recognition**: Vision-language model for extracting descriptions from images
- **Storage Manager**: TinyDB-based persistence layer for haiku retrieval and storage
## ๐ Documentation
Senju is documented with sphinx. The documentation of the latest release is
available on [github-pages](https://senju1337.github.io/senju/).
It can be generated like this (after installing the dependencies, see above):
```bash
cd docs
bash auto_docu.sh
# now open the documentation with a web browser of your choice
firefox ./build/html/
```
## ๐งช Testing
```bash
# Run tests
pytest
# Run tests with coverage
bash coverage.sh
```
## ๐ License
Distributed under the GPL-3 License. See `LICENSE` for more information.
## ๐ Acknowledgements
- [Ollama](https://ollama.ai/) for providing the AI backend
- [BLIP](https://github.com/salesforce/BLIP) for the image captioning model
- [PyTorch](https://pytorch.org/) and [Transformers](https://huggingface.co/docs/transformers/index) for ML infrastructure
- [Flask](https://flask.palletsprojects.com/) for the web framework
- [TinyDB](https://tinydb.readthedocs.io/) for the document database
Purple petals rise
Defying fragile beauty
Fiercely breathing life
