Update core/api_clients.py

core/api_clients.py

@@ -713,44 +713,226 @@ async def _hf_infer_image_with_token(
     return False
 
 
-async def generate_truly_free_image(prompt: str, out_path: str) -> bool:
+
+# ══════════════════════════════════════════════════════════════════
+#
+#   V18.5 -- HYBRID IMAGE SYSTEM
+#
+#   Priority order:
+#     1. Wikimedia Commons — real historical images, public domain, no key
+#     2. Pollinations.ai   — free AI generation, no key, no limit
+#     3. HF Inference      — paid fallback (existing system)
+#
+# ══════════════════════════════════════════════════════════════════
+
+WIKIMEDIA_API:      str   = "https://en.wikipedia.org/w/api.php"
+WIKIMEDIA_TIMEOUT:  float = 15.0
+MIN_WIKIMEDIA_BYTES: int  = 20 * 1024   # 20 KB minimum
+
+POLLINATIONS_URL:   str   = "https://image.pollinations.ai/prompt/{prompt}"
+POLLINATIONS_TIMEOUT: float = 60.0
+
+
+async def _search_wikimedia_image(search_query: str, out_path: str) -> bool:
     """
-    V16.6 -- HF Inference Image Generator with Round-Robin Token Rotation.
-
-    Step-by-step execution:
-
-      1. Guard: if no tokens are loaded (_HF_IMAGE_TOKENS is empty),
-         log an error and return False immediately.
-
-      2. Truncate `prompt` to <= HF_IMAGE_MAX_KEYWORDS (15) keywords
-         via _truncate_to_keywords().  The shortened text is sent as
-         the POST body {"inputs": "..."} -- NOT as a URL query string.
-
-      3. For each token in the pool (round-robin, starting from the
-         current cursor):
-           a. _acquire_hf_image_token() returns the next token and
-              advances the cursor atomically.
-           b. _hf_infer_image_with_token() is called:
-                - 503 model-loading: retried up to 3x / 5 s on the
-                  SAME token before giving up on it.
-                - 429 rate-limit:    returns False immediately; the
-                  loop moves to the next token at once.
-                - Other failure:     returns False; loop continues.
-                - Success (>= 30 KB saved): returns True.
-           c. On True, log success and return True to the caller.
-           d. On False, log which token failed and try the next one.
-
-      4. If all tokens are exhausted without success, log an error and
-         return False.
-
-    Returns True only when a valid image >= 30 KB has been saved.
-    Returns False (non-fatal) on complete failure -- the immersion
-    pipeline sets image_url="" for that chapter and continues.
+    Search Wikimedia Commons for a relevant historical image.
+    Uses the Wikipedia opensearch + imageinfo APIs.
+    Returns True if a valid image >= 20 KB was saved.
     """
+    try:
+        # Step 1: Find the most relevant Wikipedia article
+        async with httpx.AsyncClient(timeout=WIKIMEDIA_TIMEOUT) as client:
+            resp = await client.get(
+                WIKIMEDIA_API,
+                params={
+                    "action":   "query",
+                    "list":     "search",
+                    "srsearch": search_query,
+                    "srlimit":  1,
+                    "format":   "json",
+                },
+                headers={"User-Agent": "TitanImmersion/1.0 (educational)"},
+            )
+        if resp.status_code != 200:
+            logger.warning("[Wikimedia] Search HTTP %d", resp.status_code)
+            return False
+
+        results = resp.json().get("query", {}).get("search", [])
+        if not results:
+            logger.warning("[Wikimedia] No results for: %s", search_query[:80])
+            return False
+
+        page_title = results[0]["title"]
+        logger.info("[Wikimedia] Found article: %s", page_title)
+
+        # Step 2: Get images from that article
+        async with httpx.AsyncClient(timeout=WIKIMEDIA_TIMEOUT) as client:
+            resp = await client.get(
+                WIKIMEDIA_API,
+                params={
+                    "action":   "query",
+                    "titles":   page_title,
+                    "prop":     "images",
+                    "imlimit":  10,
+                    "format":   "json",
+                },
+                headers={"User-Agent": "TitanImmersion/1.0 (educational)"},
+            )
+
+        pages = resp.json().get("query", {}).get("pages", {})
+        images = []
+        for page in pages.values():
+            for img in page.get("images", []):
+                title = img.get("title", "")
+                # Skip icons, logos, flags, small decorative images
+                if any(skip in title.lower() for skip in [
+                    "flag", "icon", "logo", "map", "seal", "coat",
+                    "stub", "commons", "wikimedia", ".svg"
+                ]):
+                    continue
+                if title.lower().endswith((".jpg", ".jpeg", ".png")):
+                    images.append(title)
+
+        if not images:
+            logger.warning("[Wikimedia] No usable images for: %s", page_title)
+            return False
+
+        # Step 3: Get the actual URL for the first good image
+        async with httpx.AsyncClient(timeout=WIKIMEDIA_TIMEOUT) as client:
+            resp = await client.get(
+                WIKIMEDIA_API,
+                params={
+                    "action":    "query",
+                    "titles":    images[0],
+                    "prop":      "imageinfo",
+                    "iiprop":    "url|size",
+                    "iiurlwidth": 800,
+                    "format":    "json",
+                },
+                headers={"User-Agent": "TitanImmersion/1.0 (educational)"},
+            )
+
+        pages = resp.json().get("query", {}).get("pages", {})
+        img_url = None
+        for page in pages.values():
+            info = page.get("imageinfo", [])
+            if info:
+                img_url = info[0].get("thumburl") or info[0].get("url")
+                break
+
+        if not img_url:
+            logger.warning("[Wikimedia] No URL for image: %s", images[0])
+            return False
+
+        # Step 4: Download the image
+        async with httpx.AsyncClient(timeout=WIKIMEDIA_TIMEOUT) as client:
+            resp = await client.get(
+                img_url,
+                headers={"User-Agent": "TitanImmersion/1.0 (educational)"},
+                follow_redirects=True,
+            )
+
+        if resp.status_code != 200:
+            logger.warning("[Wikimedia] Download HTTP %d", resp.status_code)
+            return False
+
+        img_bytes = resp.content
+        if len(img_bytes) < MIN_WIKIMEDIA_BYTES:
+            logger.warning("[Wikimedia] Image too small: %d B", len(img_bytes))
+            return False
+
+        with open(out_path, "wb") as fh:
+            fh.write(img_bytes)
+
+        logger.info(
+            "[Wikimedia] ✅ Saved %s (%.1f KB) from: %s",
+            out_path, len(img_bytes) / 1024, page_title,
+        )
+        return True
+
+    except Exception as exc:
+        logger.warning("[Wikimedia] Exception: %s", exc)
+        return False
+
+
+async def _generate_via_pollinations(prompt: str, out_path: str) -> bool:
+    """
+    Generate image via Pollinations.ai — free, no API key, no rate limit.
+    Returns True if a valid image >= 20 KB was saved.
+    """
+    try:
+        safe = urllib.parse.quote(prompt[:500])
+        url  = f"https://image.pollinations.ai/prompt/{safe}?width=800&height=600&nologo=true"
+
+        logger.info("[Pollinations] Requesting image | prompt_len=%d", len(prompt))
+        async with httpx.AsyncClient(timeout=POLLINATIONS_TIMEOUT) as client:
+            resp = await client.get(url, follow_redirects=True)
+
+        if resp.status_code != 200:
+            logger.warning("[Pollinations] HTTP %d", resp.status_code)
+            return False
+
+        img_bytes = resp.content
+        if len(img_bytes) < MIN_WIKIMEDIA_BYTES:
+            logger.warning("[Pollinations] Image too small: %d B", len(img_bytes))
+            return False
+
+        with open(out_path, "wb") as fh:
+            fh.write(img_bytes)
+
+        logger.info(
+            "[Pollinations] ✅ Saved %s (%.1f KB)",
+            out_path, len(img_bytes) / 1024,
+        )
+        return True
+
+    except Exception as exc:
+        logger.warning("[Pollinations] Exception: %s", exc)
+        return False
+
+
+async def generate_truly_free_image(
+    prompt: str,
+    out_path: str,
+    search_query: str = "",
+) -> bool:
+    """
+    V18.5 -- Hybrid Image System.
+
+    Priority order:
+      1. Wikimedia Commons  — real historical images, public domain, no key
+         Uses search_query (historical_anchor event + year) if provided.
+      2. Pollinations.ai    — free AI generation, no key, no rate limit
+         Uses the cinematic_image_prompt.
+      3. HF Inference       — paid fallback (existing token pool system)
+
+    Returns True when any provider saves a valid image.
+    Returns False (non-fatal) — pipeline sets image_url="" and continues.
+    """
+    # ── Stage 1: Wikimedia Commons ──────────────────────────────────
+    if search_query.strip():
+        logger.info("[Image/Hybrid] Stage 1: Wikimedia | query='%.80s'", search_query)
+        ok = await _search_wikimedia_image(search_query, out_path)
+        if ok:
+            logger.info("[Image/Hybrid] ✅ Wikimedia success")
+            return True
+        logger.info("[Image/Hybrid] Wikimedia failed — trying Pollinations")
+    else:
+        logger.info("[Image/Hybrid] No search_query — skipping Wikimedia")
+
+    # ── Stage 2: Pollinations.ai ─────────────────────────────────────
+    logger.info("[Image/Hybrid] Stage 2: Pollinations | prompt_len=%d", len(prompt))
+    ok = await _generate_via_pollinations(prompt, out_path)
+    if ok:
+        logger.info("[Image/Hybrid] ✅ Pollinations success")
+        return True
+    logger.info("[Image/Hybrid] Pollinations failed — trying HF tokens")
+
+    # ── Stage 3: HF Inference (existing paid system) ─────────────────
     if not _HF_IMAGE_TOKENS:
         logger.error(
-            "[HF-Image] Token pool empty -- set HF_TOKEN1 through HF_TOKEN8. "
-            "Skipping image generation for this chapter."
+            "[Image/Hybrid] All stages failed — no HF tokens available. "
+            "Setting image_url='' for this chapter."
         )
         return False