PawForge AI

Autonomous print-on-demand platform that scopes breed-specific dog and cat merch into a fully observable, controlled workflow with production-grade guardrails.

Quickstart

python -m venv .venv
.venv\Scripts\activate
pip install -e .[testing]
uvicorn pawforge_ai.api.main:app --reload

Key features

• Control plane: FastAPI exposes health, provider readiness, scheduler state, readiness/preflight blockers, killswitch/pause/resume controls, workflow triggers, approvals, failure/dead-letter handling, exports, alert/event tracking, and live-mode gating endpoints.
• Production-grade guardrails: GLOBAL_DRY_RUN, OUTBOUND_KILL_SWITCH, live-mode confirmation, typed failure categories, durable approvals, idempotent operations, and explicit scheduler controls keep every execution traceable and predictable.
• Real provider adapters: Printify, Shopify Admin GraphQL, and Instagram Graph adapters validate credentials, run honest health checks (configured/live/dry-run state) with explicit missing_requirements, classify per-provider failures, and honor dry-run plus kill-switch controls. These adapters remain PROVIDER-CONSTRAINED until valid secrets arrive; notification hooks are still STUB until wired to actual APIs.
• Idempotent publishing: IdempotentOperation entries prevent duplicated listings and guarantee publish attempts are logged per provider.
• Alerting & event tracking: AlertEvent rows (accessed via /alerts and /alerts/summary) persist provider auth failures, readiness blockers, dead-letter growth, scheduler hiccups, and repeated workflow failures until resolved with /alerts/{id}/resolve.
• OpenClaw exports: exports/openclaw/pawforge_openclaw_ready.json is a deterministic snapshot of Orchestrator.export_openclaw(); regenerate it via /exports/openclaw/generate and back it up before every release.
• Provider health & readiness truth: /providers/health and /readiness/preflight now rely on the adapters' honest ProviderHealth responses, so each platform reports details, configured, mode, and explicit missing_requirements along with the timezone-aware preflight timestamp.
• Failure metadata & audit: DeadLetterEntry rows store the failure category, retryability flag, operator hint, and remediation text so /dead-letter surfaces rich context for every operator investigation.
• Timezone-aware timestamps: Control-state marks, scheduler events, failure/lookup history, and readiness reports now publish UTC-aware ISO timestamps for consistent auditing.

Environment & configuration

Copy .env.example and populate keys before running production workflows:

• PAWFORGE_ENVIRONMENT=local|dev|staging|preprod|prod
• GLOBAL_DRY_RUN=true (defaults to true in local/dev to prevent live actions until you explicitly enable live mode)
• OUTBOUND_KILL_SWITCH=true (safety default; disable only when you intentionally need outbound publishing)
• PAWFORGE_LIVE_MODE=false (live mode must be toggled via /live-mode/enable?confirm=true and a clean readiness report)
• PRINTIFY_API_URL, PRINTIFY_API_KEY, PRINTIFY_SHOP_ID, PRINTIFY_BLUEPRINT_ID (missing values are surfaced under missing_requirements in /providers/health)
• SHOPIFY_STORE_URL, SHOPIFY_ADMIN_TOKEN, SHOPIFY_API_VERSION
• INSTAGRAM_GRAPH_URL, INSTAGRAM_USER_ID, INSTAGRAM_ACCESS_TOKEN
• PAWFORGE_DATABASE_URL=sqlite:///./pawforge_ai.sqlite3 (override to point to PostgreSQL)
• PAWFORGE_SCHEDULER_ENABLED=true (false for manual trigger scenarios)

Provider integrations are PROVIDER-CONSTRAINED until credentials are supplied, and notification hooks remain STUB until you wire them to real services.

Operational control plane

• /status/scheduler reports running state, job IDs, paused/kill-switch flags, and the last scheduler event.
• /status/readiness summarizes environment, live/dry state, scheduler health, provider readiness, failure/dead-letter counts, and blockers.
• /readiness/preflight runs a live-mode readiness check; until it reports healthy, /live-mode/enable?confirm=true remains forbidden.
• /live-mode reflects the current mode (live_enabled, dry_run, kill_switch, environment). /live-mode/enable?confirm=true enforces a preflight and only flips the live flag when no blockers remain.
• /control/pause, /control/resume, /control/kill-switch, and /providers/health keep operator control tight and expose real adapter reasons.

Backups

Run python scripts/backup_state.py to snapshot the SQLite database and the OpenClaw export bundle before any deployment or configuration change.

Tests

py -3 -m pytest

Readiness Notes

• This repo supports dry-run safeguards.
• External provider credentials are still required for real integrations.
• Production use requires manual operator review.