{"id":49367056,"url":"https://github.com/eddietyp/image-prompt-library","last_synced_at":"2026-05-05T07:02:24.661Z","repository":{"id":354135176,"uuid":"1221558912","full_name":"EddieTYP/image-prompt-library","owner":"EddieTYP","description":"Local-first image prompt library for generating images, saving prompts, tags, and collections.","archived":false,"fork":false,"pushed_at":"2026-05-01T16:03:35.000Z","size":104051,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-02T00:03:07.088Z","etag":null,"topics":["ai-image","all-in-one","allinone","chatgpt","fastapi","gpt-image-2","gpt-image-2-prompts","image-generation","image-prompts","local-first","openai-codex","openai-image-generation","prompt-library","react","self-hosted","sqlite","text-to-image"],"latest_commit_sha":null,"homepage":"https://eddietyp.github.io/image-prompt-library/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EddieTYP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T11:32:00.000Z","updated_at":"2026-05-01T16:03:37.000Z","dependencies_parsed_at":"2026-05-02T00:01:14.584Z","dependency_job_id":null,"html_url":"https://github.com/EddieTYP/image-prompt-library","commit_stats":null,"previous_names":["eddietyp/image-prompt-library"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/EddieTYP/image-prompt-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddieTYP%2Fimage-prompt-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddieTYP%2Fimage-prompt-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddieTYP%2Fimage-prompt-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddieTYP%2Fimage-prompt-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddieTYP","download_url":"https://codeload.github.com/EddieTYP/image-prompt-library/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddieTYP%2Fimage-prompt-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32554777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T00:31:16.350Z","status":"ssl_error","status_checked_at":"2026-05-03T00:31:15.546Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-image","all-in-one","allinone","chatgpt","fastapi","gpt-image-2","gpt-image-2-prompts","image-generation","image-prompts","local-first","openai-codex","openai-image-generation","prompt-library","react","self-hosted","sqlite","text-to-image"],"created_at":"2026-04-27T20:00:54.033Z","updated_at":"2026-05-03T01:01:42.617Z","avatar_url":"https://github.com/EddieTYP.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Image Prompt Library\n\n[![CI](https://github.com/EddieTYP/image-prompt-library/workflows/CI/badge.svg)](https://github.com/EddieTYP/image-prompt-library/actions/workflows/ci.yml)\n[![GitHub Pages demo](https://github.com/EddieTYP/image-prompt-library/workflows/Deploy%20GitHub%20Pages%20demo/badge.svg)](https://github.com/EddieTYP/image-prompt-library/actions/workflows/pages.yml)\n[![Release](https://img.shields.io/github/v/tag/EddieTYP/image-prompt-library?sort=semver\u0026label=release)](https://github.com/EddieTYP/image-prompt-library/releases/tag/v0.2.0-alpha)\n[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue)](LICENSE)\n\nChatGPT image generation has become good enough that the prompts are worth keeping. The problem is that once you start saving great outputs, screenshots, and variations, there still is not a simple private tool for managing image prompts like a real reference library.\n\n**Image Prompt Library** is a local-first web app for collecting generated images and the prompts behind them. When you create an image worth reusing, save it into your own self-hosted library, add the prompt, organize it into collections and tags, and search it later as a quick visual reference.\n\nYour library stays on your own machine: local SQLite, local image files, no accounts, no cloud sync, and no hosted database required.\n\n**Online sandbox:** \u003chttps://eddietyp.github.io/image-prompt-library/\u003e — a read-only GitHub Pages version chooser using public sample prompts. The current 0.2 preview is available at \u003chttps://eddietyp.github.io/image-prompt-library/v0.2/\u003e, with the original 0.1 alpha archived at \u003chttps://eddietyp.github.io/image-prompt-library/v0.1/\u003e. Sandbox images are compressed for web preview. The online demo is read-only: Add, edit, and private library management are local-only, so install the app locally to create or edit your own full library.\n\n**Alpha release:** \u003chttps://github.com/EddieTYP/image-prompt-library/releases/tag/v0.2.0-alpha\u003e — refreshes Cards browsing, mobile layout behavior, adaptive image display, and versioned public previews.\n\n**Roadmap:** See [`ROADMAP.md`](ROADMAP.md) for follow-up work around mobile Explore, management flows, packaging, and public release polish.\n\n![Image Prompt Library Cards view](docs/assets/screenshots/card-view-all.png)\n\nThe 0.2 preview refreshes the browsing experience across desktop and mobile: image-first Cards, cleaner detail behavior, versioned public demos, and phone-specific layout improvements.\n\n## What it does\n\n- Save generated/reference images together with the prompt text that created them.\n- Organize references into collections and tags so good prompts are easy to find again.\n- Browse visually in **Explore view**, a thumbnail constellation that spreads images by collection in a style inspired by graph tools like Obsidian.\n- Browse densely in **Cards view**, an image-first masonry gallery for scanning many prompt references quickly on desktop and mobile.\n- Search across titles, prompts, tags, collections, sources, and notes.\n- Filter by collection, open a detail view, and copy the prompt with one click.\n- Keep everything local for privacy and long-term ownership.\n\n## Screenshots\n\nThe screenshots below show the main browsing and detail flows. The 0.2 preview also adds phone-specific behavior for Cards browsing, filtering, and detail viewing.\n\n### Browse with image-first cards\n\nCards view is designed for fast visual scanning. In the 0.2 preview, cards use an image-first layout with a clean title overlay, quick actions, and adaptive image display for mixed portrait, landscape, and tall reference images.\n\n![Cards view showing a filtered sample collection](docs/assets/screenshots/card-view-all.png)\n\n### Mobile-first browsing behavior\n\nOn phones, the app defaults to Cards view, uses a stable two-column masonry layout, keeps quick actions touch-visible, and moves the selected collection into a bottom dock instead of crowding the header. Filters open as a full-height drawer, and the detail view keeps prompt tabs and copy/edit controls reachable without switching to a desktop layout.\n\n\u003cp\u003e\n  \u003cimg src=\"docs/assets/screenshots/mobile-cards-view.jpg\" width=\"24%\" alt=\"Mobile Cards view with two-column masonry\" /\u003e\n  \u003cimg src=\"docs/assets/screenshots/mobile-filter-drawer.jpg\" width=\"24%\" alt=\"Mobile collection filter drawer\" /\u003e\n  \u003cimg src=\"docs/assets/screenshots/mobile-detail-image.jpg\" width=\"24%\" alt=\"Mobile image-first detail view\" /\u003e\n  \u003cimg src=\"docs/assets/screenshots/mobile-detail-prompt.jpg\" width=\"24%\" alt=\"Mobile prompt detail with language tabs\" /\u003e\n\u003c/p\u003e\n\n### Explore your prompt library visually\n\nExplore view gives you a spatial overview of your library. Collections become visual hubs, with image thumbnails arranged around them so you can scan patterns, styles, and prompt families at a glance.\n\n![Explore view showing the full sample library](docs/assets/screenshots/explore-view-home.png)\n\n### Focus on one collection\n\nFilters let you focus the same visual map on a single collection while keeping search, collection context, and the view switcher close at hand.\n\n![Explore view filtered to a technical diagrams collection](docs/assets/screenshots/explore-view-filtered.png)\n\n### Keep the prompt beside the image\n\nThe detail view keeps the large image preview, prompt, language tabs, attribution, notes, tags, favorite/edit actions, and one-click prompt copy in one place. On mobile, the detail view becomes image-first with floating controls over the image.\n\n![Reference item detail modal](docs/assets/screenshots/reference-item-detail.png)\n\n## Features\n\n- Local SQLite database and local image files.\n- Image storage with originals, previews, and thumbnails.\n- Explore mode: thumbnail constellation view for visual browsing.\n- Cards mode: image-first masonry/Pinterest-style prompt gallery.\n- Search across titles, prompts, tags, collections, sources, and notes.\n- Collections and tags for organizing references.\n- Detail modal with lightweight inline editing, prompt language tabs, and copy feedback.\n- Add/edit modal with English, Traditional Chinese, and Simplified Chinese prompt fields plus metadata.\n- Result image and optional reference image uploads.\n- Phone-friendly Cards behavior: two-column masonry, compact header, touch-visible actions, and bottom selected-collection dock.\n- Adaptive card/detail image display for mixed portrait, landscape, and tall reference images.\n\n## Requirements\n\n- Python 3.10+\n- Node.js 20+ recommended\n- npm\n\n## Platform support\n\n- macOS and Linux are the primary supported local-install targets today.\n- Windows can run the app stack through **WSL 2** using the same commands as Linux.\n- Native Windows PowerShell/CMD is not a supported quick-start path yet because the current helper scripts are Bash scripts and assume Unix-style virtualenv paths such as `.venv/bin/activate`. Native Windows support should use equivalent PowerShell scripts or a Docker/Compose path in a future pass.\n\n## Quick start\n\n```bash\ngit clone https://github.com/EddieTYP/image-prompt-library.git\ncd image-prompt-library\n./scripts/setup.sh\n./scripts/start.sh\n```\n\nOpen \u003chttp://127.0.0.1:8000/\u003e.\n\n`scripts/start.sh` builds the frontend and serves the built app through FastAPI, so normal local use only needs one server.\n\n## Development mode\n\nFor frontend/backend development with Vite hot reload:\n\n```bash\n./scripts/dev.sh\n```\n\nOpen \u003chttp://127.0.0.1:5177/\u003e.\n\nDefault development ports:\n\n- Backend API: \u003chttp://127.0.0.1:8000\u003e\n- Vite frontend: \u003chttp://127.0.0.1:5177\u003e\n\n## Configuration\n\nCopy `.env.example` to `.env` and edit if needed:\n\n```bash\ncp .env.example .env\n```\n\nImportant settings:\n\n```bash\nIMAGE_PROMPT_LIBRARY_PATH=./library\nBACKEND_HOST=127.0.0.1\nBACKEND_PORT=8000\nFRONTEND_PORT=5177\nBACKUP_DIR=./backups\n```\n\n`IMAGE_PROMPT_LIBRARY_PATH` controls where your private database and images live. The default `./library` is repo-local and intentionally ignored by git. For long-term personal use, you may prefer a durable path such as `~/ImagePromptLibrary`.\n\n## Data layout\n\nRuntime data lives under `IMAGE_PROMPT_LIBRARY_PATH`:\n\n```text\nlibrary/db.sqlite       SQLite metadata and full-text search index\nlibrary/originals/      original uploaded/imported images\nlibrary/previews/       generated preview images\nlibrary/thumbs/         generated thumbnail images\n```\n\nDo not commit runtime `library/` data to git. It is your private prompt/image collection.\n\n## Add your own prompts\n\n1. Start the app.\n2. Click `+ Add`.\n3. Add a title, prompt text, collection, optional tags, and a required result image.\n4. Save the card.\n5. Use Cards/Explore, search, filters, and detail view to browse and copy prompts later.\n\n![Add prompt modal](docs/assets/screenshots/add-prompt-modal.png)\n\n## Import and example data\n\nThe app starts with an empty private library. Your own `library/` folder contains personal prompt data and images, so it is intentionally ignored by git.\n\n### Try the sample library\n\nIf you want to see the app with example content, install the optional sample library:\n\n```bash\n./scripts/install-sample-data.sh en\n```\n\nThen start the app and open \u003chttp://127.0.0.1:8000/\u003e.\n\nThe installer downloads the sample image ZIP from a public sample-data release and verifies its SHA256 checksum before import. The default sample library is based on [`wuyoscar/gpt_image_2_skill`](https://github.com/wuyoscar/gpt_image_2_skill), licensed under **CC BY 4.0**. A second sample package based on [`freestylefly/awesome-gpt-image-2`](https://github.com/freestylefly/awesome-gpt-image-2), licensed under **MIT**, is available with:\n\n```bash\n./scripts/install-sample-data.sh zh_hant awesome-gpt-image-2\n```\n\nBoth are included only as demo/sample content; your own prompt library data remains private and is not part of any sample bundle.\n\n## Backup\n\nCreate a timestamped backup archive:\n\n```bash\n./scripts/backup.sh\n```\n\nThe backup includes:\n\n- `library/db.sqlite`\n- `library/originals/`\n- `library/thumbs/`\n- `library/previews/`\n\nRestore by stopping the app, extracting the archive, and replacing the corresponding library directory contents. Keep backups somewhere outside the repo if the library matters to you.\n\n## GitHub Pages sandbox\n\nThe repository also ships static read-only demos for GitHub Pages:\n\n```bash\nnpm run build:demo\nnpm run build:demo:v0.2\n```\n\nThe public Pages deployment is versioned:\n\n- `/` — version chooser\n- `/v0.2/` — current 0.2 preview\n- `/v0.1/` — archived 0.1 alpha demo\n\nThe demos read public sample metadata from `frontend/public/demo-data/`, use compressed WebP preview images, and disable write actions. They are intended only as online sandboxes. The online demo is read-only: Add, edit, and private library management are local-only, so install the app locally to create or edit your own private prompt library.\n\n## Verification\n\nRun backend/API/static tests:\n\n```bash\nsource .venv/bin/activate\npython -m pytest -q\n```\n\nBuild the frontend:\n\n```bash\nnpm run build\n```\n\nSmoke-test a running local server:\n\n```bash\n./scripts/smoke-test.sh\n```\n\n## License and allowed use\n\nImage Prompt Library's core application code is open source under **AGPL-3.0-or-later**. Copyright (C) 2026 Edward Tsoi. See `NOTICE` for the project copyright notice and `LICENSE` for the full AGPL text.\n\nCommercial licenses are available for organizations that want to use, modify, or host Image Prompt Library under terms outside the AGPL. Contact the maintainer if you need proprietary hosted-product terms or other non-AGPL licensing.\n\nSample data and third-party assets are licensed separately and retain their original attribution/license terms. The optional sample bundle currently preserves `wuyoscar/gpt_image_2_skill` / **CC BY 4.0** attribution; do not treat sample prompts/images as part of the app-code AGPL grant.\n\nYour own local prompt library data remains yours and should not be committed to this repository.\n\n## Privacy and security model\n\n- The app is local-first and stores data on your device.\n- There are no user accounts or built-in cloud sync.\n- The `/media` route only serves image media directories and should not expose the SQLite database or internal files.\n- Binding to `127.0.0.1` keeps the app local to your machine. Only change the host if you understand the LAN exposure implications.\n\n## Troubleshooting\n\n### `./scripts/start.sh` cannot find Python dependencies\n\nRun setup first:\n\n```bash\n./scripts/setup.sh\n```\n\n### Port already in use\n\nChange `.env`:\n\n```bash\nBACKEND_PORT=8001\nFRONTEND_PORT=5178\n```\n\nThen restart the app.\n\n### Empty library after first start\n\nThat is expected for a fresh install. Click `+ Add` to create your first prompt card, or install the optional sample library if you want demo content first.\n\n### Images or database missing after moving folders\n\nCheck `IMAGE_PROMPT_LIBRARY_PATH` in `.env`. Your database and image folders must stay together.\n\n## Project status\n\nThis is an alpha local-first app. Core browse/search/filter/detail/copy/add/edit flows exist, the public read-only sandbox is versioned, and the 0.2 preview improves both desktop and mobile browsing. Remaining work includes deeper mobile Explore gestures, management-flow polish, packaging, and public-release hardening.\n\nSee `ROADMAP.md` for the current roadmap and follow-up priorities.\n\n## Repository layout\n\n```text\nbackend/                 FastAPI app, SQLite migrations, repositories, services, routers\nfrontend/                Vite/React app\nlibrary/                 Local runtime data, ignored except .gitkeep placeholders\nscripts/dev.sh           Backend + Vite development mode\nscripts/setup.sh         Local setup helper\nscripts/start.sh         Single-service local mode\nscripts/backup.sh        Timestamped local data backup\nscripts/smoke-test.sh    Basic running-server smoke test\ntests/                   Backend/API/static regression tests\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddietyp%2Fimage-prompt-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddietyp%2Fimage-prompt-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddietyp%2Fimage-prompt-library/lists"}