init

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.env

README.md

@@ -0,0 +1,135 @@
+# Topcoder Challenge Scout (Agentic MCP)
+
+An agentic AI app that discovers and prioritizes Topcoder challenges using the Topcoder MCP server and OpenAI for keyword extraction, intelligent scoring, and action planning. The model decides what to search (keywords) and how to rank results; you provide only high-level requirements.
+
+## Use case
+- Input a free-form requirement (e.g., "Looking for recent active LLM development challenges with web UI").
+- The agent extracts minimal, broad keywords automatically (1–3 terms).
+- Fetches challenges via MCP; defaults to last 90 days and active/open status.
+- Uses OpenAI to score relevance, produce recommendation stars (1–5), and return a brief plan.
+- Displays a compact table (title, tags, prize, deadline, stars, AI reason) plus a quick plan.
+
+## Setup
+
+### 1. Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Configure OpenAI API
+You need an OpenAI API key to enable agentic keyword extraction, scoring, and planning features.
+
+**Quick Setup:**
+```bash
+python setup_env.py
+```
+
+**Manual Setup:**
+1. Get your API key from https://platform.openai.com/api-keys
+2. Set environment variable:
+   ```bash
+   # macOS/Linux
+   export OPENAI_API_KEY=your_api_key_here
+   
+   # Windows (Command Prompt)
+   set OPENAI_API_KEY=your_api_key_here
+   
+   # Windows (PowerShell)
+   $env:OPENAI_API_KEY="your_api_key_here"
+   ```
+
+**Optional Configuration:**
+- `OPENAI_BASE_URL`: Custom API base URL (default: https://api.openai.com/v1)
+- `OPENAI_MODEL`: Model to use (default: gpt-4o-mini)
+
+### 3. Run the App (Local)
+```bash
+python app.py
+```
+
+Open the printed local URL to use the UI.
+
+UI inputs:
+- `Requirements`: free-form text. The model extracts keywords automatically.
+- `Use MCP (recommended)`: toggle live Topcoder data.
+- `Debug mode`: shows detailed MCP and model logs.
+
+Defaults applied by the agent:
+- Time window: within last 90 days
+- Status: active/open (unknown kept; closed/cancelled filtered)
+
+## Features
+
+### MCP Integration
+- Uses the official MCP SDK via SSE/streamable HTTP
+- Connects to `https://api.topcoder-dev.com/v6/mcp/mcp` and `https://api.topcoder-dev.com/v6/mcp/sse`
+- Fetches real-time challenge data; includes robust normalization and fallbacks
+- Built-in retries and detailed debug logging
+
+### AI-Powered Features
+- **Keyword Extraction**: From free-form requirements to 1–3 broad search terms
+- **Smart Scoring**: Relevance scoring with reasons (0–1), converted to 1–5 stars
+- **Action Planning**: Generates concise next steps for top picks
+- **Context-Aware**: Considers skills, tags, brief descriptions, and prize amounts
+
+### Cost Information
+Using gpt-4o-mini (recommended):
+- ~100-200 tokens per scoring query
+- ~200-300 tokens per plan generation
+- Estimated cost: $0.02-0.10 per 1000 queries
+
+## Debug Mode
+Enable "Debug mode" in the UI to view:
+- MCP connection attempts and responses
+- OpenAI API calls and responses
+- Detailed scoring and ranking logs
+- Error messages and troubleshooting info
+
+## Deploy on Hugging Face Spaces
+1. Create a new Space
+   - Space type: `Gradio`
+   - Hardware: `CPU basic`
+   - Runtime: `Python`
+2. Add files
+   - Upload the repository contents (`app.py`, `requirements.txt`, `README.md`, etc.)
+3. Set secrets in the Space
+   - Settings → Secrets → Add new secret:
+     - Name: `OPENAI_API_KEY`
+     - Value: your OpenAI API key
+   - (Optional) `OPENAI_BASE_URL` and `OPENAI_MODEL` if using a compatible provider
+4. Build & run
+   - The Space auto-installs from `requirements.txt` and runs `app.py`
+   - Ensure outbound network is allowed for MCP and OpenAI endpoints
+5. Test
+   - Open the Space URL
+   - Enter a natural-language requirement and click "Find challenges"
+   - Verify you see recommendation stars and an AI plan
+
+Notes
+- The app listens on Gradio’s default port; `demo.launch(server_name="0.0.0.0")` is set.
+- No GPU required; designed for CPU basic.
+
+## Deliverables Checklist (per Spec)
+- Functional agent application using the Topcoder MCP server (SSE/HTTP) with a clear, user-friendly UI (Gradio)
+- Runs on Hugging Face Spaces (CPU Basic) without GPU
+- Clear use case and purpose documented (this README)
+- Intelligent features: LLM-based keyword extraction, relevance scoring with reasons, star recommendations, and plan generation
+- Robust behavior: retries, fallbacks, and debug logging
+- Deployment/configuration instructions for Spaces (this README, plus `setup_env.py` for local setup)
+- Optional: short demo video (3–5 minutes) showcasing the agent’s core workflow
+
+## Submission Guidance
+Provide either (or both):
+1. Public Hugging Face Space URL with the agent running; and/or
+2. A downloadable zip of this repository
+
+Also include:
+- A brief use case summary (can reference this README)
+- Short notes on MCP integration (tools discovery and call flow)
+- Any custom configuration (e.g., model/base URL overrides)
+
+Recommended final checklist before submitting:
+- `OPENAI_API_KEY` secret set in the Space
+- Space loads and returns live results from MCP
+- Table shows stars and AI reason; Plan section renders
+- Debug mode produces logs without errors

app.py

@@ -0,0 +1,667 @@
+import json
+import os
+import re
+import time
+import uuid
+import sys
+import logging
+import asyncio
+import traceback
+from datetime import datetime, timezone, timedelta
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import gradio as gr
+import requests
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from openai import OpenAI
+from dotenv import load_dotenv
+
+load_dotenv()
+
+MCP_SSE_URL = "https://api.topcoder-dev.com/v6/mcp/sse"
+MCP_MESSAGES_URL = "https://api.topcoder-dev.com/v6/mcp/messages"
+MCP_HTTP_BASE = "https://api.topcoder-dev.com/v6/mcp/mcp"
+
+
+# Console logger for runtime diagnostics
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    stream=sys.stdout,
+)
+logger = logging.getLogger("challenge_scout")
+
+
+@dataclass
+class Challenge:
+    id: str
+    title: str
+    prize: float
+    deadline: str
+    tags: List[str]
+    description: str = ""
+
+
+FALLBACK_DATA: List[Challenge] = [
+    Challenge(id="123", title="Build a Minimal MCP Agent UI", prize=300.0, deadline="2025-08-20", tags=["mcp", "python", "gradio"]),
+    Challenge(id="456", title="Topcoder Data Parsing Toolkit", prize=500.0, deadline="2025-08-15", tags=["data", "api", "json"]),
+    Challenge(id="789", title="AI-Powered Web Application", prize=250.0, deadline="2025-08-18", tags=["ai", "web", "optimization"]),
+]
+
+
+def _open_mcp_session(
+    connect_timeout: float = 5.0,
+    read_window_seconds: float = 8.0,
+    debug: bool = False,
+    max_retries: int = 2,
+) -> Tuple[Optional[str], str]:
+    """Open SSE and extract a sessionId from the first data event.
+
+    We keep the stream open for up to `read_window_seconds` to wait for the
+    line like: "data: /v6/mcp/messages?sessionId=<uuid>".
+    """
+    logs: List[str] = []
+    headers = {
+        "Accept": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+    }
+    backoff = 0.6
+    for attempt in range(1, max_retries + 2):
+        if debug:
+            logger.info(f"SSE dialing attempt={attempt} url={MCP_SSE_URL}")
+        try:
+            t0 = time.time()
+            resp = requests.get(
+                MCP_SSE_URL,
+                headers=headers,
+                timeout=(connect_timeout, read_window_seconds + 2.0),
+                stream=True,
+            )
+            elapsed = time.time() - t0
+            logs.append(f"SSE attempt {attempt}: status={resp.status_code}, elapsed={elapsed:.2f}s")
+            if debug:
+                logger.info(f"SSE attempt {attempt} status={resp.status_code} elapsed={elapsed:.2f}s")
+            resp.raise_for_status()
+
+            start = time.time()
+            pattern = re.compile(r"^data:\s*/v6/mcp/messages\?sessionId=([a-f0-9-]+)\s*$", re.IGNORECASE)
+            for line in resp.iter_lines(decode_unicode=True, chunk_size=1):
+                if line is None:
+                    if time.time() - start > read_window_seconds:
+                        logs.append("SSE: timeout waiting for data line")
+                        break
+                    continue
+                if not isinstance(line, str):
+                    if time.time() - start > read_window_seconds:
+                        logs.append("SSE: timeout (non-str line)")
+                        break
+                    continue
+                if debug:
+                    logs.append(f"SSE line: {line[:160]}")
+                    logger.info(f"SSE line: {line[:160]}")
+                m = pattern.match(line)
+                if m:
+                    sid = m.group(1)
+                    logs.append(f"SSE: obtained sessionId={sid}")
+                    if debug:
+                        logger.info(f"SSE obtained sessionId={sid}")
+                    return sid, "\n".join(logs)
+                if time.time() - start > read_window_seconds:
+                    logs.append("SSE: read window exceeded without sessionId")
+                    if debug:
+                        logger.info("SSE: read window exceeded without sessionId")
+                    break
+        except Exception as e:
+            logs.append(f"SSE error on attempt {attempt}: {e}")
+            if debug:
+                logger.info(f"SSE error on attempt {attempt}: {e}")
+        time.sleep(backoff)
+        backoff *= 1.6
+    return None, "\n".join(logs)
+
+
+def _mcp_list_challenges(
+    debug: bool = False,
+    retries: int = 2,
+) -> Tuple[List[Challenge], Optional[str], str]:
+    """Call MCP using the official SDK (JSON-RPC over streamable HTTP) and return compact challenges.
+
+    Returns (challenges, error, debug_logs)
+    """
+    logs: List[str] = []
+    async def _do() -> Tuple[List[Challenge], Optional[str], str]:
+        try:
+            t0 = time.time()
+            async with sse_client(MCP_SSE_URL) as (read, write):
+                async with ClientSession(read, write) as session:
+                    await session.initialize()
+                    tools = await session.list_tools()
+                    names = [t.name for t in tools.tools]
+                    logs.append(f"SDK tools: {names}")
+                    # Prefer a known tool name pattern
+                    tool_name = None
+                    for cand in [
+                        "query-tc-challenges",
+                        "query-tc-challenges-public",
+                        "query-tc-challenges-private",
+                    ]:
+                        if cand in names:
+                            tool_name = cand
+                            break
+                    if not tool_name and names:
+                        tool_name = names[0]
+                    if not tool_name:
+                        return [], "No tools available", "\n".join(logs)
+                    # Call with minimal args (tool often supports pagination; start small)
+                    args = {"page": 1, "pageSize": 20}
+                    logs.append(f"Calling tool {tool_name} with args: {args}")
+                    try:
+                        result = await session.call_tool(tool_name, args)
+                    except Exception as e:
+                        logs.append(f"call_tool error: {e}")
+                        return [], str(e), "\n".join(logs)
+
+                    items: List[Challenge] = []
+                    payload = getattr(result, "structuredContent", None)
+                    if not payload:
+                        # Fallback to text content join and attempt JSON extraction of an object with data[] or array
+                        combined_text = "\n".join(
+                            getattr(c, "text", "") for c in getattr(result, "content", []) if hasattr(c, "text")
+                        )
+                        obj_match = re.search(r"\{[\s\S]*\}$", combined_text)
+                        if obj_match:
+                            try:
+                                payload = json.loads(obj_match.group(0))
+                            except Exception:
+                                payload = None
+                    # Normalize list of challenge-like dicts
+                    raw_list = []
+                    if isinstance(payload, dict) and isinstance(payload.get("data"), list):
+                        raw_list = payload.get("data")
+                        logs.append(f"Received {len(raw_list)} items from data[]")
+                    elif isinstance(payload, list):
+                        raw_list = payload
+                        logs.append(f"Received {len(raw_list)} items from top-level list")
+                    else:
+                        logs.append(f"Unexpected payload shape: {type(payload)}")
+
+                    def to_ch(item: dict) -> Challenge:
+                        title = (
+                            str(item.get("name") or item.get("title") or item.get("challengeTitle") or "")
+                        )
+                        # prize from prizeSets → sum values if present
+                        prize = 0.0
+                        prize_sets = item.get("prizeSets")
+                        if isinstance(prize_sets, list):
+                            for s in prize_sets:
+                                prizes = s.get("prizes") if isinstance(s, dict) else None
+                                if isinstance(prizes, list):
+                                    for p in prizes:
+                                        val = None
+                                        if isinstance(p, dict):
+                                            val = p.get("value") or p.get("amount")
+                                        try:
+                                            prize += float(val or 0)
+                                        except Exception:
+                                            pass
+                        else:
+                            prize_val = item.get("totalPrizes") or item.get("prize") or item.get("totalPrize") or 0
+                            try:
+                                prize = float(prize_val or 0)
+                            except Exception:
+                                prize = 0.0
+                        # deadline candidates
+                        deadline = (
+                            str(
+                                item.get("endDate")
+                                or item.get("submissionEndDate")
+                                or item.get("registrationEndDate")
+                                or item.get("startDate")
+                                or ""
+                            )
+                        )
+                        # tags candidates
+                        tg = item.get("tags")
+                        if not isinstance(tg, list):
+                            tg = []
+                        # add some fallbacks/contextual labels
+                        for extra in [item.get("track"), item.get("type"), item.get("status")]:
+                            if extra:
+                                tg.append(extra)
+                        # skills may be list of dicts or strings
+                        sk = item.get("skills")
+                        if isinstance(sk, list):
+                            for s in sk:
+                                if isinstance(s, dict):
+                                    name = s.get("name") or s.get("id")
+                                    if name:
+                                        tg.append(str(name))
+                                else:
+                                    tg.append(str(s))
+                        tg = [str(x) for x in tg if x]
+                        desc = str(item.get("description") or "")
+                        return Challenge(
+                            id=str(item.get("id", "")),
+                            title=title,
+                            prize=prize,
+                            deadline=deadline,
+                            tags=tg,
+                            description=desc,
+                        )
+
+                    for it in raw_list:
+                        if isinstance(it, dict):
+                            items.append(to_ch(it))
+                    logs.append(f"Normalized {len(items)} challenges")
+                    return items, None, "\n".join(logs)
+        except Exception as e:
+            logs.append(f"SDK fatal: {e}")
+            logs.append(traceback.format_exc())
+            # Try to unwrap ExceptionGroup-like messages if any
+            try:
+                from exceptiongroup import ExceptionGroup  # type: ignore
+            except Exception:
+                ExceptionGroup = None  # type: ignore
+            if ExceptionGroup and isinstance(e, ExceptionGroup):  # type: ignore[arg-type]
+                for idx, sub in enumerate(e.exceptions):  # type: ignore[attr-defined]
+                    logs.append(f"  sub[{idx}]: {type(sub).__name__}: {sub}")
+            return [], str(e), "\n".join(logs)
+
+    # Run the async block
+    return asyncio.run(_do())
+
+
+def shortlist(challenge_list: List[Challenge], keyword: str, min_prize: float) -> List[Challenge]:
+    keyword_lower = keyword.lower().strip()
+    results = []
+    for ch in challenge_list:
+        if ch.prize < min_prize:
+            continue
+        hay = f"{ch.title} {' '.join(ch.tags)}".lower()
+        if keyword_lower and keyword_lower not in hay:
+            continue
+        results.append(ch)
+    # lightweight ranking: by prize desc
+    results.sort(key=lambda c: c.prize, reverse=True)
+    return results
+
+
+def _parse_deadline(dt_str: str) -> Optional[datetime]:
+    if not dt_str:
+        return None
+    try:
+        # Try ISO 8601 with Z
+        return datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
+    except Exception:
+        try:
+            return datetime.strptime(dt_str, "%Y-%m-%d")
+        except Exception:
+            return None
+
+
+def _filter_by_days(items: List[Challenge], days_ahead: int) -> List[Challenge]:
+    if days_ahead <= 0:
+        return items
+    now = datetime.now(timezone.utc)
+    limit = now + timedelta(days=days_ahead)
+    kept: List[Challenge] = []
+    for ch in items:
+        dt = _parse_deadline(ch.deadline)
+        if dt is None:
+            kept.append(ch)
+            continue
+        if now <= dt <= limit:
+            kept.append(ch)
+    return kept
+
+
+def _generate_plan(items: List[Challenge], keyword: str, min_prize: float, days_ahead: int, debug: bool = False) -> Tuple[str, str]:
+    # Keep context tiny: only top 8 rows of compact fields
+    top = items[:8]
+    compact = [
+        {
+            "title": c.title,
+            "prize": c.prize,
+            "deadline": c.deadline,
+            "tags": c.tags[:5],
+        }
+        for c in top
+    ]
+    
+    logs: List[str] = []
+    api_key = os.getenv("OPENAI_API_KEY")
+    base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    
+    if not api_key:
+        logs.append("Missing OPENAI_API_KEY")
+        return "", "\n".join(logs)
+    
+    try:
+        client = OpenAI(
+            api_key=api_key,
+            base_url=base_url
+        )
+        
+        prompt = (
+            "You are a concise challenge scout. Given compact challenge metadata, output:\n"
+            "- Top 3 picks (title + brief reason)\n"
+            "- Quick plan of action (3 bullets)\n"
+            f"Constraints: keyword='{keyword}', min_prize>={min_prize}, within {days_ahead} days.\n"
+            f"Data: {json.dumps(compact)}"
+        )
+        
+        if debug:
+            logs.append(f"PLAN OpenAI prompt: {prompt[:1500]}")
+        
+        response = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
+            messages=[
+                {"role": "system", "content": "You are a helpful, terse assistant."},
+                {"role": "user", "content": prompt},
+            ],
+            temperature=0.3,
+            timeout=20
+        )
+        
+        text = response.choices[0].message.content.strip()
+        
+        if debug:
+            logs.append(f"PLAN OpenAI output: {text[:800]}")
+            logger.info("\n".join(logs))
+            
+        return text, "\n".join(logs)
+        
+    except Exception as e:
+        if debug:
+            logs.append(f"PLAN OpenAI error: {e}")
+            logger.info("\n".join(logs))
+        return "", "\n".join(logs)
+
+
+def _score_items(items: List[Challenge], keyword: str, debug: bool = False) -> Tuple[List[tuple[Challenge, float, str]], str]:
+    """Score challenges using OpenAI API and return (challenge, score, reason) tuples"""
+    api_key = os.getenv("OPENAI_API_KEY")
+    base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    
+    results: List[tuple[Challenge, float, str]] = []
+    slog: List[str] = []
+    
+    if not items:
+        return results, "\n".join(slog)
+    
+    if not api_key:
+        if debug:
+            slog.append("Missing OPENAI_API_KEY")
+        return results, "\n".join(slog)
+
+    compact = [
+        {
+            "id": c.id,
+            "title": c.title,
+            "prize": c.prize,
+            "deadline": c.deadline,
+            "tags": c.tags[:6],
+            "description": (c.description or "").replace("\n", " ")[:400],
+        }
+        for c in items[:8]
+    ]
+
+    scoring_prompt = (
+        "You are an expert Topcoder challenge analyst. Analyze items and rate match to the query.\n"
+        f"Query: {keyword}\n"
+        "Items: " + json.dumps(compact) + "\n\n"
+        "Instructions:\n"
+        "- Consider skills, tags, and brief description.\n"
+        "- Higher prize is slightly better all else equal.\n"
+        "- Return ONLY JSON array of objects: [{id, score, reason}] where 0<=score<=1.\n"
+        "- Do not include any extra text."
+    )
+
+    try:
+        client = OpenAI(
+            api_key=api_key,
+            base_url=base_url
+        )
+        
+        if debug:
+            slog.append(f"OpenAI model: {os.getenv('OPENAI_MODEL', 'gpt-4o-mini')}")
+            slog.append(f"OpenAI prompt: {scoring_prompt[:1500]}")
+        
+        response = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
+            messages=[
+                {"role": "system", "content": "You are a helpful, terse assistant. Return JSON only."},
+                {"role": "user", "content": scoring_prompt},
+            ],
+            temperature=0.2,
+            timeout=40
+        )
+        
+        text = response.choices[0].message.content.strip()
+        
+        if debug:
+            slog.append(f"OpenAI raw output: {text[:800]}")
+        
+        # Extract JSON from response
+        m = re.search(r"\[\s*\{[\s\S]*\}\s*\]", text)
+        if not m:
+            if debug:
+                slog.append("No valid JSON array found in response")
+            return results, "\n".join(slog)
+        
+        try:
+            arr = json.loads(m.group(0))
+            score_map: dict[str, tuple[float, str]] = {}
+            
+            for obj in arr:
+                if isinstance(obj, dict):
+                    cid = str(obj.get("id", ""))
+                    score = float(obj.get("score", 0))
+                    reason = str(obj.get("reason", ""))
+                    score_map[cid] = (max(0.0, min(1.0, score)), reason)
+            
+            # Build results with scores
+            out: List[tuple[Challenge, float, str]] = []
+            for c in items:
+                if c.id in score_map:
+                    s, r = score_map[c.id]
+                    out.append((c, s, r))
+                else:
+                    # Fallback: light prize-based score for missing items
+                    out.append((c, min(c.prize / 1000.0, 1.0) * 0.3, ""))
+            
+            if debug:
+                slog.append(f"OpenAI parsed {len(score_map)} scores")
+                logger.info("\n".join(slog))
+            
+            return out, "\n".join(slog)
+            
+        except json.JSONDecodeError as e:
+            if debug:
+                slog.append(f"JSON decode error: {e}")
+            return results, "\n".join(slog)
+        
+    except Exception as e:
+        if debug:
+            slog.append(f"OpenAI API error: {e}")
+            logger.info("\n".join(slog))
+        return results, "\n".join(slog)
+
+
+def _require_llm_config() -> Tuple[bool, str]:
+    """Check if OpenAI API is properly configured"""
+    if os.getenv("OPENAI_API_KEY"):
+        return True, ""
+    return False, "Set OPENAI_API_KEY for LLM scoring"
+
+
+def _extract_keywords(requirements: str, debug: bool = False) -> Tuple[str, str]:
+    """Use LLM to extract 1-3 broad, concise keywords from free-form requirements."""
+    logs: List[str] = []
+    api_key = os.getenv("OPENAI_API_KEY")
+    base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    if not api_key:
+        return "", "Missing OPENAI_API_KEY"
+    try:
+        client = OpenAI(api_key=api_key, base_url=base_url)
+        prompt = (
+            "You extract compact search keywords.\n"
+            "Given a user's requirements, output a comma-separated list of up to 3 broad keywords (1-3 words each).\n"
+            "Keep them minimal, generic, and deduplicated.\n"
+            "Examples:\n"
+            "- 'Need an LLM project with Python and simple UI' -> LLM, Python, UI\n"
+            "- 'Data visualization challenges about dashboards' -> data visualization, dashboard\n"
+            f"Requirements: {requirements.strip()}\n"
+            "Return only the keywords, comma-separated."
+        )
+        if debug:
+            logs.append(f"KW prompt: {prompt[:500]}")
+        resp = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
+            messages=[
+                {"role": "system", "content": "You are a terse assistant. Return only keywords."},
+                {"role": "user", "content": prompt},
+            ],
+            temperature=0.2,
+            timeout=20,
+        )
+        text = (resp.choices[0].message.content or "").strip()
+        # normalize to simple comma-separated
+        text = re.sub(r"\s*[,\n]\s*", ", ", text)
+        # keep at most 3
+        parts = [p.strip() for p in text.split(",") if p.strip()]
+        keywords = ", ".join(parts[:3])
+        if debug:
+            logs.append(f"KW extracted: {keywords}")
+        return keywords, "\n".join(logs)
+    except Exception as e:
+        if debug:
+            logs.append(f"KW error: {e}")
+        return "", "\n".join(logs)
+
+
+def _filter_active(items: List[Challenge]) -> List[Challenge]:
+    """Keep items that appear to be active/online based on tags or status hints."""
+    kept: List[Challenge] = []
+    for ch in items:
+        tags_lower = [t.lower() for t in ch.tags]
+        if any(t == "active" or t == "open" for t in tags_lower):
+            kept.append(ch)
+        else:
+            # If status is unknown, keep it (avoid over-filtering)
+            if not any(t in ("completed", "closed", "cancelled", "draft") for t in tags_lower):
+                kept.append(ch)
+    return kept
+
+
+def _stars_for_score(score: float) -> str:
+    n = max(1, min(5, int(round(score * 5))))
+    return "★" * n + "☆" * (5 - n)
+
+
+def run_query(requirements: str, use_mcp: bool, debug_mode: bool):
+    debug_text = ""
+    if debug_mode:
+        logger.info(
+            f"RUN start use_mcp={use_mcp} keyword={keyword!r} min_prize={min_prize} days_ahead={days_ahead}"
+        )
+    # Defaults for agent flow
+    min_prize = 0.0
+    days_ahead = 90
+
+    # Extract compact keywords from requirements
+    keyword, kw_logs = _extract_keywords(requirements, debug=debug_mode)
+
+    if use_mcp:
+        items, err, dbg = _mcp_list_challenges(debug=debug_mode)
+        debug_text = dbg or ""
+        if kw_logs:
+            debug_text = (debug_text + "\n\n" + kw_logs).strip()
+        if err:
+            items = FALLBACK_DATA
+            status = f"MCP fallback: {err}"
+            if debug_mode:
+                logger.info(f"RUN fallback reason: {err}")
+        else:
+            status = "MCP OK"
+            if debug_mode:
+                logger.info("RUN MCP OK")
+    else:
+        items = FALLBACK_DATA
+        status = "Local sample"
+
+    # Apply time window first, then keyword/prize filtering
+    items = _filter_by_days(items, days_ahead)
+    items = _filter_active(items)
+    # Apply light shortlist by prize only; rely on AI scoring for relevance
+    filtered = shortlist(items, "", min_prize)
+    # Enforce LLM config for scoring
+    ok, cfg_msg = _require_llm_config()
+    score_logs = ""
+    if not ok:
+        status = f"{status} | LLM config required: {cfg_msg}"
+    else:
+        scored, score_logs = _score_items(filtered, keyword, debug=debug_mode)
+        if scored:
+            scored.sort(key=lambda t: t[1], reverse=True)
+            filtered = [c for c, _, _ in scored]
+    # If MCP returned items but filtering removed all (e.g., many items missing prize), show unfiltered
+    if not filtered and items:
+        filtered = items
+        status = f"{status} (no matches; showing unfiltered)"
+    plan_text, plan_logs = _generate_plan(filtered, keyword, min_prize, days_ahead, debug=debug_mode) if filtered else ("", "")
+
+    # Build a map from id to (score, reason) for star display
+    id_to_score_reason: dict[str, tuple[float, str]] = {}
+    if ok:
+        for c, s, r in (scored if 'scored' in locals() else []):
+            id_to_score_reason[c.id] = (s, r)
+
+    rows = []
+    for c in filtered:
+        s, r = id_to_score_reason.get(c.id, (0.0, ""))
+        stars = _stars_for_score(s)
+        rows.append([
+            c.title,
+            f"${c.prize:,.0f}",
+            c.deadline,
+            ", ".join(c.tags),
+            stars,
+            (r[:160] + ("…" if len(r) > 160 else "")) if r else "",
+            c.id,
+        ])
+    # Append model logs into debug output when enabled and also log to console
+    if debug_mode:
+        merged_logs = (debug_text + "\n\n" + score_logs + "\n\n" + plan_logs).strip()
+        debug_text = merged_logs
+        if merged_logs:
+            logger.info(merged_logs)
+    return rows, status, debug_text, plan_text
+
+
+with gr.Blocks(title="Topcoder Challenge Scout") as demo:
+    gr.Markdown("**Topcoder Challenge Scout** — agent picks tools, you provide requirements")
+    with gr.Row():
+        requirements = gr.Textbox(label="Requirements", placeholder="e.g. Looking for recent active LLM development challenges with web UI", lines=3)
+        use_mcp = gr.Checkbox(label="Use MCP (recommended)", value=True)
+        debug_mode = gr.Checkbox(label="Debug mode", value=False)
+    gr.Markdown("Default filters: within last 90 days, active status. The agent extracts minimal keywords automatically.")
+    run_btn = gr.Button("Find challenges")
+    status = gr.Textbox(label="Status", interactive=False)
+    table = gr.Dataframe(headers=["Title", "Prize", "Deadline", "Tags", "Recommend", "AI Reason", "Id"], wrap=True)
+    plan_md = gr.Markdown("", label="Plan")
+    with gr.Accordion("Debug output", open=False):
+        debug_out = gr.Textbox(label="Logs", interactive=False, lines=8)
+
+    run_btn.click(
+        fn=run_query,
+        inputs=[requirements, use_mcp, debug_mode],
+        outputs=[table, status, debug_out, plan_md],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=int(os.getenv("PORT", "7860")))

