Initial commit: last30days skill

Research topics across Reddit + X from the last 30 days using
OpenAI and xAI APIs. Features:
- Auto model selection (GPT-5.x, Grok-3)
- Popularity-aware scoring (relevance + recency + engagement)
- Reddit thread enrichment with real metrics
- Near-duplicate detection
- Multiple emit modes (compact, json, context, path)
- 24h caching with --refresh bypass
- NUX for API key setup
- 87 passing unit tests

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

scripts/lib/__init__.py

@@ -0,0 +1 @@
+# last30days library modules

scripts/lib/cache.py

@@ -0,0 +1,119 @@
+"""Caching utilities for last30days skill."""
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+CACHE_DIR = Path.home() / ".cache" / "last30days"
+DEFAULT_TTL_HOURS = 24
+MODEL_CACHE_TTL_DAYS = 7
+
+
+def ensure_cache_dir():
+    """Ensure cache directory exists."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_cache_key(topic: str, from_date: str, to_date: str, sources: str) -> str:
+    """Generate a cache key from query parameters."""
+    key_data = f"{topic}|{from_date}|{to_date}|{sources}"
+    return hashlib.sha256(key_data.encode()).hexdigest()[:16]
+
+
+def get_cache_path(cache_key: str) -> Path:
+    """Get path to cache file."""
+    return CACHE_DIR / f"{cache_key}.json"
+
+
+def is_cache_valid(cache_path: Path, ttl_hours: int = DEFAULT_TTL_HOURS) -> bool:
+    """Check if cache file exists and is within TTL."""
+    if not cache_path.exists():
+        return False
+
+    try:
+        stat = cache_path.stat()
+        mtime = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
+        now = datetime.now(timezone.utc)
+        age_hours = (now - mtime).total_seconds() / 3600
+        return age_hours < ttl_hours
+    except OSError:
+        return False
+
+
+def load_cache(cache_key: str, ttl_hours: int = DEFAULT_TTL_HOURS) -> Optional[dict]:
+    """Load data from cache if valid."""
+    cache_path = get_cache_path(cache_key)
+
+    if not is_cache_valid(cache_path, ttl_hours):
+        return None
+
+    try:
+        with open(cache_path, 'r') as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save_cache(cache_key: str, data: dict):
+    """Save data to cache."""
+    ensure_cache_dir()
+    cache_path = get_cache_path(cache_key)
+
+    try:
+        with open(cache_path, 'w') as f:
+            json.dump(data, f)
+    except OSError:
+        pass  # Silently fail on cache write errors
+
+
+def clear_cache():
+    """Clear all cache files."""
+    if CACHE_DIR.exists():
+        for f in CACHE_DIR.glob("*.json"):
+            try:
+                f.unlink()
+            except OSError:
+                pass
+
+
+# Model selection cache (longer TTL)
+MODEL_CACHE_FILE = CACHE_DIR / "model_selection.json"
+
+
+def load_model_cache() -> dict:
+    """Load model selection cache."""
+    if not is_cache_valid(MODEL_CACHE_FILE, MODEL_CACHE_TTL_DAYS * 24):
+        return {}
+
+    try:
+        with open(MODEL_CACHE_FILE, 'r') as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_model_cache(data: dict):
+    """Save model selection cache."""
+    ensure_cache_dir()
+    try:
+        with open(MODEL_CACHE_FILE, 'w') as f:
+            json.dump(data, f)
+    except OSError:
+        pass
+
+
+def get_cached_model(provider: str) -> Optional[str]:
+    """Get cached model selection for a provider."""
+    cache = load_model_cache()
+    return cache.get(provider)
+
+
+def set_cached_model(provider: str, model: str):
+    """Cache model selection for a provider."""
+    cache = load_model_cache()
+    cache[provider] = model
+    cache['updated_at'] = datetime.now(timezone.utc).isoformat()
+    save_model_cache(cache)

scripts/lib/dates.py

@@ -0,0 +1,124 @@
+"""Date utilities for last30days skill."""
+
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Tuple
+
+
+def get_date_range(days: int = 30) -> Tuple[str, str]:
+    """Get the date range for the last N days.
+
+    Returns:
+        Tuple of (from_date, to_date) as YYYY-MM-DD strings
+    """
+    today = datetime.now(timezone.utc).date()
+    from_date = today - timedelta(days=days)
+    return from_date.isoformat(), today.isoformat()
+
+
+def parse_date(date_str: Optional[str]) -> Optional[datetime]:
+    """Parse a date string in various formats.
+
+    Supports: YYYY-MM-DD, ISO 8601, Unix timestamp
+    """
+    if not date_str:
+        return None
+
+    # Try Unix timestamp (from Reddit)
+    try:
+        ts = float(date_str)
+        return datetime.fromtimestamp(ts, tz=timezone.utc)
+    except (ValueError, TypeError):
+        pass
+
+    # Try ISO formats
+    formats = [
+        "%Y-%m-%d",
+        "%Y-%m-%dT%H:%M:%S",
+        "%Y-%m-%dT%H:%M:%SZ",
+        "%Y-%m-%dT%H:%M:%S%z",
+        "%Y-%m-%dT%H:%M:%S.%f%z",
+    ]
+
+    for fmt in formats:
+        try:
+            return datetime.strptime(date_str, fmt).replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+
+    return None
+
+
+def timestamp_to_date(ts: Optional[float]) -> Optional[str]:
+    """Convert Unix timestamp to YYYY-MM-DD string."""
+    if ts is None:
+        return None
+    try:
+        dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+        return dt.date().isoformat()
+    except (ValueError, TypeError, OSError):
+        return None
+
+
+def get_date_confidence(date_str: Optional[str], from_date: str, to_date: str) -> str:
+    """Determine confidence level for a date.
+
+    Args:
+        date_str: The date to check (YYYY-MM-DD or None)
+        from_date: Start of valid range (YYYY-MM-DD)
+        to_date: End of valid range (YYYY-MM-DD)
+
+    Returns:
+        'high', 'med', or 'low'
+    """
+    if not date_str:
+        return 'low'
+
+    try:
+        dt = datetime.strptime(date_str, "%Y-%m-%d").date()
+        start = datetime.strptime(from_date, "%Y-%m-%d").date()
+        end = datetime.strptime(to_date, "%Y-%m-%d").date()
+
+        if start <= dt <= end:
+            return 'high'
+        elif dt < start:
+            # Older than range
+            return 'low'
+        else:
+            # Future date (suspicious)
+            return 'low'
+    except ValueError:
+        return 'low'
+
+
+def days_ago(date_str: Optional[str]) -> Optional[int]:
+    """Calculate how many days ago a date is.
+
+    Returns None if date is invalid or missing.
+    """
+    if not date_str:
+        return None
+
+    try:
+        dt = datetime.strptime(date_str, "%Y-%m-%d").date()
+        today = datetime.now(timezone.utc).date()
+        delta = today - dt
+        return delta.days
+    except ValueError:
+        return None
+
+
+def recency_score(date_str: Optional[str], max_days: int = 30) -> int:
+    """Calculate recency score (0-100).
+
+    0 days ago = 100, max_days ago = 0, clamped.
+    """
+    age = days_ago(date_str)
+    if age is None:
+        return 0  # Unknown date gets worst score
+
+    if age < 0:
+        return 100  # Future date (treat as today)
+    if age >= max_days:
+        return 0
+
+    return int(100 * (1 - age / max_days))

scripts/lib/dedupe.py

@@ -0,0 +1,120 @@
+"""Near-duplicate detection for last30days skill."""
+
+import re
+from typing import List, Set, Tuple, Union
+
+from . import schema
+
+
+def normalize_text(text: str) -> str:
+    """Normalize text for comparison.
+
+    - Lowercase
+    - Remove punctuation
+    - Collapse whitespace
+    """
+    text = text.lower()
+    text = re.sub(r'[^\w\s]', ' ', text)
+    text = re.sub(r'\s+', ' ', text)
+    return text.strip()
+
+
+def get_ngrams(text: str, n: int = 3) -> Set[str]:
+    """Get character n-grams from text."""
+    text = normalize_text(text)
+    if len(text) < n:
+        return {text}
+    return {text[i:i+n] for i in range(len(text) - n + 1)}
+
+
+def jaccard_similarity(set1: Set[str], set2: Set[str]) -> float:
+    """Compute Jaccard similarity between two sets."""
+    if not set1 or not set2:
+        return 0.0
+    intersection = len(set1 & set2)
+    union = len(set1 | set2)
+    return intersection / union if union > 0 else 0.0
+
+
+def get_item_text(item: Union[schema.RedditItem, schema.XItem]) -> str:
+    """Get comparable text from an item."""
+    if isinstance(item, schema.RedditItem):
+        return item.title
+    else:
+        return item.text
+
+
+def find_duplicates(
+    items: List[Union[schema.RedditItem, schema.XItem]],
+    threshold: float = 0.7,
+) -> List[Tuple[int, int]]:
+    """Find near-duplicate pairs in items.
+
+    Args:
+        items: List of items to check
+        threshold: Similarity threshold (0-1)
+
+    Returns:
+        List of (i, j) index pairs where i < j and items are similar
+    """
+    duplicates = []
+
+    # Pre-compute n-grams
+    ngrams = [get_ngrams(get_item_text(item)) for item in items]
+
+    for i in range(len(items)):
+        for j in range(i + 1, len(items)):
+            similarity = jaccard_similarity(ngrams[i], ngrams[j])
+            if similarity >= threshold:
+                duplicates.append((i, j))
+
+    return duplicates
+
+
+def dedupe_items(
+    items: List[Union[schema.RedditItem, schema.XItem]],
+    threshold: float = 0.7,
+) -> List[Union[schema.RedditItem, schema.XItem]]:
+    """Remove near-duplicates, keeping highest-scored item.
+
+    Args:
+        items: List of items (should be pre-sorted by score descending)
+        threshold: Similarity threshold
+
+    Returns:
+        Deduplicated items
+    """
+    if len(items) <= 1:
+        return items
+
+    # Find duplicate pairs
+    dup_pairs = find_duplicates(items, threshold)
+
+    # Mark indices to remove (always remove the lower-scored one)
+    # Since items are pre-sorted by score, the second index is always lower
+    to_remove = set()
+    for i, j in dup_pairs:
+        # Keep the higher-scored one (lower index in sorted list)
+        if items[i].score >= items[j].score:
+            to_remove.add(j)
+        else:
+            to_remove.add(i)
+
+    # Return items not marked for removal
+    return [item for idx, item in enumerate(items) if idx not in to_remove]
+
+
+def dedupe_reddit(
+    items: List[schema.RedditItem],
+    threshold: float = 0.7,
+) -> List[schema.RedditItem]:
+    """Dedupe Reddit items."""
+    return dedupe_items(items, threshold)
+
+
+def dedupe_x(
+    items: List[schema.XItem],
+    threshold: float = 0.7,
+) -> List[schema.XItem]:
+    """Dedupe X items."""
+    return dedupe_items(items, threshold)

scripts/lib/env.py

@@ -0,0 +1,102 @@
+"""Environment and API key management for last30days skill."""
+
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+CONFIG_DIR = Path.home() / ".config" / "last30days"
+CONFIG_FILE = CONFIG_DIR / ".env"
+
+
+def load_env_file(path: Path) -> Dict[str, str]:
+    """Load environment variables from a file."""
+    env = {}
+    if not path.exists():
+        return env
+
+    with open(path, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            if '=' in line:
+                key, _, value = line.partition('=')
+                key = key.strip()
+                value = value.strip()
+                # Remove quotes if present
+                if value and value[0] in ('"', "'") and value[-1] == value[0]:
+                    value = value[1:-1]
+                if key and value:
+                    env[key] = value
+    return env
+
+
+def get_config() -> Dict[str, Any]:
+    """Load configuration from ~/.config/last30days/.env and environment."""
+    # Load from config file first
+    file_env = load_env_file(CONFIG_FILE)
+
+    # Environment variables override file
+    config = {
+        'OPENAI_API_KEY': os.environ.get('OPENAI_API_KEY') or file_env.get('OPENAI_API_KEY'),
+        'XAI_API_KEY': os.environ.get('XAI_API_KEY') or file_env.get('XAI_API_KEY'),
+        'OPENAI_MODEL_POLICY': os.environ.get('OPENAI_MODEL_POLICY') or file_env.get('OPENAI_MODEL_POLICY', 'auto'),
+        'OPENAI_MODEL_PIN': os.environ.get('OPENAI_MODEL_PIN') or file_env.get('OPENAI_MODEL_PIN'),
+        'XAI_MODEL_POLICY': os.environ.get('XAI_MODEL_POLICY') or file_env.get('XAI_MODEL_POLICY', 'latest'),
+        'XAI_MODEL_PIN': os.environ.get('XAI_MODEL_PIN') or file_env.get('XAI_MODEL_PIN'),
+    }
+
+    return config
+
+
+def config_exists() -> bool:
+    """Check if configuration file exists."""
+    return CONFIG_FILE.exists()
+
+
+def get_available_sources(config: Dict[str, Any]) -> str:
+    """Determine which sources are available based on API keys.
+
+    Returns: 'both', 'reddit', 'x', or 'none'
+    """
+    has_openai = bool(config.get('OPENAI_API_KEY'))
+    has_xai = bool(config.get('XAI_API_KEY'))
+
+    if has_openai and has_xai:
+        return 'both'
+    elif has_openai:
+        return 'reddit'
+    elif has_xai:
+        return 'x'
+    else:
+        return 'none'
+
+
+def validate_sources(requested: str, available: str) -> tuple[str, Optional[str]]:
+    """Validate requested sources against available keys.
+
+    Args:
+        requested: 'auto', 'reddit', 'x', or 'both'
+        available: Result from get_available_sources()
+
+    Returns:
+        Tuple of (effective_sources, error_message)
+    """
+    if available == 'none':
+        return 'none', "No API keys configured. Please add at least one key to ~/.config/last30days/.env"
+
+    if requested == 'auto':
+        return available, None
+
+    if requested == 'both':
+        if available != 'both':
+            missing = 'xAI' if available == 'reddit' else 'OpenAI'
+            return 'none', f"Requested both sources but {missing} key is missing. Use --sources=auto to use available keys."
+
+    if requested == 'reddit' and available == 'x':
+        return 'none', "Requested Reddit but only xAI key is available."
+
+    if requested == 'x' and available == 'reddit':
+        return 'none', "Requested X but only OpenAI key is available."
+
+    return requested, None

scripts/lib/http.py

@@ -0,0 +1,126 @@
+"""HTTP utilities for last30days skill (stdlib only)."""
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+DEFAULT_TIMEOUT = 30
+MAX_RETRIES = 3
+RETRY_DELAY = 1.0
+USER_AGENT = "last30days-skill/1.0 (Claude Code Skill)"
+
+
+class HTTPError(Exception):
+    """HTTP request error with status code."""
+    def __init__(self, message: str, status_code: Optional[int] = None, body: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+def request(
+    method: str,
+    url: str,
+    headers: Optional[Dict[str, str]] = None,
+    json_data: Optional[Dict[str, Any]] = None,
+    timeout: int = DEFAULT_TIMEOUT,
+    retries: int = MAX_RETRIES,
+) -> Dict[str, Any]:
+    """Make an HTTP request and return JSON response.
+
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        url: Request URL
+        headers: Optional headers dict
+        json_data: Optional JSON body (for POST)
+        timeout: Request timeout in seconds
+        retries: Number of retries on failure
+
+    Returns:
+        Parsed JSON response
+
+    Raises:
+        HTTPError: On request failure
+    """
+    headers = headers or {}
+    headers.setdefault("User-Agent", USER_AGENT)
+
+    data = None
+    if json_data is not None:
+        data = json.dumps(json_data).encode('utf-8')
+        headers.setdefault("Content-Type", "application/json")
+
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+    last_error = None
+    for attempt in range(retries):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as response:
+                body = response.read().decode('utf-8')
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as e:
+            body = None
+            try:
+                body = e.read().decode('utf-8')
+            except:
+                pass
+            last_error = HTTPError(f"HTTP {e.code}: {e.reason}", e.code, body)
+
+            # Don't retry client errors (4xx) except rate limits
+            if 400 <= e.code < 500 and e.code != 429:
+                raise last_error
+
+            if attempt < retries - 1:
+                time.sleep(RETRY_DELAY * (attempt + 1))
+        except urllib.error.URLError as e:
+            last_error = HTTPError(f"URL Error: {e.reason}")
+            if attempt < retries - 1:
+                time.sleep(RETRY_DELAY * (attempt + 1))
+        except json.JSONDecodeError as e:
+            last_error = HTTPError(f"Invalid JSON response: {e}")
+            raise last_error
+
+    if last_error:
+        raise last_error
+    raise HTTPError("Request failed with no error details")
+
+
+def get(url: str, headers: Optional[Dict[str, str]] = None, **kwargs) -> Dict[str, Any]:
+    """Make a GET request."""
+    return request("GET", url, headers=headers, **kwargs)
+
+
+def post(url: str, json_data: Dict[str, Any], headers: Optional[Dict[str, str]] = None, **kwargs) -> Dict[str, Any]:
+    """Make a POST request with JSON body."""
+    return request("POST", url, headers=headers, json_data=json_data, **kwargs)
+
+
+def get_reddit_json(path: str) -> Dict[str, Any]:
+    """Fetch Reddit thread JSON.
+
+    Args:
+        path: Reddit path (e.g., /r/subreddit/comments/id/title)
+
+    Returns:
+        Parsed JSON response
+    """
+    # Ensure path starts with /
+    if not path.startswith('/'):
+        path = '/' + path
+
+    # Remove trailing slash and add .json
+    path = path.rstrip('/')
+    if not path.endswith('.json'):
+        path = path + '.json'
+
+    url = f"https://www.reddit.com{path}?raw_json=1"
+
+    headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+    }
+
+    return get(url, headers=headers)

scripts/lib/models.py

@@ -0,0 +1,175 @@
+"""Model auto-selection for last30days skill."""
+
+import re
+from typing import Dict, List, Optional, Tuple
+
+from . import cache, http
+
+# OpenAI API
+OPENAI_MODELS_URL = "https://api.openai.com/v1/models"
+OPENAI_FALLBACK_MODELS = ["gpt-5.2", "gpt-5.1", "gpt-5", "gpt-4o"]
+
+# xAI API
+XAI_MODELS_URL = "https://api.x.ai/v1/models"
+XAI_ALIASES = {
+    "latest": "grok-3",
+    "stable": "grok-3",
+}
+
+
+def parse_version(model_id: str) -> Optional[Tuple[int, ...]]:
+    """Parse semantic version from model ID.
+
+    Examples:
+        gpt-5 -> (5,)
+        gpt-5.2 -> (5, 2)
+        gpt-5.2.1 -> (5, 2, 1)
+    """
+    match = re.search(r'(\d+(?:\.\d+)*)', model_id)
+    if match:
+        return tuple(int(x) for x in match.group(1).split('.'))
+    return None
+
+
+def is_mainline_openai_model(model_id: str) -> bool:
+    """Check if model is a mainline GPT model (not mini/nano/chat/codex/pro)."""
+    model_lower = model_id.lower()
+
+    # Must be gpt-5 series
+    if not re.match(r'^gpt-5(\.\d+)*$', model_lower):
+        return False
+
+    # Exclude variants
+    excludes = ['mini', 'nano', 'chat', 'codex', 'pro', 'preview', 'turbo']
+    for exc in excludes:
+        if exc in model_lower:
+            return False
+
+    return True
+
+
+def select_openai_model(
+    api_key: str,
+    policy: str = "auto",
+    pin: Optional[str] = None,
+    mock_models: Optional[List[Dict]] = None,
+) -> str:
+    """Select the best OpenAI model based on policy.
+
+    Args:
+        api_key: OpenAI API key
+        policy: 'auto' or 'pinned'
+        pin: Model to use if policy is 'pinned'
+        mock_models: Mock model list for testing
+
+    Returns:
+        Selected model ID
+    """
+    if policy == "pinned" and pin:
+        return pin
+
+    # Check cache first
+    cached = cache.get_cached_model("openai")
+    if cached:
+        return cached
+
+    # Fetch model list
+    if mock_models is not None:
+        models = mock_models
+    else:
+        try:
+            headers = {"Authorization": f"Bearer {api_key}"}
+            response = http.get(OPENAI_MODELS_URL, headers=headers)
+            models = response.get("data", [])
+        except http.HTTPError:
+            # Fall back to known models
+            return OPENAI_FALLBACK_MODELS[0]
+
+    # Filter to mainline models
+    candidates = [m for m in models if is_mainline_openai_model(m.get("id", ""))]
+
+    if not candidates:
+        # No gpt-5 models found, use fallback
+        return OPENAI_FALLBACK_MODELS[0]
+
+    # Sort by version (descending), then by created timestamp
+    def sort_key(m):
+        version = parse_version(m.get("id", "")) or (0,)
+        created = m.get("created", 0)
+        return (version, created)
+
+    candidates.sort(key=sort_key, reverse=True)
+    selected = candidates[0]["id"]
+
+    # Cache the selection
+    cache.set_cached_model("openai", selected)
+
+    return selected
+
+
+def select_xai_model(
+    api_key: str,
+    policy: str = "latest",
+    pin: Optional[str] = None,
+    mock_models: Optional[List[Dict]] = None,
+) -> str:
+    """Select the best xAI model based on policy.
+
+    Args:
+        api_key: xAI API key
+        policy: 'latest', 'stable', or 'pinned'
+        pin: Model to use if policy is 'pinned'
+        mock_models: Mock model list for testing
+
+    Returns:
+        Selected model ID
+    """
+    if policy == "pinned" and pin:
+        return pin
+
+    # Use alias system
+    if policy in XAI_ALIASES:
+        alias = XAI_ALIASES[policy]
+
+        # Check cache first
+        cached = cache.get_cached_model("xai")
+        if cached:
+            return cached
+
+        # Cache the alias
+        cache.set_cached_model("xai", alias)
+        return alias
+
+    # Default to latest
+    return XAI_ALIASES["latest"]
+
+
+def get_models(
+    config: Dict,
+    mock_openai_models: Optional[List[Dict]] = None,
+    mock_xai_models: Optional[List[Dict]] = None,
+) -> Dict[str, Optional[str]]:
+    """Get selected models for both providers.
+
+    Returns:
+        Dict with 'openai' and 'xai' keys
+    """
+    result = {"openai": None, "xai": None}
+
+    if config.get("OPENAI_API_KEY"):
+        result["openai"] = select_openai_model(
+            config["OPENAI_API_KEY"],
+            config.get("OPENAI_MODEL_POLICY", "auto"),
+            config.get("OPENAI_MODEL_PIN"),
+            mock_openai_models,
+        )
+
+    if config.get("XAI_API_KEY"):
+        result["xai"] = select_xai_model(
+            config["XAI_API_KEY"],
+            config.get("XAI_MODEL_POLICY", "latest"),
+            config.get("XAI_MODEL_PIN"),
+            mock_xai_models,
+        )
+
+    return result

scripts/lib/normalize.py

@@ -0,0 +1,118 @@
+"""Normalization of raw API data to canonical schema."""
+
+from typing import Any, Dict, List
+
+from . import dates, schema
+
+
+def normalize_reddit_items(
+    items: List[Dict[str, Any]],
+    from_date: str,
+    to_date: str,
+) -> List[schema.RedditItem]:
+    """Normalize raw Reddit items to schema.
+
+    Args:
+        items: Raw Reddit items from API
+        from_date: Start of date range
+        to_date: End of date range
+
+    Returns:
+        List of RedditItem objects
+    """
+    normalized = []
+
+    for item in items:
+        # Parse engagement
+        engagement = None
+        eng_raw = item.get("engagement")
+        if isinstance(eng_raw, dict):
+            engagement = schema.Engagement(
+                score=eng_raw.get("score"),
+                num_comments=eng_raw.get("num_comments"),
+                upvote_ratio=eng_raw.get("upvote_ratio"),
+            )
+
+        # Parse comments
+        top_comments = []
+        for c in item.get("top_comments", []):
+            top_comments.append(schema.Comment(
+                score=c.get("score", 0),
+                date=c.get("date"),
+                author=c.get("author", ""),
+                excerpt=c.get("excerpt", ""),
+                url=c.get("url", ""),
+            ))
+
+        # Determine date confidence
+        date_str = item.get("date")
+        date_confidence = dates.get_date_confidence(date_str, from_date, to_date)
+
+        normalized.append(schema.RedditItem(
+            id=item.get("id", ""),
+            title=item.get("title", ""),
+            url=item.get("url", ""),
+            subreddit=item.get("subreddit", ""),
+            date=date_str,
+            date_confidence=date_confidence,
+            engagement=engagement,
+            top_comments=top_comments,
+            comment_insights=item.get("comment_insights", []),
+            relevance=item.get("relevance", 0.5),
+            why_relevant=item.get("why_relevant", ""),
+        ))
+
+    return normalized
+
+
+def normalize_x_items(
+    items: List[Dict[str, Any]],
+    from_date: str,
+    to_date: str,
+) -> List[schema.XItem]:
+    """Normalize raw X items to schema.
+
+    Args:
+        items: Raw X items from API
+        from_date: Start of date range
+        to_date: End of date range
+
+    Returns:
+        List of XItem objects
+    """
+    normalized = []
+
+    for item in items:
+        # Parse engagement
+        engagement = None
+        eng_raw = item.get("engagement")
+        if isinstance(eng_raw, dict):
+            engagement = schema.Engagement(
+                likes=eng_raw.get("likes"),
+                reposts=eng_raw.get("reposts"),
+                replies=eng_raw.get("replies"),
+                quotes=eng_raw.get("quotes"),
+            )
+
+        # Determine date confidence
+        date_str = item.get("date")
+        date_confidence = dates.get_date_confidence(date_str, from_date, to_date)
+
+        normalized.append(schema.XItem(
+            id=item.get("id", ""),
+            text=item.get("text", ""),
+            url=item.get("url", ""),
+            author_handle=item.get("author_handle", ""),
+            date=date_str,
+            date_confidence=date_confidence,
+            engagement=engagement,
+            relevance=item.get("relevance", 0.5),
+            why_relevant=item.get("why_relevant", ""),
+        ))
+
+    return normalized
+
+
+def items_to_dicts(items: List) -> List[Dict[str, Any]]:
+    """Convert schema items to dicts for JSON serialization."""
+    return [item.to_dict() for item in items]

scripts/lib/openai_reddit.py

@@ -0,0 +1,158 @@
+"""OpenAI Responses API client for Reddit discovery."""
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from . import http
+
+OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses"
+
+REDDIT_SEARCH_PROMPT = """Search Reddit for discussions about: {topic}
+
+Focus on threads from the last 30 days. Find 15-30 high-quality, relevant threads.
+
+IMPORTANT: Return ONLY valid JSON in this exact format, no other text:
+{{
+  "items": [
+    {{
+      "title": "Thread title",
+      "url": "https://reddit.com/r/...",
+      "subreddit": "subreddit_name",
+      "date": "YYYY-MM-DD or null if unknown",
+      "why_relevant": "Brief explanation of relevance",
+      "relevance": 0.85
+    }}
+  ]
+}}
+
+Rules:
+- relevance is 0.0 to 1.0 (1.0 = highly relevant)
+- date must be YYYY-MM-DD format or null
+- Include diverse subreddits if applicable
+- Prefer threads with substantive discussions
+- Do NOT include engagement metrics (upvotes, comments) - those will be fetched separately"""
+
+
+def search_reddit(
+    api_key: str,
+    model: str,
+    topic: str,
+    mock_response: Optional[Dict] = None,
+) -> Dict[str, Any]:
+    """Search Reddit for relevant threads using OpenAI Responses API.
+
+    Args:
+        api_key: OpenAI API key
+        model: Model to use
+        topic: Search topic
+        mock_response: Mock response for testing
+
+    Returns:
+        Raw API response
+    """
+    if mock_response is not None:
+        return mock_response
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+
+    payload = {
+        "model": model,
+        "tools": [
+            {
+                "type": "web_search",
+                "filters": {
+                    "allowed_domains": ["reddit.com"]
+                }
+            }
+        ],
+        "include": ["web_search_call.action.sources"],
+        "input": REDDIT_SEARCH_PROMPT.format(topic=topic),
+    }
+
+    return http.post(OPENAI_RESPONSES_URL, payload, headers=headers, timeout=60)
+
+
+def parse_reddit_response(response: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Parse OpenAI response to extract Reddit items.
+
+    Args:
+        response: Raw API response
+
+    Returns:
+        List of item dicts
+    """
+    items = []
+
+    # Try to find the output text
+    output_text = ""
+    if "output" in response:
+        output = response["output"]
+        if isinstance(output, str):
+            output_text = output
+        elif isinstance(output, list):
+            for item in output:
+                if isinstance(item, dict):
+                    if item.get("type") == "message":
+                        content = item.get("content", [])
+                        for c in content:
+                            if isinstance(c, dict) and c.get("type") == "output_text":
+                                output_text = c.get("text", "")
+                                break
+                    elif "text" in item:
+                        output_text = item["text"]
+                elif isinstance(item, str):
+                    output_text = item
+                if output_text:
+                    break
+
+    # Also check for choices (older format)
+    if not output_text and "choices" in response:
+        for choice in response["choices"]:
+            if "message" in choice:
+                output_text = choice["message"].get("content", "")
+                break
+
+    if not output_text:
+        return items
+
+    # Extract JSON from the response
+    json_match = re.search(r'\{[\s\S]*"items"[\s\S]*\}', output_text)
+    if json_match:
+        try:
+            data = json.loads(json_match.group())
+            items = data.get("items", [])
+        except json.JSONDecodeError:
+            pass
+
+    # Validate and clean items
+    clean_items = []
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            continue
+
+        url = item.get("url", "")
+        if not url or "reddit.com" not in url:
+            continue
+
+        clean_item = {
+            "id": f"R{i+1}",
+            "title": str(item.get("title", "")).strip(),
+            "url": url,
+            "subreddit": str(item.get("subreddit", "")).strip().lstrip("r/"),
+            "date": item.get("date"),
+            "why_relevant": str(item.get("why_relevant", "")).strip(),
+            "relevance": min(1.0, max(0.0, float(item.get("relevance", 0.5)))),
+        }
+
+        # Validate date format
+        if clean_item["date"]:
+            if not re.match(r'^\d{4}-\d{2}-\d{2}$', str(clean_item["date"])):
+                clean_item["date"] = None
+
+        clean_items.append(clean_item)
+
+    return clean_items

