luckiest-co 1.0.0 → 1.0.3

package/skills/luckiest-trends/scripts/lib/preflight.py

@@ -0,0 +1,119 @@
+"""Engine-side query-quality pre-flight.
+
+Detects Class 1 (demographic shopping) keyword-trap queries and returns a
+structured REFUSE message. The caller (scripts/last30days.py main()) writes
+the message to stderr and exits code 2. No pipeline work runs on a doomed
+query; the model sees the REFUSE on stderr and asks the user for the
+hobbies/relationship/budget context it needs.
+
+Patterns ported from SKILL.md Step 0.45 prose. Only Class 1 is implemented
+here because it has a verified failure mode on v3.0.8 (2026-04-18 'birthday
+gift for 40 year old' run returned r/todayilearned and unrelated drama
+posts).
+"""
+
+from __future__ import annotations
+
+import re
+
+_CLASS_1_PATTERNS = [
+    re.compile(
+        r"^\s*(birthday\s+)?(gift|gifts|present|presents)\s+"
+        r"(for|ideas\s+for)\s+(a\s+|my\s+)?\d+[\s-]?year[\s-]?old\b",
+        re.IGNORECASE,
+    ),
+    re.compile(
+        r"^\s*(best|top)\s+[\w\s-]+?\s+for\s+"
+        r"(men|women|kids|guys|girls|teens|dads|moms|husbands|wives|brothers|sisters|friends)\b",
+        re.IGNORECASE,
+    ),
+    re.compile(
+        r"^\s*what\s+to\s+(buy|get|gift)\s+(for\s+)?(a\s+|my\s+)?"
+        r"(\d+[\s-]?year[\s-]?old|husband|wife|dad|mom|brother|sister|friend|boss|coworker)\b",
+        re.IGNORECASE,
+    ),
+    re.compile(
+        r"^\s*(present|presents|gift|gifts)\s+for\s+(a\s+|my\s+)?"
+        r"(husband|wife|dad|mom|brother|sister|friend|boss|coworker)\b",
+        re.IGNORECASE,
+    ),
+]
+
+_QUALIFIER_PATTERNS = [
+    re.compile(r"\$\d+"),
+    re.compile(r"\bbudget\b", re.IGNORECASE),
+    re.compile(r"\bwho\s+(loves|likes|is\s+into|enjoys)\b", re.IGNORECASE),
+    re.compile(r"\bhobbies?\b", re.IGNORECASE),
+    re.compile(r"\b(cooking|running|reading|gaming|golf|woodworking|coding|hiking|cycling|fishing|music)[\s-]?(obsessed|enthusiast|fan|lover)\b", re.IGNORECASE),
+]
+
+_RELATIONSHIP_WORDS = {
+    "husband", "wife", "dad", "mom", "father", "mother", "brother", "sister",
+    "friend", "boss", "coworker", "son", "daughter", "grandma", "grandpa",
+    "aunt", "uncle", "nephew", "niece", "partner", "boyfriend", "girlfriend",
+}
+
+_YEAR_OLD_NOUN = re.compile(r"\byear[\s-]?old\s+(\w+)", re.IGNORECASE)
+
+
+def _has_qualifier(topic: str) -> bool:
+    """Return True if the topic contains hobbies/relationship/budget context.
+
+    A Class 1 base pattern plus a qualifier means the user already filled in
+    the specificity Step 0.45 would ask for. Skip the refuse-gate and let
+    the engine run.
+
+    Also skips when `{n} year old <activity-noun>` is present, but only when
+    the noun is NOT a relationship word. 'year old runner' qualifies as an
+    interest and skips; 'year old husband' is just another relationship
+    reframing of the demographic query and does not skip.
+    """
+    if any(pattern.search(topic) for pattern in _QUALIFIER_PATTERNS):
+        return True
+
+    match = _YEAR_OLD_NOUN.search(topic)
+    if match and match.group(1).lower() not in _RELATIONSHIP_WORDS:
+        return True
+
+    return False
+
+
+def check_class_1_trap(topic: str) -> str | None:
+    """Return a REFUSE message string if the topic matches Class 1, else None.
+
+    Class 1 is the demographic-shopping keyword trap. The literal phrase
+    'birthday gift for 40 year old' is not the vocabulary of actual gift
+    discussions on Reddit, X, or TikTok, so running the engine returns
+    low-signal generic posts. Refuse up-front and ask for context.
+    """
+    if not topic:
+        return None
+
+    matched = any(pattern.search(topic) for pattern in _CLASS_1_PATTERNS)
+    if not matched:
+        return None
+
+    if _has_qualifier(topic):
+        return None
+
+    return _refuse_message(topic.strip())
+
+
+def _refuse_message(topic: str) -> str:
+    return (
+        f'[last30days] REFUSE: topic "{topic}" matches Class 1 keyword-trap '
+        "pattern (demographic shopping).\n"
+        "\n"
+        "The literal phrase is not the vocabulary of actual gift discussions "
+        "on Reddit, X, or TikTok. Running the engine will return low-signal "
+        "generic posts (the 2026-04-18 validation run returned "
+        "r/todayilearned and unrelated drama).\n"
+        "\n"
+        "Ask the user for at least one of:\n"
+        "  - hobbies (cooks / runs / reads / gaming / outdoors / golf / music)\n"
+        "  - relationship (husband / dad / friend / boss / brother)\n"
+        "  - budget range\n"
+        "\n"
+        "Then re-run with the enriched query. If the user insists 'just run it',\n"
+        "re-invoke with LAST30DAYS_SKIP_PREFLIGHT=1 to bypass this gate.\n"
+    )