mcp_demo.py

@@ -0,0 +1,28 @@
+import asyncio
+import os
+from typing import Any
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+MCP_BASE = os.getenv("TOPCODER_MCP_BASE", "https://api.topcoder-dev.com/v6/mcp/mcp")
+
+
+async def main() -> None:
+    async with streamablehttp_client(MCP_BASE) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            names = [t.name for t in tools.tools]
+            print("Tools:", names)
+
+            # If a challenges tool exists, try a harmless list/describe call signature
+            # We just print availability here; you can extend to actual tool calls once schema is known
+
+
+def run() -> None:
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

requirements.txt

@@ -0,0 +1,7 @@
+gradio==4.44.0
+requests==2.32.3
+uvicorn==0.30.3
+mcp==1.2.0
+openai==1.55.3
+python-dotenv==1.0.0
+exceptiongroup==1.2.2 ; python_version < '3.11'

setup_env.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Environment setup script for OpenAI API configuration
+"""
+
+import os
+import sys
+
+
+def check_openai_config():
+    """Check current OpenAI configuration"""
+    print("🔍 检查当前OpenAI配置")
+    print("-" * 40)
+    
+    api_key = os.getenv("OPENAI_API_KEY")
+    base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+    
+    print(f"🔑 OPENAI_API_KEY: {'✅ 已设置' if api_key else '❌ 未设置'}")
+    print(f"🌐 OPENAI_BASE_URL: {base_url}")
+    print(f"🤖 OPENAI_MODEL: {model}")
+    
+    if api_key:
+        # 隐藏API key的大部分内容，只显示前4位和后4位
+        masked_key = f"{api_key[:4]}...{api_key[-4:]}" if len(api_key) > 8 else "***"
+        print(f"    (API Key: {masked_key})")
+        return True
+    else:
+        return False
+
+
+def show_setup_guide():
+    """显示设置指南"""
+    print("\n🚀 OpenAI API 设置指南")
+    print("=" * 50)
+    
+    print("1. 获取OpenAI API Key:")
+    print("   • 访问: https://platform.openai.com/api-keys")
+    print("   • 登录或注册OpenAI账户")
+    print("   • 点击 'Create new secret key'")
+    print("   • 复制生成的API key")
+    
+    print("\n2. 设置环境变量:")
+    if sys.platform.startswith('win'):
+        print("   Windows (Command Prompt):")
+        print("   set OPENAI_API_KEY=your_api_key_here")
+        print("   Windows (PowerShell):")
+        print("   $env:OPENAI_API_KEY=\"your_api_key_here\"")
+    else:
+        print("   macOS/Linux:")
+        print("   export OPENAI_API_KEY=your_api_key_here")
+    
+    print("\n3. 可选配置:")
+    print("   • 自定义API基础URL (如果使用代理或其他OpenAI兼容服务):")
+    if sys.platform.startswith('win'):
+        print("     set OPENAI_BASE_URL=https://your-proxy.com/v1")
+    else:
+        print("     export OPENAI_BASE_URL=https://your-proxy.com/v1")
+    
+    print("   • 自定义模型 (默认: gpt-4o-mini):")
+    if sys.platform.startswith('win'):
+        print("     set OPENAI_MODEL=gpt-3.5-turbo")
+    else:
+        print("     export OPENAI_MODEL=gpt-3.5-turbo")
+    
+    print("\n4. 重启应用:")
+    print("   python app.py")
+
+
+def show_cost_info():
+    """显示费用信息"""
+    print("\n💰 OpenAI API 费用说明")
+    print("=" * 30)
+    print("• gpt-4o-mini (推荐):")
+    print("  - 输入: $0.15/1M tokens")
+    print("  - 输出: $0.60/1M tokens")
+    print("• gpt-3.5-turbo:")
+    print("  - 输入: $0.50/1M tokens")
+    print("  - 输出: $1.50/1M tokens")
+    print("• gpt-4:")
+    print("  - 输入: $30.00/1M tokens")
+    print("  - 输出: $60.00/1M tokens")
+    
+    print("\n📊 预估使用量:")
+    print("• 每次challenge评分查询: ~100-200 tokens")
+    print("• 每次计划生成: ~200-300 tokens")
+    print("• 预计每1000次查询成本: $0.02-0.10 (使用gpt-4o-mini)")
+
+
+def show_troubleshooting():
+    """显示故障排除指南"""
+    print("\n🔧 故障排除")
+    print("=" * 20)
+    print("如果遇到问题:")
+    print("1. 确认API key正确设置且有效")
+    print("2. 检查网络连接")
+    print("3. 确认OpenAI账户有足够余额")
+    print("4. 如果使用代理，确认OPENAI_BASE_URL正确")
+    print("5. 查看应用日志中的详细错误信息")
+
+
+def create_env_file():
+    """创建.env文件示例"""
+    env_content = """# OpenAI API Configuration
+# 在此处设置您的OpenAI API Key
+OPENAI_API_KEY=your_api_key_here
+
+# 可选: 自定义API基础URL (用于代理或其他兼容服务)
+# OPENAI_BASE_URL=https://api.openai.com/v1
+
+# 可选: 自定义模型 (默认: gpt-4o-mini)
+# OPENAI_MODEL=gpt-4o-mini
+"""
+    
+    try:
+        with open('.env.example', 'w', encoding='utf-8') as f:
+            f.write(env_content)
+        print("✅ 已创建 .env.example 文件")
+        print("   请复制为 .env 并填入您的API key")
+    except Exception as e:
+        print(f"❌ 创建 .env.example 失败: {e}")
+
+
+def main():
+    print("🤖 AI Agent - OpenAI API 配置助手")
+    print("=" * 50)
+    
+    # 检查当前配置
+    has_api_key = check_openai_config()
+    
+    if has_api_key:
+        print("\n✅ OpenAI API 已配置完成!")
+        print("您可以直接运行应用: python app.py")
+    else:
+        print("\n❌ OpenAI API 未配置")
+        show_setup_guide()
+    
+    # 显示费用信息
+    show_cost_info()
+    
+    # 创建环境文件示例
+    print("\n📝 创建配置文件示例")
+    print("-" * 30)
+    create_env_file()
+    
+    # 显示故障排除
+    show_troubleshooting()
+    
+    print("\n" + "=" * 50)
+    print("配置完成后，请运行: python app.py")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    main()

spec.md

@@ -0,0 +1,225 @@
+Challenge Overview
+Welcome to the Learn AI Challenge series! Your mission is to explore AI and the Model Context Protocol (MCP) by building an innovative AI Agent application that leverages the Topcoder MCP server.
+
+The agent can take many forms—chatbot, automation tool, research assistant, code generator, data visualization tool, or something entirely unique.
+
+You are free to use open-source agents or develop your own from scratch. The only requirement is that the agent must utilize the Topcoder MCP server and deliver a meaningful, user-friendly experience through the server's tools and resources.
+
+This is your opportunity to learn, innovate, and demonstrate your creativity and engineering expertise using cutting-edge AI technologies—plus earn rewards and community recognition.
+
+Challenge Incentives
+Top 10 winners will receive cash prizes.
+Winners and top submissions will be awarded an "AI Explorer" badge on their Topcoder profiles.
+Selected high-quality submissions will be featured on the Topcoder Hugging Face organization page, providing recognition and exposure to the broader AI community.
+Challenge Details
+Technology Focus: Development of AI Agents using the Model Context Protocol (MCP)
+Submission Duration: 21 days
+Agent Type: Any form of intelligent application is allowed—such as chatbots, virtual assistants, research tools, code generators, or data visualization agents.
+Creativity: Participants are encouraged to push boundaries and design original, inventive AI applications.
+Functionality: The AI agent must address a clearly defined problem or purpose and deliver impactful, practical results.
+Implementation Requirements:
+
+The AI agent must be designed to run within a Hugging Face Space.
+You can use any SDK or programming language, as long as it functions correctly in the Hugging Face Space environment.
+The agent must run smoothly on the default free-tier hardware (CPU Basic) provided by Hugging Face—no GPU usage required.
+It must connect to and interact with the Topcoder MCP server and deliver clear, purposeful results through an intuitive and user-friendly interface.
+Submission Requirements
+A fully functional AI Agent application, either as a downloadable codebase (zip file) or a publicly accessible Hugging Face Space link—or both.
+The submission must be based on a clearly defined use case that addresses a specific problem. Participants should also include a simple, clear document (as part of the submission) that outlines the problem being solved, the rationale behind the chosen use case, and how the AI agent addresses it. This clarity should also be reflected in the agent’s implementation and user experience.
+Accompanying documentation that clearly explains how to deploy, configure, and run the AI agent on Hugging Face Spaces.
+An optional demo video (up to 5 minutes) showcasing the agent’s core functionality and how it addresses the defined use case.
+What You Will Learn
+By participating in this challenge, you will:
+
+Gain a practical understanding of AI agent architecture, development workflows, and prompt engineering techniques.
+Strengthen your hands-on skills using technologies such as TypeScript, Python, JSON, APIs, and Gradio in real-world scenarios.
+Learn to build, integrate, and test AI applications using the Model Context Protocol (MCP) server provided by Topcoder.
+Develop proficiency in working with data ingestion, backend logic, and designing clear and effective user experiences (UI/UX) for AI tools.
+Learn how to prepare, optimize, and deploy your application to Hugging Face Spaces using their CPU Basic environment.
+Improve your ability to define clear use cases, articulate the problem your solution addresses, and communicate that effectively through documentation and demonstration.
+Engage with the broader Topcoder AI community to gain visibility, collect feedback, and earn recognition through badges, publications, or prizes.
+Build portfolio-worthy work that demonstrates your ability to solve meaningful problems using modern AI tools.
+Learning Path & Plan
+This 3-week challenge is structured as a guided learning journey. Below is a comprehensive, curriculum-style blueprint divided into modules, each with a clear objective, tasks, and deliverables. This will help you progress from beginner to deployer by the end of the challenge.
+
+Module 1: Foundations of AI Agents & MCP (Days 1–2)
+Objective: Understand the core principles of AI agents and how the Model Context Protocol (MCP) enables real-world AI integration.
+
+What are AI agents? (Examples: chatbots, automation tools, assistants, research agents)
+
+Core capabilities of agents: statefulness, prompt context, responsiveness, and output generation
+
+Overview of the Model Context Protocol (MCP) and how it facilitates structured communication between users and AI models
+
+Learn about transports like SSE and Streamable HTTP used by MCP
+
+Understand how MCP connects to Topcoder’s public APIs and what kind of tools/data you can access
+
+Recommended Course: Model Context Protocol (MCP) Course by Hugging Face
+
+Covers how to build MCP clients
+Shows integration with Gradio
+Includes code walkthroughs, examples, and deployment steps
+Deliverable: Written summary explaining:
+
+The type of AI agent you want to build
+How MCP can be used in that context
+Module 2: Development Environment Setup (Days 1–2)
+Objective: Get your local environment ready to build, test, and run MCP-powered AI agents.
+
+Install and configure a suitable IDE (e.g., VSCode, Cursor)
+Set up the Topcoder MCP server endpoint (
+https://api.topcoder-dev.com/v6/mcp/mcp
+) in your IDE’s
+settings.json
+Install relevant SDKs and dependencies (e.g., TypeScript, Python, Gradio, Node.js, etc.)
+Use the MCP Inspector to validate server connection and test a basic query
+Recommended Resources:
+
+Gradio Getting Started Guide (with code examples and UI integrations)
+VSCode Official Setup Instructions, Cursor Editor (AI-powered IDE)
+Topcoder MCP Inspector GitHub
+Deliverable:
+
+A working development environment
+Screenshot or confirmation of successful test interaction with MCP server using MCP Inspector
+Module 3: Exploring MCP Server Capabilities (Days 1–2)
+Objective: Learn how to explore the Topcoder MCP server, understand available tools and data, and identify what can power your agent.
+
+Understand the difference between SSE and Streamable HTTP transports in MCP.
+Launch the MCP Inspector and connect it to the Topcoder MCP endpoint (
+https://api.topcoder-dev.com/v6/mcp
+).
+Explore the public tools and resources available via the server.
+Review example requests and responses, and document the ones relevant to your intended use case.
+Determine the input and output formats for at least one useful endpoint.
+Recommended Resources:
+
+Topcoder MCP Inspector GitHub
+SSE and HTTP Streaming - MDN Reference
+Deliverable:
+
+A table listing at least 3 MCP tools or endpoints with their purpose, input, and expected output
+Screenshots or logs of actual request/response payloads from the MCP Inspector
+Module 4: Refine the Use Case & Design the Agent (Days 1–2)
+Objective: Revisit your original agent idea after exploring the Topcoder MCP server and finalize a well-defined use case and experience flow.
+
+Reflect on your initial idea from Module 1 in light of the MCP tools and data you've explored
+Validate whether the original use case still makes sense or needs to be adapted
+Clearly define:
+The real-world problem you're solving
+Why it's meaningful
+How your agent will solve it using one or more MCP tools
+Create a user journey flow, wireframe, or basic mockup to visualize how users will interact with your agent
+Deliverable:
+
+Finalized use case document with:
+Problem definition
+Target user or audience
+Description of solution and value proposition
+MCP tools or endpoints your agent will use
+UX mockup or user journey diagram that reflects the agent's intended experience. You can use v0.dev to quickly generate visually appealing mockups with the help of AI.
+Module 5: Building Agent Logic & MCP Integration (Days 2–3)
+Objective: Implement the core logic of your agent to communicate effectively with the Topcoder MCP server, retrieve data, and generate intelligent outputs.
+
+Set up your project structure using a preferred language (Python, TypeScript, etc.)
+Choose your connection method (SSE or Streamable HTTP) and implement a request handler for MCP
+Integrate the MCP endpoint(s) you selected in Module 3
+Process incoming data and prepare meaningful responses
+Apply prompt engineering principles to enhance agent output quality
+Ensure your logic runs efficiently on Hugging Face CPU Basic (no GPU dependencies)
+Recommended Resources:
+
+Prompt Engineering Guide
+Example backend agent using Python with SSE + Hugging Face: MCP Agent Boilerplate (Python)
+Demonstrates how to:
+Connect to Topcoder MCP using SSE
+Build an async backend agent using FastAPI
+Deploy to Hugging Face with CPU basic config
+This is ideal if you're building a backend-only agent with no frontend SDK involved.
+EventSource API Reference: MDN Docs Guide](https://github.com/dair-ai/Prompt-Engineering-Guide)
+Example SSE integration (React or Node): MDN EventSource Docs
+Deliverable:
+
+A backend agent logic module that:
+Successfully connects to and queries the MCP server
+Returns usable responses to the frontend
+Demonstrates use of at least one real MCP tool or endpoint
+A brief explanation (in your README) of how the MCP connection is implemented and which tools it uses
+Module 6: UI/UX Development (Days 2–3)
+Objective: Create an accessible, intuitive interface to showcase your AI agent’s capabilities.
+
+Choose a simple UI framework such as Gradio, Streamlit, or a minimal HTML/JS frontend (Gradio recommended for ease of Hugging Face integration)
+Link the UI to your backend logic (built in Module 5)
+Focus on making input fields and output displays clear and accessible
+Provide contextual labels, input placeholders, and output formatting where helpful
+Consider adding a loading indicator or progress feedback if MCP requests take time
+Deliverable: A lightweight, working UI prototype that allows users to interact with your agent and see live responses from the MCP server
+
+Module 7: End-to-End Testing & Debugging (Days 1–2)
+Objective: Ensure your agent is production-ready through comprehensive testing and optimization.
+
+Perform full end-to-end testing: UI → backend → MCP → backend → UI
+Simulate real user interactions and input variations
+Identify and handle edge cases, unexpected input, and communication errors (e.g., timeouts, SSE disconnects)
+Add fallback behavior or helpful messages for errors
+Profile and optimize response time, agent feedback, and loading states
+Deliverable: A stable, polished, and bug-free agent that reliably handles diverse inputs and edge scenarios
+
+Module 8: Deployment on Hugging Face Spaces (Days 1–2)
+Objective: Deploy your agent to a live environment and ensure it's accessible and stable.
+
+Prepare
+requirements.txt
+and
+README.md
+with necessary dependencies and setup instructions
+Push your project to a new or existing Hugging Face Space
+Confirm successful deployment on the default CPU Basic hardware (no GPU)
+Perform smoke testing to validate end-to-end functionality
+Deliverable: A fully deployed Hugging Face Space (public link) or a repository that’s ready to be deployed without additional changes
+
+Module 9: Documentation & Demo (Days 1–2)
+Objective: Ensure your project is easy to understand, use, and present.
+
+Create a well-structured README that includes setup instructions, usage examples, and technical details
+Clearly articulate the use case and the problem your agent addresses
+(Optional) Record a 3–5 minute demo video walking through how your agent works
+Deliverable: Comprehensive documentation with an optional demo video
+
+Module 10: Final Packaging & Submission (Day 1)
+Objective: Finalize and submit your agent project with all required materials.
+
+Package your project as a zip file or provide a live public link (e.g., Hugging Face Space)
+Carefully review the challenge submission checklist to ensure everything is included
+Submit your entry via the challenge platform before the deadline
+Deliverable: A complete submission package that meets all criteria and is ready for judging
+
+The Topcoder MCP Server
+The Model Context Protocol (MCP) server provided by Topcoder is hosted at: https://api.topcoder-dev.com/v6/mcp.
+
+It supports two transport mechanisms for agent communication:
+
+Server-Sent Events (SSE): https://api.topcoder-dev.com/v6/mcp/sse
+Streamable HTTP: https://api.topcoder-dev.com/v6/mcp/mcp
+Your agent must use one of these transports to interact with the MCP server.
+No authentication is currently required—your agent can connect and send requests without needing a token.
+The server exposes publicly available data and tools sourced from the Topcoder APIs. In future updates, we may introduce authenticated features and enhanced tools that require login or user tokens.
+
+Review & Evaluation
+We will review submissions on an iterative basis. After completing each module, please upload your work (e.g., Document, link to GitHub repo, Hugging Face Space, or zipped files) and notify the challenge copilot by email, the copilot will reivew and share feedback over email.
+
+You will typically receive feedback within 1–2 days, helping you improve and refine your work before progressing.
+
+This optional collaborative review process ensures you stay on track and gives you the best chance of submitting a high-quality agent by the end.
+
+Final Evaluation Criteria
+Your final submission will be judged based on the following:
+
+Functionality & Stability (30%) – Does the agent work as intended across different inputs and edge cases?
+Use Case Relevance (20%) – How clearly defined and meaningful is the problem the agent addresses?
+MCP Integration (20%) – How effectively does the agent leverage the Topcoder MCP tools and transports?
+User Experience & Interface (15%) – Is the UI intuitive, responsive, and polished?
+Documentation & Demo (10%) – Is the README clear? Does the optional video explain the agent effectively?
+Originality & Creativity (5%) – Is the idea novel or uniquely executed?
+High-scoring submissions typically demonstrate smooth functionality, a clear purpose, practical use of MCP tools, and thoughtful design.

test_openai.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+Test OpenAI integration
+"""
+
+import os
+import json
+from openai import OpenAI
+
+
+def test_openai_connection():
+    """Test basic OpenAI connection"""
+    api_key = os.getenv("OPENAI_API_KEY")
+    base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    
+    if not api_key:
+        print("❌ 请先设置 OPENAI_API_KEY 环境变量")
+        print("   export OPENAI_API_KEY=your_api_key_here")
+        return False
+    
+    try:
+        client = OpenAI(
+            api_key=api_key,
+            base_url=base_url
+        )
+        
+        print(f"🔗 连接到: {base_url}")
+        print(f"🔑 API Key: {api_key[:4]}...{api_key[-4:]}")
+        
+        # 测试简单的聊天完成
+        response = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
+            messages=[
+                {"role": "user", "content": "Hello! Please respond with just 'OK' to confirm the connection."}
+            ],
+            max_tokens=10,
+            temperature=0
+        )
+        
+        result = response.choices[0].message.content.strip()
+        print(f"✅ 连接成功! 响应: {result}")
+        
+        return True
+        
+    except Exception as e:
+        print(f"❌ 连接失败: {e}")
+        return False
+
+
+def test_scoring_function():
+    """Test the scoring functionality similar to what's used in app.py"""
+    api_key = os.getenv("OPENAI_API_KEY")
+    
+    if not api_key:
+        print("❌ 请先设置 OPENAI_API_KEY 环境变量")
+        return False
+    
+    try:
+        client = OpenAI(
+            api_key=api_key,
+            base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+        )
+        
+        # 测试数据，类似app.py中的格式
+        test_challenges = [
+            {
+                "id": "test1",
+                "title": "Build a Python Web API",
+                "prize": 500.0,
+                "deadline": "2025-02-15",
+                "tags": ["python", "api", "web"],
+                "description": "Create a REST API using Python and FastAPI framework"
+            },
+            {
+                "id": "test2", 
+                "title": "React Frontend Development",
+                "prize": 300.0,
+                "deadline": "2025-02-20",
+                "tags": ["react", "frontend", "javascript"],
+                "description": "Build a modern React application with responsive design"
+            }
+        ]
+        
+        scoring_prompt = (
+            "You are an expert Topcoder challenge analyst. Analyze items and rate match to the query.\n"
+            f"Query: python web development\n"
+            "Items: " + json.dumps(test_challenges) + "\n\n"
+            "Instructions:\n"
+            "- Consider skills, tags, and brief description.\n"
+            "- Higher prize is slightly better all else equal.\n"
+            "- Return ONLY JSON array of objects: [{id, score, reason}] where 0<=score<=1.\n"
+            "- Do not include any extra text."
+        )
+        
+        print("🧪 测试智能评分功能...")
+        
+        response = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
+            messages=[
+                {"role": "system", "content": "You are a helpful assistant. Return JSON only."},
+                {"role": "user", "content": scoring_prompt}
+            ],
+            temperature=0.2,
+            timeout=30
+        )
+        
+        result = response.choices[0].message.content.strip()
+        print(f"📊 评分结果: {result}")
+        
+        # 尝试解析JSON
+        try:
+            scores = json.loads(result)
+            print("✅ JSON解析成功!")
+            for item in scores:
+                print(f"   - {item.get('id')}: 分数={item.get('score')}, 原因={item.get('reason')}")
+            return True
+        except json.JSONDecodeError as e:
+            print(f"❌ JSON解析失败: {e}")
+            return False
+            
+    except Exception as e:
+        print(f"❌ 评分测试失败: {e}")
+        return False
+
+
+def test_planning_function():
+    """Test the planning functionality"""
+    api_key = os.getenv("OPENAI_API_KEY")
+    
+    if not api_key:
+        print("❌ 请先设置 OPENAI_API_KEY 环境变量")
+        return False
+    
+    try:
+        client = OpenAI(
+            api_key=api_key,
+            base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+        )
+        
+        # 测试数据
+        test_challenges = [
+            {
+                "title": "Build a Python Web API",
+                "prize": 500.0,
+                "deadline": "2025-02-15",
+                "tags": ["python", "api", "web"]
+            }
+        ]
+        
+        prompt = (
+            "You are a concise challenge scout. Given compact challenge metadata, output:\n"
+            "- Top 3 picks (title + brief reason)\n"
+            "- Quick plan of action (3 bullets)\n"
+            f"Constraints: keyword='python', min_prize>=100, within 30 days.\n"
+            f"Data: {json.dumps(test_challenges)}"
+        )
+        
+        print("📋 测试计划生成功能...")
+        
+        response = client.chat.completions.create(
+            model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
+            messages=[
+                {"role": "system", "content": "You are a helpful, terse assistant."},
+                {"role": "user", "content": prompt}
+            ],
+            temperature=0.3,
+            timeout=30
+        )
+        
+        result = response.choices[0].message.content.strip()
+        print(f"📝 计划结果:\n{result}")
+        print("✅ 计划生成成功!")
+        
+        return True
+        
+    except Exception as e:
+        print(f"❌ 计划测试失败: {e}")
+        return False
+
+
+def main():
+    print("🤖 OpenAI API 集成测试")
+    print("=" * 40)
+    
+    # 测试基本连接
+    if not test_openai_connection():
+        print("\n❌ 基本连接测试失败，请检查配置")
+        return
+    
+    print("\n" + "-" * 40)
+    
+    # 测试评分功能
+    if not test_scoring_function():
+        print("❌ 评分功能测试失败")
+        return
+    
+    print("\n" + "-" * 40)
+    
+    # 测试计划功能
+    if not test_planning_function():
+        print("❌ 计划功能测试失败")
+        return
+    
+    print("\n" + "=" * 40)
+    print("🎉 所有测试通过! OpenAI集成工作正常")
+    print("现在可以运行主应用: python app.py")
+    print("=" * 40)
+
+
+if __name__ == "__main__":
+    main()