scripts/lib/reddit_enrich.py

@@ -0,0 +1,232 @@
+"""Reddit thread enrichment with real engagement metrics."""
+
+import re
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+
+from . import http, dates
+
+
+def extract_reddit_path(url: str) -> Optional[str]:
+    """Extract the path from a Reddit URL.
+
+    Args:
+        url: Reddit URL
+
+    Returns:
+        Path component or None
+    """
+    try:
+        parsed = urlparse(url)
+        if "reddit.com" not in parsed.netloc:
+            return None
+        return parsed.path
+    except:
+        return None
+
+
+def fetch_thread_data(url: str, mock_data: Optional[Dict] = None) -> Optional[Dict[str, Any]]:
+    """Fetch Reddit thread JSON data.
+
+    Args:
+        url: Reddit thread URL
+        mock_data: Mock data for testing
+
+    Returns:
+        Thread data dict or None on failure
+    """
+    if mock_data is not None:
+        return mock_data
+
+    path = extract_reddit_path(url)
+    if not path:
+        return None
+
+    try:
+        data = http.get_reddit_json(path)
+        return data
+    except http.HTTPError:
+        return None
+
+
+def parse_thread_data(data: Any) -> Dict[str, Any]:
+    """Parse Reddit thread JSON into structured data.
+
+    Args:
+        data: Raw Reddit JSON response
+
+    Returns:
+        Dict with submission and comments data
+    """
+    result = {
+        "submission": None,
+        "comments": [],
+    }
+
+    if not isinstance(data, list) or len(data) < 1:
+        return result
+
+    # First element is submission listing
+    submission_listing = data[0]
+    if isinstance(submission_listing, dict):
+        children = submission_listing.get("data", {}).get("children", [])
+        if children:
+            sub_data = children[0].get("data", {})
+            result["submission"] = {
+                "score": sub_data.get("score"),
+                "num_comments": sub_data.get("num_comments"),
+                "upvote_ratio": sub_data.get("upvote_ratio"),
+                "created_utc": sub_data.get("created_utc"),
+                "permalink": sub_data.get("permalink"),
+                "title": sub_data.get("title"),
+                "selftext": sub_data.get("selftext", "")[:500],  # Truncate
+            }
+
+    # Second element is comments listing
+    if len(data) >= 2:
+        comments_listing = data[1]
+        if isinstance(comments_listing, dict):
+            children = comments_listing.get("data", {}).get("children", [])
+            for child in children:
+                if child.get("kind") != "t1":  # t1 = comment
+                    continue
+                c_data = child.get("data", {})
+                if not c_data.get("body"):
+                    continue
+
+                comment = {
+                    "score": c_data.get("score", 0),
+                    "created_utc": c_data.get("created_utc"),
+                    "author": c_data.get("author", "[deleted]"),
+                    "body": c_data.get("body", "")[:300],  # Truncate
+                    "permalink": c_data.get("permalink"),
+                }
+                result["comments"].append(comment)
+
+    return result
+
+
+def get_top_comments(comments: List[Dict], limit: int = 10) -> List[Dict[str, Any]]:
+    """Get top comments sorted by score.
+
+    Args:
+        comments: List of comment dicts
+        limit: Maximum number to return
+
+    Returns:
+        Top comments sorted by score
+    """
+    # Filter out deleted/removed
+    valid = [c for c in comments if c.get("author") not in ("[deleted]", "[removed]")]
+
+    # Sort by score descending
+    sorted_comments = sorted(valid, key=lambda c: c.get("score", 0), reverse=True)
+
+    return sorted_comments[:limit]
+
+
+def extract_comment_insights(comments: List[Dict], limit: int = 7) -> List[str]:
+    """Extract key insights from top comments.
+
+    Uses simple heuristics to identify valuable comments:
+    - Has substantive text
+    - Contains actionable information
+    - Not just agreement/disagreement
+
+    Args:
+        comments: Top comments
+        limit: Max insights to extract
+
+    Returns:
+        List of insight strings
+    """
+    insights = []
+
+    for comment in comments[:limit * 2]:  # Look at more comments than we need
+        body = comment.get("body", "").strip()
+        if not body or len(body) < 30:
+            continue
+
+        # Skip low-value patterns
+        skip_patterns = [
+            r'^(this|same|agreed|exactly|yep|nope|yes|no|thanks|thank you)\.?$',
+            r'^lol|lmao|haha',
+            r'^\[deleted\]',
+            r'^\[removed\]',
+        ]
+        if any(re.match(p, body.lower()) for p in skip_patterns):
+            continue
+
+        # Truncate to first meaningful sentence or ~150 chars
+        insight = body[:150]
+        if len(body) > 150:
+            # Try to find a sentence boundary
+            for i, char in enumerate(insight):
+                if char in '.!?' and i > 50:
+                    insight = insight[:i+1]
+                    break
+            else:
+                insight = insight.rstrip() + "..."
+
+        insights.append(insight)
+        if len(insights) >= limit:
+            break
+
+    return insights
+
+
+def enrich_reddit_item(
+    item: Dict[str, Any],
+    mock_thread_data: Optional[Dict] = None,
+) -> Dict[str, Any]:
+    """Enrich a Reddit item with real engagement data.
+
+    Args:
+        item: Reddit item dict
+        mock_thread_data: Mock data for testing
+
+    Returns:
+        Enriched item dict
+    """
+    url = item.get("url", "")
+
+    # Fetch thread data
+    thread_data = fetch_thread_data(url, mock_thread_data)
+    if not thread_data:
+        return item
+
+    parsed = parse_thread_data(thread_data)
+    submission = parsed.get("submission")
+    comments = parsed.get("comments", [])
+
+    # Update engagement metrics
+    if submission:
+        item["engagement"] = {
+            "score": submission.get("score"),
+            "num_comments": submission.get("num_comments"),
+            "upvote_ratio": submission.get("upvote_ratio"),
+        }
+
+        # Update date from actual data
+        created_utc = submission.get("created_utc")
+        if created_utc:
+            item["date"] = dates.timestamp_to_date(created_utc)
+
+    # Get top comments
+    top_comments = get_top_comments(comments)
+    item["top_comments"] = []
+    for c in top_comments:
+        permalink = c.get("permalink", "")
+        comment_url = f"https://reddit.com{permalink}" if permalink else ""
+        item["top_comments"].append({
+            "score": c.get("score", 0),
+            "date": dates.timestamp_to_date(c.get("created_utc")),
+            "author": c.get("author", ""),
+            "excerpt": c.get("body", "")[:200],
+            "url": comment_url,
+        })
+
+    # Extract insights
+    item["comment_insights"] = extract_comment_insights(top_comments)
+
+    return item

