Merge branch 'readme' into 'main'
Update README.md See merge request engineering/unturf/art.ai.unturf.com!3
This commit is contained in:
commit
8fe6c4c481
1 changed files with 90 additions and 69 deletions
159
README.md
159
README.md
|
|
@ -2,126 +2,147 @@
|
|||
|
||||
Black Forest Labs Image Generation
|
||||
|
||||
This project enables users to generate images based on prompts using the Black Forest Labs API. It now supports multiple users with individual namespaces (albums), secure OTP-based authentication, and enhanced metadata storage. Generated images are stored locally with their metadata in a SQLite database, and a Streamlit web interface provides an interactive experience.
|
||||
This project is a Streamlit-based web application that allows users to generate images using the Black Forest Labs API. It supports multiple users with secure OTP-based authentication, collaborative namespaces (albums), and persistent storage of images and metadata in SQLite databases. Users can create albums, generate images with customizable settings, invite collaborators, and download their creations with detailed metadata.
|
||||
|
||||
## Features
|
||||
|
||||
- **User Authentication**: Secure login via email and one-time password (OTP).
|
||||
- **Namespaces (Albums)**: Organize images into user-created albums, with support for multiple collaborators.
|
||||
- **Image Generation**: Generate images using Black Forest Labs models (e.g., `flux-dev`, `flux-pro-1.1`) with customizable seeds.
|
||||
- **Collaboration**: Invite other users to collaborate on albums via email.
|
||||
- **Persistent Storage**: Images and metadata are stored in SQLite databases, with per-namespace separation.
|
||||
- **Metadata**: Each image includes prompt, seed, model endpoint, and generation timestamp.
|
||||
- **Web Interface**: Interactive Streamlit app for login, album management, and image generation/display.
|
||||
- **Downloadable Outputs**: Download generated images directly from the interface.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.x
|
||||
checkout ``requirements.txt``
|
||||
|
||||
- Python 3.8+
|
||||
- Required Python packages:
|
||||
- `http.client`
|
||||
- `json`
|
||||
- `base64`
|
||||
- `os`
|
||||
- `time`
|
||||
- `requests`
|
||||
- `streamlit` (for web interface)
|
||||
- `argparse`
|
||||
- `re`
|
||||
- `sqlalchemy` (replaces `sqlite3` for ORM)
|
||||
- `bcrypt` (for OTP hashing)
|
||||
- `streamlit-cookies-manager` (for session persistence)
|
||||
- `python-dateutil` (for date handling)
|
||||
- `secrets` (for secure cookie secret generation)
|
||||
- `streamlit` (web interface)
|
||||
- `requests` (API calls)
|
||||
- `sqlalchemy` (ORM for database management)
|
||||
- `bcrypt` (OTP hashing)
|
||||
- `streamlit-cookies-manager` (session persistence)
|
||||
- `smtplib` (email sending, optional)
|
||||
- `http.client` (BFL API interaction)
|
||||
- `base64` (image encoding)
|
||||
- `secrets` (secure cookie secret generation)
|
||||
- Plus standard libraries: `os`, `time`, `json`, `re`, `random`, `socket`, `tempfile`, `datetime`
|
||||
|
||||
## Installation
|
||||
|
||||
1. **Clone the Repository**
|
||||
|
||||
Clone this repository to your local machine:
|
||||
|
||||
```bash
|
||||
git clone https://git.unturf.com/engineering/unturf/art.ai.unturf.com.git
|
||||
cd art.ai.unturf.com
|
||||
```
|
||||
|
||||
2. **Install Required Packages**
|
||||
2. **Create Python3 virtualenv & Install Required Packages**
|
||||
|
||||
Install the required packages:
|
||||
Then install:
|
||||
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
*Note*: If `requirements.txt` doesn’t exist yet, manually install the listed packages:
|
||||
|
||||
```bash
|
||||
pip install requests streamlit sqlalchemy bcrypt streamlit-cookies-manager python-dateutil
|
||||
```
|
||||
|
||||
3. **Set Environment Variables**
|
||||
|
||||
Set your Black Forest Labs API key as an environment variable:
|
||||
Set your Black Forest Labs API key:
|
||||
|
||||
```bash
|
||||
export BLACK_FOREST_LABS_API_KEY="your_api_key_here"
|
||||
```
|
||||
|
||||
Replace `"your_api_key_here"` with your actual API key.
|
||||
|
||||
For Streamlit Cloud deployments, optionally set:
|
||||
|
||||
```bash
|
||||
export STREAMLIT_CLOUD="true"
|
||||
export BLACK_FOREST_LABS_API_KEY="your_api_key_here"
|
||||
```
|
||||
|
||||
And configure the API key in Streamlit’s secrets management (see [Streamlit Docs](https://docs.streamlit.io/deploy/streamlit-community-cloud/manage-your-app#manage-app-secrets)).
|
||||
Alternatively, configure the API key in Streamlit’s secrets management (see [Streamlit Docs](https://docs.streamlit.io/deploy/streamlit-community-cloud/manage-your-app#manage-app-secrets)).
|
||||
|
||||
4. **SMTP Configuration (Optional)**
|
||||
|
||||
For OTP and invite emails, configure an SMTP server (e.g., `localhost:25`). If not available, emails are logged to stdout.
|
||||
|
||||
## Usage
|
||||
|
||||
### Command-Line Interface
|
||||
### Running the Web Interface
|
||||
|
||||
Run the script with a prompt (single-user mode, no authentication):
|
||||
|
||||
```bash
|
||||
python black_forest_test.py "A beautiful sunset over the mountains"
|
||||
```
|
||||
|
||||
This creates an `images` directory for storing generated images.
|
||||
|
||||
### Web Interface
|
||||
|
||||
Run the Streamlit web interface:
|
||||
Launch the Streamlit app:
|
||||
|
||||
```bash
|
||||
streamlit run black_forest_streamlit.py
|
||||
```
|
||||
|
||||
- **Login**: Enter your email to receive a 6-digit OTP, then verify it to access your account.
|
||||
- **Albums**: Create and select namespaces (albums) to organize your images.
|
||||
- **Generate**: Input prompts to generate images within the selected album.
|
||||
- **View**: See images with metadata like seed, model, and generation time.
|
||||
- **Login**: Enter your email to receive a 6-digit OTP (sent via email or logged to console), then verify to log in.
|
||||
- **Album Management**: Create new albums or select existing ones from the dropdown.
|
||||
- **Collaboration**: Invite collaborators via email from the sidebar and manage access.
|
||||
- **Image Generation**: Enter a prompt, choose a model and seed, and generate images within the selected album.
|
||||
- **View & Download**: Browse generated images with metadata (prompt, seed, model, timestamp) and download them as JPEGs.
|
||||
- **Logout**: End your session from the sidebar.
|
||||
|
||||
## Output
|
||||
|
||||
- **Images**: Stored temporarily in memory (deployed) or in an `images` directory (local, single-user CLI mode).
|
||||
- **Metadata**: Stored in `data/image_metadata.db` SQLite database, persistent across deploys.
|
||||
- **Storage**: Images and metadata are stored in the `data/` directory:
|
||||
- `main.db`: SQLite database for users and namespaces.
|
||||
- `namespace_<id>.db`: Per-namespace SQLite databases for images.
|
||||
- `cookie_secret.txt`: Persistent cookie encryption key.
|
||||
- **Temporary Files**: Generated images are stored temporarily in memory during the session for display and download.
|
||||
|
||||
## Database Structure
|
||||
|
||||
The database (`data/image_metadata.db`) includes three tables:
|
||||
### Main Database (`data/main.db`)
|
||||
|
||||
### `users`
|
||||
- **id**: Unique identifier (INTEGER PRIMARY KEY)
|
||||
- **email**: User’s email (TEXT, UNIQUE)
|
||||
- **otp_hash**: Hashed OTP for authentication (TEXT)
|
||||
- **otp_expiry**: OTP expiration time (DATETIME)
|
||||
- **`users`**:
|
||||
- `id` (INTEGER PRIMARY KEY): Unique user ID.
|
||||
- `email` (STRING, UNIQUE): User’s email.
|
||||
- `otp_hash` (STRING): Hashed OTP for login.
|
||||
- `otp_expiry` (DATETIME): OTP expiration timestamp.
|
||||
|
||||
### `namespaces`
|
||||
- **id**: Unique identifier (INTEGER PRIMARY KEY)
|
||||
- **user_id**: Foreign key to `users.id` (INTEGER)
|
||||
- **name**: Album name (TEXT, UNIQUE per user)
|
||||
- **`namespaces`**:
|
||||
- `id` (INTEGER PRIMARY KEY): Unique namespace (album) ID.
|
||||
- `name` (STRING): Album name.
|
||||
|
||||
### `images`
|
||||
- **id**: Unique identifier (INTEGER PRIMARY KEY)
|
||||
- **namespace_id**: Foreign key to `namespaces.id` (INTEGER)
|
||||
- **slug**: Prompt-based slug (TEXT)
|
||||
- **prompt**: Original generation prompt (TEXT)
|
||||
- **filename**: Saved image filename (TEXT)
|
||||
- **base64_image**: Base64 encoded image (TEXT)
|
||||
- **generation_time**: Exact time of generation (DATETIME)
|
||||
- **seed**: Seed used for generation (INTEGER)
|
||||
- **model_endpoint**: Black Forest Labs model used (TEXT, e.g., "flux-dev")
|
||||
- **`namespace_users`**:
|
||||
- `id` (INTEGER PRIMARY KEY): Unique relation ID.
|
||||
- `user_id` (INTEGER, FOREIGN KEY): References `users.id`.
|
||||
- `namespace_id` (INTEGER, FOREIGN KEY): References `namespaces.id`.
|
||||
- Unique constraint on `(user_id, namespace_id)`.
|
||||
|
||||
### Namespace Databases (`data/namespace_<id>.db`)
|
||||
|
||||
- **`images`**:
|
||||
- `id` (INTEGER PRIMARY KEY): Unique image ID.
|
||||
- `slug` (STRING): Unique slug derived from prompt and timestamp.
|
||||
- `prompt` (STRING): Original prompt text.
|
||||
- `filename` (STRING): Generated filename (e.g., `slug.jpg`).
|
||||
- `base64_image` (STRING): Base64-encoded image data.
|
||||
- `generation_time` (DATETIME): Timestamp of generation.
|
||||
- `seed` (INTEGER): Seed used for generation.
|
||||
- `model_endpoint` (STRING): BFL model used (e.g., `flux-dev`).
|
||||
|
||||
## Deployment
|
||||
|
||||
For Streamlit Cloud:
|
||||
1. Push the repository to GitHub.
|
||||
2. Connect it to Streamlit Cloud.
|
||||
3. Add `BLACK_FOREST_LABS_API_KEY` to Streamlit secrets.
|
||||
4. Ensure the `data/` directory is writable (Streamlit Cloud uses a temporary filesystem).
|
||||
|
||||
## Notes
|
||||
|
||||
- **Local Development**: If SMTP isn’t configured, OTPs and invites are logged to the console.
|
||||
- **Security**: OTPs expire after 10 minutes; cookies are encrypted using a persistent secret.
|
||||
- **Scalability**: Each namespace has its own database to manage large image collections efficiently.
|
||||
|
||||
## License
|
||||
|
||||
This work is dedicated to the public domain.
|
||||
This work is dedicated to the public domain.
|
||||
Loading…
Add table
Add a link
Reference in a new issue