https://github.com/jackd248/clockwork-ai
Simple DIY clock project to generate AI poems by current time.
https://github.com/jackd248/clockwork-ai
ai chatgpt openai python raspberrypi waveshare waveshare-eink
Last synced: 6 months ago
JSON representation
Simple DIY clock project to generate AI poems by current time.
- Host: GitHub
- URL: https://github.com/jackd248/clockwork-ai
- Owner: jackd248
- License: mit
- Created: 2024-02-19T15:56:24.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-09T10:31:58.000Z (over 1 year ago)
- Last Synced: 2024-12-09T11:35:15.737Z (over 1 year ago)
- Topics: ai, chatgpt, openai, python, raspberrypi, waveshare, waveshare-eink
- Language: Python
- Homepage: https://jackd248.github.io/clockwork-ai/
- Size: 6.65 MB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# clockwork/ai
>
> This project is inspired by creative mind Matt Web and his beautiful [Poem/1](https://poem.town/) clock.
>
Simple DIY clock project to generate AI poems by current time using a raspberry pi zero + e-ink display.
- [General](#general)
* [Reuse](#reuse)
* [Lock](#lock)
- [Installation](#installation)
* [Hardware](#hardware)
* [Preparation](#preparation)
* [Prerequirements](#prerequirements)
* [Software](#software)
* [Permanent setup](#permanent-setup)
- [Configuration](#configuration)
* [Hardware support](#hardware-support)
* [Prompt](#prompt)
* [Validation](#validation)
* [Show time](#show-time)
* [Display rotation](#display-rotation)
* [Coincidence](#coincidence)
* [Font](#font)
* [Debug](#debug)
- [Development](#development)
- [Project log](#project-log)
* [Concept](#concept)
* [Prototype](#prototype)
- [Disclaimer](#disclaimer)
## General
Currently forced for german language, but can be adjusted for custom usage, see [Configuration](#Configuration).
### Features
- generate an AI poem about the current time and display them on an e-ink display
- display custom messages on the e-ink display
- clear the e-ink display
### Demo
See a live demo here: https://jackd248.github.io/clockwork-ai/.
### Commands
General command line functionalities of the python app:
- `python3 clockwork` - generates ai poem of current time
- `python3 clockwork 09:41` - generates ai poem of a requested time
- `python3 clockwork clear` - clear display
- `python3 clockwork demo` - demo poems to display
- `python3 clockwork display ` - display custom text
- `python3 clockwork ask ` - ask custom question to ai and display answer
The `--dry-run` option prevent the display process on the e-ink display and generates images instead under `var/debug/`.
### Reuse
The fs component stores the received poems to json files, e.g. `var/storage/12/1245.json`. If the environment variable `CLOCKWORK_REUSE` is set to true, the algorithm randomly uses stored poems instead of calling the api to reuse them.
The script also checks if an internet connection is available to call the api. If not so, the script will show a stored poem if available for some kind of offline usage.
### Lock
The file lock prevents the multiple execution of the python script, because this can result in display issues.
## Installation
### Hardware
- raspberry pi zero wh
- [waveshare 2.13inch e-Paper](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT) or [waveshare 7.5inch e-Paper](https://www.waveshare.com/wiki/7.5inch_e-Paper_HAT)
### Preparation
- based on the waveshare [tutorial](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual)
- see initialization and installation instructions for the raspberry and the needed libraries
### Prerequirements
- get an api key from openai: https://platform.openai.com/api-keys
### Software
```bash
# get python app
git clone https://github.com/jackd248/clockwork-ai.git
cd clockwork-ai
# install python requirements
pip3 install -r requirements.txt
# prepare settings
cp .env.dist .env
# run demo
python3 clockwork demo
```
You need to store your openai api key as environment variable within the `.env` file:
```dotenv
OPENAI_API_KEY='xxx'
```
Run the clockwork script to generate a poem:
```bash
python3 clockwork
```
### Permanent setup
Set up a periodic cronjob to update the poem e.g. every minute:
```bash
crontab -e
```
```cronexp
* * * * * python3 /path/to/clockwork/dir clockwork
```
Or set up a cronjob to update the poem on daytime:
```cronexp
* 06-23 * * * python3 /path/to/clockwork/dir clockwork
10 23 * * * python3 /path/to/clockwork/dir clockwork clear
```
> Note that you should clear the e-ink screen to avoid display issues.
> I would suggest to clear the screen if the display is not used for a longer time, e.g. at night.
## Configuration
All further configuration options are available within your `.env` file.
The 3.5 model is stored as default model for the openai api because it's the cheapest one so far. If you want to use another model, adjust the `OPENAI_API_MODEL` environment variable. See https://platform.openai.com/docs/models.
### Hardware support
Currently, the both displays are supported:
- 2.13inch e-Paper: `epd2in13`
- 7.5inch e-Paper: `epd7in5`
Change the `CLOCKWORK_DISPLAY` environment variable to the used hardware component.
### Prompt
You can adjust the default openai prompt to adjust the poem results or the desired language if you edit the environment variable `OPENAI_CLOCKWORK_SYSTEM_PROMPT` within your `.env` file:
```dotenv
OPENAI_CLOCKWORK_PROMPT="You are a clock that shows the time in a two-line poem."
```
### Validation
To improve the poem results by the ai, you can validate the response from the api again by the ai enabling the environment variable `CLOCKWORK_VALIDATE`. Therefore, a second request is sent to openai with the initial conversation messages and additional the `OPENAI_CLOCKWORK_VALIDATION_PROMPT`.
### Show time
If you want to compare current time with the generated poem, activate the `CLOCKWORK_SHOW_TIME` environment variable to display the time in the bottom right corner.
### Display rotation
Use the `CLOCKWORK_ROTATE` environment variable to define the degree of rotation, e.g. 180.
### Font
Download a custom TrueType font (e.g. at https://fonts2u.com/), save them within the `font` directory and adjust the `CLOCKWORK_FONT` environment variable to adjust the displayed font.
### Coincidence
To influence the random function for choosing between api request and storage, set and increase the `CLOCKWORK_RANDOM_FACTOR` environment variable with an integer. Normally, it's 1 (api) to 1 (storage) as ratio. To increase the usage of the storage increase the env var, e.g. to 8 for 1 (api) to 8 (storage).
### Debug
Use the environment variable `CLOCKWORK_DEBUG` to enable file log for more debug information under e.g. `var/log/app_2024-02-23.log`.
Also, a little dot is displayed in the upper right corner if a poem is reused instead of calling the openai api.
## Development
Use [docker](https://www.docker.com/) and [docker-compose](https://docs.docker.com/compose/) for a development context to work on the app.
Build docker container:
```bash
docker compose up --build
```
Run python app within dev service:
```bash
docker-compose run dev
$ python3 clockwork demo --dry-run
$ python3 clockwork display "Test" --dry-run
```
Use pylint to improve code quality:
```bash
docker-compose run dev
$ pylint clockwork
```
## Project log
### Concept
This graphic shows the request chain for generating the AI poem by the chatgpt api:
### Prototype
The following pictures show the iterations of the prototype.
*Version 1:* simple prototype with a raspberry pi zero and the 2.13inch e-Paper display
*Version 2:* using a pwnagotchi case
*Version 3:* using a bigger 7.5inch e-Paper display and simple ikea picture frame
## Disclaimer
The waveshare libraries are part of the [e-Paper](https://github.com/waveshareteam/e-Paper) repository.