scripts/lib/render.py

@@ -0,0 +1,277 @@
+"""Output rendering for last30days skill."""
+
+import json
+from pathlib import Path
+from typing import List, Optional
+
+from . import schema
+
+OUTPUT_DIR = Path.home() / ".local" / "share" / "last30days" / "out"
+
+
+def ensure_output_dir():
+    """Ensure output directory exists."""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def render_compact(report: schema.Report, limit: int = 15) -> str:
+    """Render compact output for Claude to synthesize.
+
+    Args:
+        report: Report data
+        limit: Max items per source
+
+    Returns:
+        Compact markdown string
+    """
+    lines = []
+
+    # Header
+    lines.append(f"## Research Results: {report.topic}")
+    lines.append("")
+    lines.append(f"**Date Range:** {report.range_from} to {report.range_to}")
+    lines.append(f"**Mode:** {report.mode}")
+    if report.openai_model_used:
+        lines.append(f"**OpenAI Model:** {report.openai_model_used}")
+    if report.xai_model_used:
+        lines.append(f"**xAI Model:** {report.xai_model_used}")
+    lines.append("")
+
+    # Coverage note
+    if report.mode == "reddit-only":
+        lines.append("*Tip: Add xAI key for X coverage and better triangulation.*")
+        lines.append("")
+    elif report.mode == "x-only":
+        lines.append("*Tip: Add OpenAI key for Reddit coverage and better triangulation.*")
+        lines.append("")
+
+    # Reddit items
+    if report.reddit:
+        lines.append("### Reddit Threads")
+        lines.append("")
+        for item in report.reddit[:limit]:
+            eng_str = ""
+            if item.engagement:
+                eng = item.engagement
+                parts = []
+                if eng.score is not None:
+                    parts.append(f"{eng.score}pts")
+                if eng.num_comments is not None:
+                    parts.append(f"{eng.num_comments}cmt")
+                if parts:
+                    eng_str = f" [{', '.join(parts)}]"
+
+            date_str = f" ({item.date})" if item.date else " (date unknown)"
+            conf_str = f" [date:{item.date_confidence}]" if item.date_confidence != "high" else ""
+
+            lines.append(f"**{item.id}** (score:{item.score}) r/{item.subreddit}{date_str}{conf_str}{eng_str}")
+            lines.append(f"  {item.title}")
+            lines.append(f"  {item.url}")
+            lines.append(f"  *{item.why_relevant}*")
+
+            # Top comment insights
+            if item.comment_insights:
+                lines.append(f"  Insights:")
+                for insight in item.comment_insights[:3]:
+                    lines.append(f"    - {insight}")
+
+            lines.append("")
+
+    # X items
+    if report.x:
+        lines.append("### X Posts")
+        lines.append("")
+        for item in report.x[:limit]:
+            eng_str = ""
+            if item.engagement:
+                eng = item.engagement
+                parts = []
+                if eng.likes is not None:
+                    parts.append(f"{eng.likes}likes")
+                if eng.reposts is not None:
+                    parts.append(f"{eng.reposts}rt")
+                if parts:
+                    eng_str = f" [{', '.join(parts)}]"
+
+            date_str = f" ({item.date})" if item.date else " (date unknown)"
+            conf_str = f" [date:{item.date_confidence}]" if item.date_confidence != "high" else ""
+
+            lines.append(f"**{item.id}** (score:{item.score}) @{item.author_handle}{date_str}{conf_str}{eng_str}")
+            lines.append(f"  {item.text[:200]}...")
+            lines.append(f"  {item.url}")
+            lines.append(f"  *{item.why_relevant}*")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_context_snippet(report: schema.Report) -> str:
+    """Render reusable context snippet.
+
+    Args:
+        report: Report data
+
+    Returns:
+        Context markdown string
+    """
+    lines = []
+    lines.append(f"# Context: {report.topic} (Last 30 Days)")
+    lines.append("")
+    lines.append(f"*Generated: {report.generated_at[:10]} | Sources: {report.mode}*")
+    lines.append("")
+
+    # Key sources summary
+    lines.append("## Key Sources")
+    lines.append("")
+
+    all_items = []
+    for item in report.reddit[:5]:
+        all_items.append((item.score, "Reddit", item.title, item.url))
+    for item in report.x[:5]:
+        all_items.append((item.score, "X", item.text[:50] + "...", item.url))
+
+    all_items.sort(key=lambda x: -x[0])
+    for score, source, text, url in all_items[:7]:
+        lines.append(f"- [{source}] {text}")
+
+    lines.append("")
+    lines.append("## Summary")
+    lines.append("")
+    lines.append("*See full report for best practices, prompt pack, and detailed sources.*")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_full_report(report: schema.Report) -> str:
+    """Render full markdown report.
+
+    Args:
+        report: Report data
+
+    Returns:
+        Full report markdown
+    """
+    lines = []
+
+    # Title
+    lines.append(f"# {report.topic} - Last 30 Days Research Report")
+    lines.append("")
+    lines.append(f"**Generated:** {report.generated_at}")
+    lines.append(f"**Date Range:** {report.range_from} to {report.range_to}")
+    lines.append(f"**Mode:** {report.mode}")
+    lines.append("")
+
+    # Models
+    lines.append("## Models Used")
+    lines.append("")
+    if report.openai_model_used:
+        lines.append(f"- **OpenAI:** {report.openai_model_used}")
+    if report.xai_model_used:
+        lines.append(f"- **xAI:** {report.xai_model_used}")
+    lines.append("")
+
+    # Reddit section
+    if report.reddit:
+        lines.append("## Reddit Threads")
+        lines.append("")
+        for item in report.reddit:
+            lines.append(f"### {item.id}: {item.title}")
+            lines.append("")
+            lines.append(f"- **Subreddit:** r/{item.subreddit}")
+            lines.append(f"- **URL:** {item.url}")
+            lines.append(f"- **Date:** {item.date or 'Unknown'} (confidence: {item.date_confidence})")
+            lines.append(f"- **Score:** {item.score}/100")
+            lines.append(f"- **Relevance:** {item.why_relevant}")
+
+            if item.engagement:
+                eng = item.engagement
+                lines.append(f"- **Engagement:** {eng.score or '?'} points, {eng.num_comments or '?'} comments")
+
+            if item.comment_insights:
+                lines.append("")
+                lines.append("**Key Insights from Comments:**")
+                for insight in item.comment_insights:
+                    lines.append(f"- {insight}")
+
+            lines.append("")
+
+    # X section
+    if report.x:
+        lines.append("## X Posts")
+        lines.append("")
+        for item in report.x:
+            lines.append(f"### {item.id}: @{item.author_handle}")
+            lines.append("")
+            lines.append(f"- **URL:** {item.url}")
+            lines.append(f"- **Date:** {item.date or 'Unknown'} (confidence: {item.date_confidence})")
+            lines.append(f"- **Score:** {item.score}/100")
+            lines.append(f"- **Relevance:** {item.why_relevant}")
+
+            if item.engagement:
+                eng = item.engagement
+                lines.append(f"- **Engagement:** {eng.likes or '?'} likes, {eng.reposts or '?'} reposts")
+
+            lines.append("")
+            lines.append(f"> {item.text}")
+            lines.append("")
+
+    # Placeholders for Claude synthesis
+    lines.append("## Best Practices")
+    lines.append("")
+    lines.append("*To be synthesized by Claude*")
+    lines.append("")
+
+    lines.append("## Prompt Pack")
+    lines.append("")
+    lines.append("*To be synthesized by Claude*")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def write_outputs(
+    report: schema.Report,
+    raw_openai: Optional[dict] = None,
+    raw_xai: Optional[dict] = None,
+    raw_reddit_enriched: Optional[list] = None,
+):
+    """Write all output files.
+
+    Args:
+        report: Report data
+        raw_openai: Raw OpenAI API response
+        raw_xai: Raw xAI API response
+        raw_reddit_enriched: Raw enriched Reddit thread data
+    """
+    ensure_output_dir()
+
+    # report.json
+    with open(OUTPUT_DIR / "report.json", 'w') as f:
+        json.dump(report.to_dict(), f, indent=2)
+
+    # report.md
+    with open(OUTPUT_DIR / "report.md", 'w') as f:
+        f.write(render_full_report(report))
+
+    # last30days.context.md
+    with open(OUTPUT_DIR / "last30days.context.md", 'w') as f:
+        f.write(render_context_snippet(report))
+
+    # Raw responses
+    if raw_openai:
+        with open(OUTPUT_DIR / "raw_openai.json", 'w') as f:
+            json.dump(raw_openai, f, indent=2)
+
+    if raw_xai:
+        with open(OUTPUT_DIR / "raw_xai.json", 'w') as f:
+            json.dump(raw_xai, f, indent=2)
+
+    if raw_reddit_enriched:
+        with open(OUTPUT_DIR / "raw_reddit_threads_enriched.json", 'w') as f:
+            json.dump(raw_reddit_enriched, f, indent=2)
+
+
+def get_context_path() -> str:
+    """Get path to context file."""
+    return str(OUTPUT_DIR / "last30days.context.md")

