Etsy Shop Autopilot (Baby Agent)

Create 1,000 original print-on-demand Etsy listings in ~72 hours with a policy-safe, resumable automation pipeline.

Overview

This project builds an end-to-end automation (“baby agent”) that:

1. researches low-risk niches and keyword clusters
2. generates original designs + variants
3. upscales, removes backgrounds, validates print specs
4. uploads designs to a print-on-demand (POD) partner
5. creates and publishes Etsy listings in throttled batches
6. tracks outcomes (views/favorites/sales) to learn what to scale

Target output: 1,000 listings in ~72 hours (goal), with observability, idempotency, and platform-safe rate limiting.

---

Non-negotiables (Compliance + Safety)

• No IP infringement: no brands, celebrity names, team names, copyrighted characters, logos, “inspired by X,” etc.
• No ToS-violating scraping: use official APIs where available; throttle everything.
• Quality guardrails: unique listings, coherent SEO, clean PNGs with transparency.
• Anti-ban discipline: controlled concurrency, exponential backoff, kill switch.
• Traceability: every concept/design/listing has an ID and audit trail.

---

Architecture (High Level)

Pipeline stages:

• A. Research → niches + keyword clusters + differentiation notes
• B. Design → original design specs + variants
• C. Image processing → upscale + background removal + validation
• D. POD → upload + create product variants + fetch SKU mappings
• E. Etsy → create listing payloads + publish in batches
• F. Metrics loop → pull performance signals and prioritize next runs

Core components:

• orchestrator/ – job queue + scheduler + idempotent runs
• research/ – keyword discovery + clustering + scoring
• design/ – generator adapter + prompt templates + variation engine
• image_processing/ – upscale + BG removal + PNG validation
• pod/ – Printify/Printful client (one first, pluggable)
• etsy/ – Etsy API client + listing builder + publisher
• db/ – SQLite/Postgres schema + migrations
• observability/ – structured logs, events, run summaries
• ui/ – optional dashboard (FastAPI) or rich CLI

---

Repo Structure

etsy-autopilot/ README.md .env.example pyproject.toml src/ orchestrator/ run.py queue.py throttle.py retry.py research/ niches.py keywords.py scoring.py design/ generator.py prompts.py variants.py safety_filters.py image_processing/ upscale.py background.py validate.py pod/ client.py products.py mockups.py etsy/ auth.py client.py listings.py publish.py db/ models.py migrations/ init.sql observability/ logger.py events.py metrics.py config/ default.yaml tests/ test_keywords.py test_validate_png.py test_listing_payload.py test_idempotency.py

---

Prerequisites

• Python 3.11+
• An Etsy developer app + OAuth tokens
• A POD partner account (Printify or Printful)
• A design generation provider (pluggable; can be your local model or API)
• (Optional) Postgres if you want multi-run scaling; SQLite works for demos

---

Setup

1) Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

2) Install dependencies

pip install -U pip
pip install -r requirements.txt

3) Configure environment variables

Copy and edit:

cp .env.example .env

Minimum required variables (names may evolve with implementation):
	•	Etsy
	•	ETSY_CLIENT_ID
	•	ETSY_CLIENT_SECRET
	•	ETSY_OAUTH_TOKEN
	•	ETSY_SHOP_ID
	•	POD partner (choose one)
	•	PRINTIFY_API_KEY (and optionally PRINTIFY_SHOP_ID)
	•	or PRINTFUL_API_KEY
	•	Design generator
	•	DESIGN_PROVIDER (e.g. local, openai, stability, etc.)
	•	DESIGN_API_KEY (if applicable)
	•	Runtime
	•	DATABASE_URL (e.g. sqlite:///data.db or postgresql://...)
	•	DRY_RUN=1 (recommended first)

⸻

Running the Project

Demo Mode (10 listings end-to-end)

Creates 10 concepts → designs → processed PNGs → POD products → Etsy drafts (or publish if enabled).

python -m src.orchestrator.run --config src/config/default.yaml --demo 10

Dry Run (Generate everything except publish)

python -m src.orchestrator.run --config src/config/default.yaml --target 1000 --dry-run

Production Run (Controlled publishing)

Use only after demo + dry-run succeed:

python -m src.orchestrator.run --config src/config/default.yaml --target 1000


⸻

Key Configuration (src/config/default.yaml)

Typical knobs:
	•	target_listings: 1000
	•	time_budget_hours: 72
	•	publish_batch_size: 10
	•	publish_concurrency: 1 (start at 1; increase cautiously)
	•	design_workers: 8 (safe to parallelize)
	•	image_workers: 8
	•	pod_workers: 4
	•	rate_limits: per service (Etsy/POD/Design)
	•	pricing: margin rules + rounding
	•	product_catalog: (tee/hoodie/mug/poster)
	•	safety_filters: blocklist keywords + similarity threshold
	•	human_review_gate: on/off + sample rate

⸻

Data Model (Minimum)

Entities are created and linked in order:
	•	concepts → designs → pod_products → etsy_listings

Each step is idempotent. Re-running a job should resume rather than duplicate.

⸻

Observability & Logging
	•	Every run has a run_id.
	•	Every step emits structured events to events table + log output.
	•	Failure taxonomy is recorded (auth, rate limit, validation fail, API error).

Useful commands (examples):
	•	Show run summary:

python -m src.orchestrator.run --status last


	•	Export failures to CSV:

python -m src.orchestrator.run --export-failures failures.csv



⸻

Quality Gates

A design/listing must pass:
	•	PNG has alpha (transparent background)
	•	minimum pixel dimensions for product template
	•	no obvious artifacts after background removal
	•	title/tags follow Etsy constraints
	•	blocklist + similarity checks pass (no repeated slogans)

⸻

Anti-Ban / Rate-Limit Strategy
	•	Central throttling for each external service
	•	Exponential backoff + jitter on 429/5xx
	•	Circuit breaker for repeated failures
	•	Kill switch: set PUBLISH_ENABLED=0 or stop the run

⸻

Roadmap
	1.	MVP: demo 10 listings in dry-run
	2.	POD integration: create product variants and pull SKUs
	3.	Etsy publish: batch publishing with safe throttles
	4.	Scale: 1,000 listings with strong idempotency + retries
	5.	Feedback loop: pull performance metrics and prioritize winners

⸻

Troubleshooting

“401 Unauthorized”
	•	Verify OAuth token scopes and token freshness.
	•	Confirm shop ID and connected account.

“429 Too Many Requests”
	•	Lower publish_batch_size, reduce concurrency, increase backoff.

“Design rejected / validation failed”
	•	Check image dimensions, alpha channel, and file size limits.
	•	Review background removal edge artifacts.

⸻

Disclaimer (Practical)

This system increases throughput, but revenue is not guaranteed. The goal is to run a controlled experiment: ship a large, compliant catalog, measure signals, and scale what actually converts.

⸻

License

TBD (private experimental repo by default).