File: docs/README.md
Version: v0.3.4
Last updated: November 2025
Maintainer: Leak Technologies
Project: Goondex

---

Goondex — PornPics Importer & ML Pipeline

A modular, documented gallery importer for PornPics.com, forming the foundation of the Goondex ecosystem.
Supports importing, tagging, metadata enrichment, and generation of ML-ready datasets for semantic search and classification.

---

1. Project Overview

---

Goondex automates the process of:

• Downloading and organizing galleries from PornPics.com
• Generating structured metadata and tag inference
• Enriching galleries via ThePornDB (TPDB) performer API
• Building machine-learning datasets and embeddings
• Enabling semantic, hybrid (text + image) search

All operations are handled locally — no cloud dependencies or external databases are required.
The system is modular, transparent, and designed for research and personal archival use.

---

2. Project Structure

---

src/ ├── importer/ → Core importer logic and CLI tools
│ ├── cli.py → Unified CLI entrypoint (goondex command)
│ ├── gallery_importer.py → Gallery parser and downloader
│ ├── tag_gallery.py → Tag inference and YAML management
│ ├── reports/ → Auto-generated validation and tag stats
│ ├── db/ → TPDB performer cache and local databases
│ ├── secrets/ → Local-only API keys (ignored by Git)
│ └── tag_dictionaries/ → Modular YAML tag dictionaries
│ ├── ml/ → Machine learning and semantic search
│ ├── ml_dataset_builder.py → Builds JSONL dataset for embeddings
│ ├── ml_embeddings.py → Generates CLIP + text hybrid vectors
│ ├── ml_dataset_inspector.py → (planned) visual dataset viewer
│ └── ml_vision_detector.py → (planned) DINO + SAM visual tagging
│ ├── docs/ → Documentation, changelogs, and brand files
├── tests/ → Unit and integration testing suite
└── assets/ → Static samples and test assets

---

3. Environment Setup

---

Create a virtual environment and install dependencies:

bash python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Set the source path for development:

bash export PYTHONPATH=src

---

4. Quick Start

---

Import a gallery from PornPics:

bash goondex import "https://www.pornpics.com/galleries/example-id/"

Automatically:

• Downloads images and metadata
• Saves to Galleries/