scripts/lib/schema.py

@@ -0,0 +1,193 @@
+"""Data schemas for last30days skill."""
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+from datetime import datetime, timezone
+
+
+@dataclass
+class Engagement:
+    """Engagement metrics."""
+    # Reddit fields
+    score: Optional[int] = None
+    num_comments: Optional[int] = None
+    upvote_ratio: Optional[float] = None
+
+    # X fields
+    likes: Optional[int] = None
+    reposts: Optional[int] = None
+    replies: Optional[int] = None
+    quotes: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {}
+        if self.score is not None:
+            d['score'] = self.score
+        if self.num_comments is not None:
+            d['num_comments'] = self.num_comments
+        if self.upvote_ratio is not None:
+            d['upvote_ratio'] = self.upvote_ratio
+        if self.likes is not None:
+            d['likes'] = self.likes
+        if self.reposts is not None:
+            d['reposts'] = self.reposts
+        if self.replies is not None:
+            d['replies'] = self.replies
+        if self.quotes is not None:
+            d['quotes'] = self.quotes
+        return d if d else None
+
+
+@dataclass
+class Comment:
+    """Reddit comment."""
+    score: int
+    date: Optional[str]
+    author: str
+    excerpt: str
+    url: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'score': self.score,
+            'date': self.date,
+            'author': self.author,
+            'excerpt': self.excerpt,
+            'url': self.url,
+        }
+
+
+@dataclass
+class SubScores:
+    """Component scores."""
+    relevance: int = 0
+    recency: int = 0
+    engagement: int = 0
+
+    def to_dict(self) -> Dict[str, int]:
+        return {
+            'relevance': self.relevance,
+            'recency': self.recency,
+            'engagement': self.engagement,
+        }
+
+
+@dataclass
+class RedditItem:
+    """Normalized Reddit item."""
+    id: str
+    title: str
+    url: str
+    subreddit: str
+    date: Optional[str] = None
+    date_confidence: str = "low"
+    engagement: Optional[Engagement] = None
+    top_comments: List[Comment] = field(default_factory=list)
+    comment_insights: List[str] = field(default_factory=list)
+    relevance: float = 0.5
+    why_relevant: str = ""
+    subs: SubScores = field(default_factory=SubScores)
+    score: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'id': self.id,
+            'title': self.title,
+            'url': self.url,
+            'subreddit': self.subreddit,
+            'date': self.date,
+            'date_confidence': self.date_confidence,
+            'engagement': self.engagement.to_dict() if self.engagement else None,
+            'top_comments': [c.to_dict() for c in self.top_comments],
+            'comment_insights': self.comment_insights,
+            'relevance': self.relevance,
+            'why_relevant': self.why_relevant,
+            'subs': self.subs.to_dict(),
+            'score': self.score,
+        }
+
+
+@dataclass
+class XItem:
+    """Normalized X item."""
+    id: str
+    text: str
+    url: str
+    author_handle: str
+    date: Optional[str] = None
+    date_confidence: str = "low"
+    engagement: Optional[Engagement] = None
+    relevance: float = 0.5
+    why_relevant: str = ""
+    subs: SubScores = field(default_factory=SubScores)
+    score: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'id': self.id,
+            'text': self.text,
+            'url': self.url,
+            'author_handle': self.author_handle,
+            'date': self.date,
+            'date_confidence': self.date_confidence,
+            'engagement': self.engagement.to_dict() if self.engagement else None,
+            'relevance': self.relevance,
+            'why_relevant': self.why_relevant,
+            'subs': self.subs.to_dict(),
+            'score': self.score,
+        }
+
+
+@dataclass
+class Report:
+    """Full research report."""
+    topic: str
+    range_from: str
+    range_to: str
+    generated_at: str
+    mode: str  # 'reddit-only', 'x-only', 'both'
+    openai_model_used: Optional[str] = None
+    xai_model_used: Optional[str] = None
+    reddit: List[RedditItem] = field(default_factory=list)
+    x: List[XItem] = field(default_factory=list)
+    best_practices: List[str] = field(default_factory=list)
+    prompt_pack: List[str] = field(default_factory=list)
+    context_snippet_md: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'topic': self.topic,
+            'range': {
+                'from': self.range_from,
+                'to': self.range_to,
+            },
+            'generated_at': self.generated_at,
+            'mode': self.mode,
+            'openai_model_used': self.openai_model_used,
+            'xai_model_used': self.xai_model_used,
+            'reddit': [r.to_dict() for r in self.reddit],
+            'x': [x.to_dict() for x in self.x],
+            'best_practices': self.best_practices,
+            'prompt_pack': self.prompt_pack,
+            'context_snippet_md': self.context_snippet_md,
+        }
+
+
+def create_report(
+    topic: str,
+    from_date: str,
+    to_date: str,
+    mode: str,
+    openai_model: Optional[str] = None,
+    xai_model: Optional[str] = None,
+) -> Report:
+    """Create a new report with metadata."""
+    return Report(
+        topic=topic,
+        range_from=from_date,
+        range_to=to_date,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        mode=mode,
+        openai_model_used=openai_model,
+        xai_model_used=xai_model,
+    )

