## ๐ 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
## ๐ง 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.
## ๐ฏ 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