package/skills/luckiest-trends/scripts/lib/providers.py

@@ -0,0 +1,380 @@
+"""Static provider catalog and runtime client implementations."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from typing import Any
+
+from . import env, http, schema
+
+GEMINI_FLASH_LITE = "gemini-3.1-flash-lite"
+GEMINI_PRO = "gemini-3.1-pro-preview"
+OPENAI_DEFAULT = "gpt-5.4-nano"
+XAI_DEFAULT = "grok-4-1-fast"
+
+GEMINI_URL = "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={api_key}"
+OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses"
+XAI_RESPONSES_URL = "https://api.x.ai/v1/responses"
+OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+# OpenRouter routes the Gemini Flash Lite tier as the -preview slug; that is the
+# stable form on that routing layer even though native Gemini's GEMINI_FLASH_LITE
+# constant is suffix-free. If GEMINI_FLASH_LITE moves to a non-preview stable ID,
+# double-check that OpenRouter's slug still maps to the same upstream model.
+OPENROUTER_DEFAULT = "google/gemini-3.1-flash-lite-preview"
+
+
+class ReasoningClient:
+    """Shared interface for planner and rerank providers."""
+
+    name: str
+
+    def generate_text(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        response_mime_type: str | None = None,
+    ) -> str:
+        raise NotImplementedError
+
+    def generate_json(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        text = self.generate_text(model, prompt, tools=tools, response_mime_type="application/json")
+        return extract_json(text)
+
+
+class GeminiClient(ReasoningClient):
+    name = "gemini"
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def _generate_content(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        response_mime_type: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {"temperature": 0},
+        }
+        if response_mime_type:
+            body["generationConfig"]["responseMimeType"] = response_mime_type
+        if tools:
+            body["tools"] = tools
+        return http.post(
+            GEMINI_URL.format(model=model, api_key=self.api_key),
+            body,
+            headers={"Content-Type": "application/json"},
+            timeout=90,
+        )
+
+    def generate_text(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        response_mime_type: str | None = None,
+    ) -> str:
+        payload = self._generate_content(
+            model,
+            prompt,
+            tools=tools,
+            response_mime_type=response_mime_type,
+        )
+        return extract_gemini_text(payload)
+
+class OpenAIClient(ReasoningClient):
+    name = "openai"
+
+    def __init__(self, token: str):
+        self.token = token
+
+    def generate_text(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        response_mime_type: str | None = None,
+    ) -> str:
+        del tools, response_mime_type
+        payload = {
+            "model": model,
+            "store": False,
+            "input": prompt,
+            "temperature": 0,
+        }
+        response = http.post(
+            os.environ.get("OPENAI_BASE_URL", OPENAI_RESPONSES_URL),
+            payload,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json",
+            },
+            timeout=90,
+        )
+        return extract_openai_text(response)
+
+
+class XAIClient(ReasoningClient):
+    name = "xai"
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def generate_text(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        response_mime_type: str | None = None,
+    ) -> str:
+        del tools, response_mime_type
+        payload = {
+            "model": model,
+            "input": [{"role": "user", "content": prompt}],
+        }
+        response = http.post(
+            os.environ.get("XAI_BASE_URL", XAI_RESPONSES_URL),
+            payload,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=90,
+        )
+        return extract_openai_text(response)
+
+
+class OpenRouterClient(ReasoningClient):
+    name = "openrouter"
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def generate_text(
+        self,
+        model: str,
+        prompt: str,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        response_mime_type: str | None = None,
+    ) -> str:
+        del tools, response_mime_type
+        payload = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+        }
+        response = http.post(
+            OPENROUTER_URL,
+            payload,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=90,
+        )
+        return extract_openai_text(response)
+
+
+_MODEL_DEFAULTS: dict[str, tuple[str, str]] = {
+    "gemini": (GEMINI_FLASH_LITE, GEMINI_FLASH_LITE),
+    "openai": (OPENAI_DEFAULT, OPENAI_DEFAULT),
+    "xai": (XAI_DEFAULT, XAI_DEFAULT),
+    "openrouter": (OPENROUTER_DEFAULT, OPENROUTER_DEFAULT),
+}
+
+
+def _resolve_model_pins(config: dict[str, Any], depth: str, provider_name: str) -> tuple[str, str, str]:
+    """Resolve planner, rerank, and grounding model pins for a provider."""
+    default_planner, default_rerank = _MODEL_DEFAULTS.get(provider_name, (GEMINI_FLASH_LITE, GEMINI_FLASH_LITE))
+    if depth == "deep" and provider_name == "gemini":
+        default_rerank = GEMINI_PRO
+
+    planner_model = config.get("LAST30DAYS_PLANNER_MODEL") or default_planner
+    rerank_model = config.get("LAST30DAYS_RERANK_MODEL") or default_rerank
+
+    if provider_name == "gemini":
+        _require_gemini_31(planner_model, role="planner")
+        _require_gemini_31(rerank_model, role="rerank")
+
+    return planner_model, rerank_model
+
+
+def mock_runtime(config: dict[str, Any], depth: str) -> schema.ProviderRuntime:
+    """Resolve model pins for mock mode without requiring live credentials."""
+    provider_name = (config.get("LAST30DAYS_REASONING_PROVIDER") or "gemini").lower()
+    if provider_name == "auto":
+        provider_name = "gemini"
+    if provider_name not in _MODEL_DEFAULTS:
+        raise RuntimeError(f"Unsupported reasoning provider: {provider_name}")
+
+    planner_model, rerank_model = _resolve_model_pins(config, depth, provider_name)
+    return schema.ProviderRuntime(
+        reasoning_provider=provider_name,
+        planner_model=planner_model,
+        rerank_model=rerank_model,
+
+        x_search_backend=_resolve_x_backend(config),
+    )
+
+
+def resolve_runtime(config: dict[str, Any], depth: str) -> tuple[schema.ProviderRuntime, ReasoningClient | None]:
+    """Resolve the reasoning provider and pinned models."""
+    provider_name = (config.get("LAST30DAYS_REASONING_PROVIDER") or "auto").lower()
+    google_key = config.get("GOOGLE_API_KEY") or config.get("GEMINI_API_KEY") or config.get("GOOGLE_GENAI_API_KEY")
+    openai_token = config.get("OPENAI_API_KEY")
+    xai_key = config.get("XAI_API_KEY")
+
+    if provider_name == "auto":
+        if google_key:
+            provider_name = "gemini"
+        elif openai_token and config.get("OPENAI_AUTH_STATUS") == env.AUTH_STATUS_OK:
+            provider_name = "openai"
+        elif xai_key:
+            provider_name = "xai"
+        elif config.get("OPENROUTER_API_KEY"):
+            provider_name = "openrouter"
+        else:
+            return schema.ProviderRuntime(
+                reasoning_provider="local",
+                planner_model="deterministic",
+                rerank_model="local-score",
+                x_search_backend=_resolve_x_backend(config),
+            ), None
+
+    planner_model, rerank_model = _resolve_model_pins(config, depth, provider_name)
+
+    if provider_name == "gemini":
+        if not google_key:
+            raise RuntimeError("Gemini selected but no Google API key is configured.")
+        runtime = schema.ProviderRuntime(
+            reasoning_provider="gemini",
+            planner_model=planner_model,
+            rerank_model=rerank_model,
+    
+            x_search_backend=_resolve_x_backend(config),
+        )
+        return runtime, GeminiClient(google_key)
+
+    if provider_name == "openai":
+        if not openai_token or config.get("OPENAI_AUTH_STATUS") != env.AUTH_STATUS_OK:
+            raise RuntimeError("OpenAI selected but no valid OpenAI auth is configured.")
+        runtime = schema.ProviderRuntime(
+            reasoning_provider="openai",
+            planner_model=planner_model,
+            rerank_model=rerank_model,
+    
+            x_search_backend=_resolve_x_backend(config),
+        )
+        return runtime, OpenAIClient(
+            openai_token
+        )
+
+    if provider_name == "xai":
+        if not xai_key:
+            raise RuntimeError("xAI selected but XAI_API_KEY is not configured.")
+        runtime = schema.ProviderRuntime(
+            reasoning_provider="xai",
+            planner_model=planner_model,
+            rerank_model=rerank_model,
+    
+            x_search_backend=_resolve_x_backend(config),
+        )
+        return runtime, XAIClient(xai_key)
+
+    if provider_name == "openrouter":
+        openrouter_key = config.get("OPENROUTER_API_KEY")
+        if not openrouter_key:
+            raise RuntimeError("OpenRouter selected but OPENROUTER_API_KEY is not configured.")
+        runtime = schema.ProviderRuntime(
+            reasoning_provider="openrouter",
+            planner_model=planner_model,
+            rerank_model=rerank_model,
+            x_search_backend=_resolve_x_backend(config),
+        )
+        return runtime, OpenRouterClient(openrouter_key)
+
+    raise RuntimeError(f"Unsupported reasoning provider: {provider_name}")
+
+
+def _resolve_x_backend(config: dict[str, Any]) -> str | None:
+    preferred = (config.get("LAST30DAYS_X_BACKEND") or "").lower()
+    if preferred in {"xai", "bird"}:
+        return preferred
+    return env.get_x_source(config)
+
+
+def _require_gemini_31(model: str, *, role: str) -> None:
+    if model.startswith("gemini-3.1-"):
+        return
+    raise RuntimeError(
+        f"{role} must use a Gemini 3.1 model. Got: {model}"
+    )
+
+
+def extract_json(text: str) -> dict[str, Any]:
+    """Extract the first JSON object from a model response."""
+    text = text.strip()
+    if not text:
+        raise ValueError("Expected JSON response, got empty text")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        match = re.search(r"\{[\s\S]*\}", text)
+        if not match:
+            raise
+        return json.loads(match.group(0))
+
+
+def extract_gemini_text(payload: dict[str, Any]) -> str:
+    for candidate in payload.get("candidates", []):
+        content = candidate.get("content") or {}
+        for part in content.get("parts", []):
+            text = part.get("text")
+            if text:
+                return text
+    if payload:
+        print(f"[Providers] extract_gemini_text: no text in payload keys: {list(payload.keys())}", file=sys.stderr)
+    return ""
+
+
+def extract_openai_text(payload: dict[str, Any]) -> str:
+    if isinstance(payload.get("output_text"), str):
+        return payload["output_text"]
+    output = payload.get("output") or payload.get("choices") or []
+    for item in output:
+        if isinstance(item, str):
+            return item
+        if isinstance(item, dict):
+            if isinstance(item.get("text"), str):
+                return item["text"]
+            content = item.get("content") or []
+            if isinstance(content, list):
+                for part in content:
+                    if isinstance(part, dict) and isinstance(part.get("text"), str):
+                        return part["text"]
+                    if isinstance(part, dict) and part.get("type") == "output_text" and isinstance(part.get("text"), str):
+                        return part["text"]
+            message = item.get("message") or {}
+            if isinstance(message, dict) and isinstance(message.get("content"), str):
+                return message["content"]
+    if payload:
+        print(f"[Providers] extract_openai_text: no text in payload keys: {list(payload.keys())}", file=sys.stderr)
+    return ""