scripts/lib/score.py

@@ -0,0 +1,240 @@
+"""Popularity-aware scoring for last30days skill."""
+
+import math
+from typing import List, Optional, Union
+
+from . import dates, schema
+
+# Score weights
+WEIGHT_RELEVANCE = 0.45
+WEIGHT_RECENCY = 0.25
+WEIGHT_ENGAGEMENT = 0.30
+
+# Default engagement score for unknown
+DEFAULT_ENGAGEMENT = 35
+UNKNOWN_ENGAGEMENT_PENALTY = 10
+
+
+def log1p_safe(x: Optional[int]) -> float:
+    """Safe log1p that handles None and negative values."""
+    if x is None or x < 0:
+        return 0.0
+    return math.log1p(x)
+
+
+def compute_reddit_engagement_raw(engagement: Optional[schema.Engagement]) -> Optional[float]:
+    """Compute raw engagement score for Reddit item.
+
+    Formula: 0.55*log1p(score) + 0.40*log1p(num_comments) + 0.05*(upvote_ratio*10)
+    """
+    if engagement is None:
+        return None
+
+    if engagement.score is None and engagement.num_comments is None:
+        return None
+
+    score = log1p_safe(engagement.score)
+    comments = log1p_safe(engagement.num_comments)
+    ratio = (engagement.upvote_ratio or 0.5) * 10
+
+    return 0.55 * score + 0.40 * comments + 0.05 * ratio
+
+
+def compute_x_engagement_raw(engagement: Optional[schema.Engagement]) -> Optional[float]:
+    """Compute raw engagement score for X item.
+
+    Formula: 0.55*log1p(likes) + 0.25*log1p(reposts) + 0.15*log1p(replies) + 0.05*log1p(quotes)
+    """
+    if engagement is None:
+        return None
+
+    if engagement.likes is None and engagement.reposts is None:
+        return None
+
+    likes = log1p_safe(engagement.likes)
+    reposts = log1p_safe(engagement.reposts)
+    replies = log1p_safe(engagement.replies)
+    quotes = log1p_safe(engagement.quotes)
+
+    return 0.55 * likes + 0.25 * reposts + 0.15 * replies + 0.05 * quotes
+
+
+def normalize_to_100(values: List[float], default: float = 50) -> List[float]:
+    """Normalize a list of values to 0-100 scale.
+
+    Args:
+        values: Raw values (None values are preserved)
+        default: Default value for None entries
+
+    Returns:
+        Normalized values
+    """
+    # Filter out None
+    valid = [v for v in values if v is not None]
+    if not valid:
+        return [default if v is None else 50 for v in values]
+
+    min_val = min(valid)
+    max_val = max(valid)
+    range_val = max_val - min_val
+
+    if range_val == 0:
+        return [50 if v is None else 50 for v in values]
+
+    result = []
+    for v in values:
+        if v is None:
+            result.append(None)
+        else:
+            normalized = ((v - min_val) / range_val) * 100
+            result.append(normalized)
+
+    return result
+
+
+def score_reddit_items(items: List[schema.RedditItem]) -> List[schema.RedditItem]:
+    """Compute scores for Reddit items.
+
+    Args:
+        items: List of Reddit items
+
+    Returns:
+        Items with updated scores
+    """
+    if not items:
+        return items
+
+    # Compute raw engagement scores
+    eng_raw = [compute_reddit_engagement_raw(item.engagement) for item in items]
+
+    # Normalize engagement to 0-100
+    eng_normalized = normalize_to_100(eng_raw)
+
+    for i, item in enumerate(items):
+        # Relevance subscore (model-provided, convert to 0-100)
+        rel_score = int(item.relevance * 100)
+
+        # Recency subscore
+        rec_score = dates.recency_score(item.date)
+
+        # Engagement subscore
+        if eng_normalized[i] is not None:
+            eng_score = int(eng_normalized[i])
+        else:
+            eng_score = DEFAULT_ENGAGEMENT
+
+        # Store subscores
+        item.subs = schema.SubScores(
+            relevance=rel_score,
+            recency=rec_score,
+            engagement=eng_score,
+        )
+
+        # Compute overall score
+        overall = (
+            WEIGHT_RELEVANCE * rel_score +
+            WEIGHT_RECENCY * rec_score +
+            WEIGHT_ENGAGEMENT * eng_score
+        )
+
+        # Apply penalty for unknown engagement
+        if eng_raw[i] is None:
+            overall -= UNKNOWN_ENGAGEMENT_PENALTY
+
+        # Apply penalty for low date confidence
+        if item.date_confidence == "low":
+            overall -= 10
+        elif item.date_confidence == "med":
+            overall -= 5
+
+        item.score = max(0, min(100, int(overall)))
+
+    return items
+
+
+def score_x_items(items: List[schema.XItem]) -> List[schema.XItem]:
+    """Compute scores for X items.
+
+    Args:
+        items: List of X items
+
+    Returns:
+        Items with updated scores
+    """
+    if not items:
+        return items
+
+    # Compute raw engagement scores
+    eng_raw = [compute_x_engagement_raw(item.engagement) for item in items]
+
+    # Normalize engagement to 0-100
+    eng_normalized = normalize_to_100(eng_raw)
+
+    for i, item in enumerate(items):
+        # Relevance subscore (model-provided, convert to 0-100)
+        rel_score = int(item.relevance * 100)
+
+        # Recency subscore
+        rec_score = dates.recency_score(item.date)
+
+        # Engagement subscore
+        if eng_normalized[i] is not None:
+            eng_score = int(eng_normalized[i])
+        else:
+            eng_score = DEFAULT_ENGAGEMENT
+
+        # Store subscores
+        item.subs = schema.SubScores(
+            relevance=rel_score,
+            recency=rec_score,
+            engagement=eng_score,
+        )
+
+        # Compute overall score
+        overall = (
+            WEIGHT_RELEVANCE * rel_score +
+            WEIGHT_RECENCY * rec_score +
+            WEIGHT_ENGAGEMENT * eng_score
+        )
+
+        # Apply penalty for unknown engagement
+        if eng_raw[i] is None:
+            overall -= UNKNOWN_ENGAGEMENT_PENALTY
+
+        # Apply penalty for low date confidence
+        if item.date_confidence == "low":
+            overall -= 10
+        elif item.date_confidence == "med":
+            overall -= 5
+
+        item.score = max(0, min(100, int(overall)))
+
+    return items
+
+
+def sort_items(items: List[Union[schema.RedditItem, schema.XItem]]) -> List:
+    """Sort items by score (descending), then date, then source priority.
+
+    Args:
+        items: List of items to sort
+
+    Returns:
+        Sorted items
+    """
+    def sort_key(item):
+        # Primary: score descending (negate for descending)
+        score = -item.score
+
+        # Secondary: date descending (recent first)
+        date = item.date or "0000-00-00"
+        date_key = -int(date.replace("-", ""))
+
+        # Tertiary: source priority (Reddit before X)
+        source_priority = 0 if isinstance(item, schema.RedditItem) else 1
+
+        # Quaternary: title/text for stability
+        text = getattr(item, "title", "") or getattr(item, "text", "")
+
+        return (score, date_key, source_priority, text)
+
+    return sorted(items, key=sort_key)

