Metadata-Version: 2.4
Name: image-annex
Version: 0.1.4
Summary: High-performance, Git-Annex powered photo archive with AWS S3.
Project-URL: Homepage, https://image-annex.store
Project-URL: Repository, https://github.com/InTEGr8or/image-annex
Project-URL: Documentation, https://github.com/InTEGr8or/image-annex/blob/main/llms.txt
Requires-Python: <4,>=3.9
Description-Content-Type: text/markdown
Requires-Dist: aws-cdk-lib==2.202.0
Requires-Dist: boto3>=1.35.0
Requires-Dist: constructs<11.0.0,>=10.0.0
Requires-Dist: pillow>=11.3.0
Requires-Dist: platformdirs>=4.4.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyexiftool>=0.5.6
Requires-Dist: requests>=2.31.0
Requires-Dist: faster-whisper>=1.1.0
Requires-Dist: insightface>=0.7.3
Requires-Dist: numpy>=1.24.0
Requires-Dist: onnxruntime>=1.16.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: textual>=1.0.0
Requires-Dist: toml
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.40.0
Requires-Dist: verkit

# Image Annex

Image Annex is a deduplicating photo archive. Originals stay in a git-annex repository, S3 holds the durable copy, and a local catalog stores EXIF, captions, OCR, and transcripts so you can search without downloading every file.

Install the command-line tool, then check that git, git-annex, and exiftool are available:

```bash
uv tool install image-annex
ia doctor
ia
```

`ia` lists the commands. `ia tui` opens the terminal dashboard. `image-annex` opens that same dashboard directly. `ia ingest` adds a folder, `ia gallery start` serves local thumbnails, and `ia storage status` reports what is on disk and in S3. Agents and installers should follow [llms.txt](llms.txt).

The Android photo picker is a separate repository, [image-annex-picker](android/README.md) (`~/repos/image-annex-picker` on the hub machine). Package `net.bizkite.imageannex.picker`. It is a debug CloudMediaProvider: sign in, tap Sync, then choose Image Annex as the cloud library inside the system picker. It is not on the Play Store.

This repository also contains the AWS CDK infrastructure for the archive bucket and the hosted gallery.

The core concept is based on the essay [Your Photos Are a Mess](docs/blog-post.md), which details a workflow for using `git-annex` to manage a master photo repository backed by cloud storage.

## Use

```bash
ia ingest ~/photos
ia tui
ia gallery start
ia storage status
ia --help
```

Search matches filename, path, caption, OCR, transcript, and camera text. The full command list and the Android picker steps are in [llms.txt](llms.txt).

## Docs

*   **[Install and use](llms.txt):** The short guide for people and for agents.
*   **[Hosted gallery](docs/HOSTED_GALLERY.md):** Read-only phone mirror on S3, CloudFront, and Cognito, plus the export timer.
*   **[Security](docs/SECURITY.md):** Deployment auth and secret handling.
*   **[Archive workflow](docs/ARCHIVING_WORKFLOW.md):** How the hub archive is operated.
*   **AWS CDK application:** `cdk_image_annex/`.

## Metadata & Thumbnails

*   **Metadata:** Extracted using `exiftool` and stored in a local SQLite database (`metadata.db`).
*   **Thumbnails:** Generated locally with Pillow. The hub exports thumbnail copies and `catalog.json` for the hosted gallery. Originals stay in the git-annex S3 remote, separate from that gallery prefix.

## Current Status (Dev/UAT)

This project is currently in a **Development/UAT phase**. Key points:
*   Automated testing (UAT) is performed via Docker (`Dockerfile.uat`).
*   **Limitation:** `git-annex` currently places an `annex-uuid` file at the root of the S3 bucket during `initremote`, even if a prefix is configured. This makes multi-tenant or multi-prefix use of a single bucket slightly more complex.
*   The production infrastructure is defined but should be used with caution until UAT is finalized.

## Version

Run these from this checkout:

```bash
ia version
ia version release patch
```

`ia version` prints the installed build and the latest release on PyPI. `ia version release patch` bumps the patch number, commits it, tags `vX.Y.Z`, and pushes. Use `minor` or `major` the same way. Add `--no-push` to keep the tag local.

The PyPI project page uses this README. A release published before `readme` was set in `pyproject.toml` shows an empty description until the next upload.

## Deployment

This project is deployed automatically via a GitHub Actions workflow. The deployment pipeline is configured to use a secure OIDC connection to AWS.

For details, see [docs/SECURITY.md](docs/SECURITY.md).

## Local Development

To work with the CDK infrastructure locally:

1.  **Environment Setup:**
    *   Copy `.env.template` to `.env`.
    *   Set up a Python virtual environment:
        ```bash
        python3 -m venv .venv
        source .venv/bin/activate
        pip install .
        ```
2.  **CDK Commands:**
    ```bash
    op run --env-file=.env -- cdk synth
    op run --env-file=.env -- cdk deploy
    ```