scripts/lib/xai_x.py

@@ -0,0 +1,192 @@
+"""xAI API client for X (Twitter) discovery."""
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from . import http
+
+# xAI uses chat completions endpoint
+XAI_CHAT_URL = "https://api.x.ai/v1/chat/completions"
+
+X_SEARCH_PROMPT = """You have access to real-time X (Twitter) data. Search for posts about: {topic}
+
+Focus on posts from {from_date} to {to_date}. Find 15-30 high-quality, relevant posts.
+
+IMPORTANT: Return ONLY valid JSON in this exact format, no other text:
+{{
+  "items": [
+    {{
+      "text": "Post text content (truncated if long)",
+      "url": "https://x.com/user/status/...",
+      "author_handle": "username",
+      "date": "YYYY-MM-DD or null if unknown",
+      "engagement": {{
+        "likes": 100,
+        "reposts": 25,
+        "replies": 15,
+        "quotes": 5
+      }},
+      "why_relevant": "Brief explanation of relevance",
+      "relevance": 0.85
+    }}
+  ]
+}}
+
+Rules:
+- relevance is 0.0 to 1.0 (1.0 = highly relevant)
+- date must be YYYY-MM-DD format or null
+- engagement can be null if unknown
+- Include diverse voices/accounts if applicable
+- Prefer posts with substantive content, not just links"""
+
+
+def search_x(
+    api_key: str,
+    model: str,
+    topic: str,
+    from_date: str,
+    to_date: str,
+    mock_response: Optional[Dict] = None,
+) -> Dict[str, Any]:
+    """Search X for relevant posts using xAI API with live search.
+
+    Args:
+        api_key: xAI API key
+        model: Model to use
+        topic: Search topic
+        from_date: Start date (YYYY-MM-DD)
+        to_date: End date (YYYY-MM-DD)
+        mock_response: Mock response for testing
+
+    Returns:
+        Raw API response
+    """
+    if mock_response is not None:
+        return mock_response
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+
+    # Use chat completions format with search enabled
+    payload = {
+        "model": model,
+        "messages": [
+            {
+                "role": "system",
+                "content": "You are a research assistant with access to real-time X (Twitter) data. Search X and return structured results."
+            },
+            {
+                "role": "user",
+                "content": X_SEARCH_PROMPT.format(
+                    topic=topic,
+                    from_date=from_date,
+                    to_date=to_date,
+                ),
+            }
+        ],
+        "search_parameters": {
+            "mode": "auto",
+            "sources": [{"type": "x"}],
+            "from_date": from_date,
+            "to_date": to_date,
+        },
+    }
+
+    return http.post(XAI_CHAT_URL, payload, headers=headers, timeout=90)
+
+
+def parse_x_response(response: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Parse xAI response to extract X items.
+
+    Args:
+        response: Raw API response
+
+    Returns:
+        List of item dicts
+    """
+    items = []
+
+    # Try to find the output text
+    output_text = ""
+    if "output" in response:
+        output = response["output"]
+        if isinstance(output, str):
+            output_text = output
+        elif isinstance(output, list):
+            for item in output:
+                if isinstance(item, dict):
+                    if item.get("type") == "message":
+                        content = item.get("content", [])
+                        for c in content:
+                            if isinstance(c, dict) and c.get("type") == "output_text":
+                                output_text = c.get("text", "")
+                                break
+                    elif "text" in item:
+                        output_text = item["text"]
+                elif isinstance(item, str):
+                    output_text = item
+                if output_text:
+                    break
+
+    # Also check for choices (older format)
+    if not output_text and "choices" in response:
+        for choice in response["choices"]:
+            if "message" in choice:
+                output_text = choice["message"].get("content", "")
+                break
+
+    if not output_text:
+        return items
+
+    # Extract JSON from the response
+    json_match = re.search(r'\{[\s\S]*"items"[\s\S]*\}', output_text)
+    if json_match:
+        try:
+            data = json.loads(json_match.group())
+            items = data.get("items", [])
+        except json.JSONDecodeError:
+            pass
+
+    # Validate and clean items
+    clean_items = []
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            continue
+
+        url = item.get("url", "")
+        if not url:
+            continue
+
+        # Parse engagement
+        engagement = None
+        eng_raw = item.get("engagement")
+        if isinstance(eng_raw, dict):
+            engagement = {
+                "likes": int(eng_raw.get("likes", 0)) if eng_raw.get("likes") else None,
+                "reposts": int(eng_raw.get("reposts", 0)) if eng_raw.get("reposts") else None,
+                "replies": int(eng_raw.get("replies", 0)) if eng_raw.get("replies") else None,
+                "quotes": int(eng_raw.get("quotes", 0)) if eng_raw.get("quotes") else None,
+            }
+
+        clean_item = {
+            "id": f"X{i+1}",
+            "text": str(item.get("text", "")).strip()[:500],  # Truncate long text
+            "url": url,
+            "author_handle": str(item.get("author_handle", "")).strip().lstrip("@"),
+            "date": item.get("date"),
+            "engagement": engagement,
+            "why_relevant": str(item.get("why_relevant", "")).strip(),
+            "relevance": min(1.0, max(0.0, float(item.get("relevance", 0.5)))),
+        }
+
+        # Validate date format
+        if clean_item["date"]:
+            if not re.match(r'^\d{4}-\d{2}-\d{2}$', str(clean_item["date"])):
+                clean_item["date"] = None
+
+        clean_items.append(clean_item)
+
+    return clean_items