eightstatecli 0.4.0__py3-none-any.whl

escli/commands/search.py

@@ -0,0 +1,286 @@
+"""
+escli search / fetch — web search and URL extraction via Parallel.ai.
+
+Uses the free Parallel Search MCP endpoint (no API key required).
+Falls back to the REST API with a key from gate if available.
+
+Usage:
+  escli search "query about something"           Web search
+  escli search "query" --queries "q1" "q2"       Multiple search queries
+  escli fetch <url> [url2 ...]                   Extract content from URLs
+  escli fetch <url> --objective "what to find"   Focused extraction
+  escli fetch <url> --full                       Full page content
+"""
+
+import argparse
+import json
+import sys
+import time
+import uuid
+
+from ..services.credentials import get_key_for_service
+
+MCP_ENDPOINT = "https://search.parallel.ai/mcp"
+REST_ENDPOINT = "https://api.parallel.ai/v1"
+
+
+def _session_id() -> str:
+    """Stable session ID for rate limiting."""
+    return uuid.uuid4().hex
+
+
+def _call_mcp(tool_name: str, arguments: dict) -> dict:
+    """Call a tool on the Parallel MCP endpoint via JSON-RPC over HTTP."""
+    import httpx
+
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": tool_name,
+            "arguments": arguments,
+        },
+    }
+
+    resp = httpx.post(
+        MCP_ENDPOINT,
+        json=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        },
+        timeout=60,
+    )
+    resp.raise_for_status()
+
+    data = resp.json()
+    if "error" in data:
+        raise RuntimeError(data["error"].get("message", "MCP error"))
+
+    result = data.get("result", {})
+    # MCP tool results come as content array
+    content = result.get("content", [])
+    for item in content:
+        if item.get("type") == "text":
+            try:
+                return json.loads(item["text"])
+            except json.JSONDecodeError:
+                return {"text": item["text"]}
+
+    return result
+
+
+def _call_rest_search(objective: str, queries: list[str], api_key: str) -> dict:
+    """Call Parallel Search REST API directly."""
+    import httpx
+
+    resp = httpx.post(
+        f"{REST_ENDPOINT}/search",
+        json={"objective": objective, "search_queries": queries},
+        headers={"Content-Type": "application/json", "x-api-key": api_key},
+        timeout=60,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _call_rest_extract(urls: list[str], objective: str | None, full: bool, api_key: str) -> dict:
+    """Call Parallel Extract REST API directly."""
+    import httpx
+
+    body: dict = {"urls": urls}
+    if objective:
+        body["objective"] = objective
+    if full:
+        body["full_content"] = True
+
+    resp = httpx.post(
+        f"{REST_ENDPOINT}/extract",
+        json=body,
+        headers={"Content-Type": "application/json", "x-api-key": api_key},
+        timeout=60,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ── Commands ─────────────────────────────────────────────────────
+
+def cmd_search(args):
+    """Web search via Parallel."""
+    objective = " ".join(args.objective)
+    if not objective:
+        print("  ✗ search objective required", file=sys.stderr)
+        return 1
+
+    queries = args.queries if args.queries else [objective]
+    t0 = time.time()
+
+    if not args.quiet:
+        print(f"  ▸ searching: {objective}", file=sys.stderr)
+
+    # Try REST API with key first (better quality), fall back to MCP (free)
+    api_key = get_key_for_service("parallel", "PARALLEL_API_KEY")
+
+    try:
+        if api_key:
+            data = _call_rest_search(objective, queries, api_key)
+        else:
+            session = _session_id()
+            data = _call_mcp("web_search", {
+                "objective": objective,
+                "search_queries": queries,
+                "session_id": session,
+            })
+    except Exception as e:
+        if args.json:
+            print(json.dumps({"success": False, "error": str(e)}))
+        else:
+            print(f"  ✗ search failed: {e}", file=sys.stderr)
+        return 1
+
+    elapsed = round(time.time() - t0, 1)
+    results = data.get("results", [])
+
+    if args.json:
+        print(json.dumps({
+            "success": True,
+            "elapsed_seconds": elapsed,
+            "results": results,
+            "count": len(results),
+        }))
+        return 0
+
+    if not results:
+        print("  No results found.", file=sys.stderr)
+        return 0
+
+    for r in results:
+        title = r.get("title", "")
+        url = r.get("url", "")
+        excerpts = r.get("excerpts", [])
+
+        print(f"\n  {title}")
+        print(f"  {url}")
+        for ex in excerpts[:2]:
+            # Truncate long excerpts
+            text = ex.strip().replace("\n", " ")[:200]
+            print(f"    {text}")
+
+    if not args.quiet:
+        print(f"\n  {len(results)} results · {elapsed}s", file=sys.stderr)
+
+    return 0
+
+
+def cmd_fetch(args):
+    """Extract content from URLs via Parallel."""
+    urls = args.urls
+    if not urls:
+        print("  ✗ at least one URL required", file=sys.stderr)
+        return 1
+
+    objective = args.objective
+    full = getattr(args, "full", False)
+    t0 = time.time()
+
+    if not args.quiet:
+        print(f"  ▸ fetching {len(urls)} URL(s)...", file=sys.stderr)
+
+    api_key = get_key_for_service("parallel", "PARALLEL_API_KEY")
+
+    try:
+        if api_key:
+            data = _call_rest_extract(urls, objective, full, api_key)
+        else:
+            session = _session_id()
+            mcp_args: dict = {"urls": urls, "session_id": session}
+            if objective:
+                mcp_args["objective"] = objective
+            if full:
+                mcp_args["full_content"] = True
+            data = _call_mcp("web_fetch", mcp_args)
+    except Exception as e:
+        if args.json:
+            print(json.dumps({"success": False, "error": str(e)}))
+        else:
+            print(f"  ✗ fetch failed: {e}", file=sys.stderr)
+        return 1
+
+    elapsed = round(time.time() - t0, 1)
+    results = data.get("results", [])
+
+    if args.json:
+        print(json.dumps({
+            "success": True,
+            "elapsed_seconds": elapsed,
+            "results": results,
+            "count": len(results),
+        }))
+        return 0
+
+    for r in results:
+        title = r.get("title", "")
+        url = r.get("url", "")
+        full_content = r.get("full_content")
+        excerpts = r.get("excerpts", [])
+
+        if title:
+            print(f"\n  # {title}")
+        print(f"  {url}\n")
+
+        if full_content:
+            print(full_content)
+        else:
+            for ex in excerpts:
+                print(ex)
+                print()
+
+    if not args.quiet:
+        print(f"  {len(results)} page(s) · {elapsed}s", file=sys.stderr)
+
+    return 0
+
+
+# ── Parser ───────────────────────────────────────────────────────
+
+def register(subparsers):
+    """Register search and fetch subcommands."""
+    F = argparse.RawDescriptionHelpFormatter
+
+    # search
+    search_p = subparsers.add_parser(
+        "search", aliases=["s"], help="Web search (Parallel.ai)",
+        formatter_class=F,
+        epilog="""examples:
+  escli search "latest cloudflare workers features"
+  escli search "react server components" --queries "RSC tutorial" "RSC vs SSR"
+  escli --json search "python web frameworks 2026"
+
+Uses the free Parallel Search MCP. No API key needed.
+Add a Parallel API key for higher rate limits.
+""")
+    search_p.add_argument("objective", nargs="+", help="What you're searching for")
+    search_p.add_argument("--queries", nargs="+", default=None, metavar="Q",
+                          help="Specific search queries (default: uses objective)")
+    search_p.set_defaults(func=cmd_search)
+
+    # fetch
+    fetch_p = subparsers.add_parser(
+        "fetch", aliases=["f"], help="Extract URL content (Parallel.ai)",
+        formatter_class=F,
+        epilog="""examples:
+  escli fetch https://docs.parallel.ai/search/search-quickstart
+  escli fetch https://example.com --objective "pricing information"
+  escli fetch https://example.com --full
+  escli --json fetch https://example.com https://other.com
+
+Uses the free Parallel Extract MCP. No API key needed.
+""")
+    fetch_p.add_argument("urls", nargs="+", help="URLs to extract content from")
+    fetch_p.add_argument("--objective", default=None, help="Focus extraction on this topic")
+    fetch_p.add_argument("--full", action="store_true", help="Return full page content instead of excerpts")
+    fetch_p.set_defaults(func=cmd_fetch)
+
+    return search_p

escli/commands/social.py

@@ -0,0 +1,243 @@
+"""
+escli social — social media search via Tavily API.
+
+Searches across Reddit, X/Twitter, TikTok, LinkedIn, Instagram,
+Facebook, or all combined for real-world opinions and discussions.
+
+Usage:
+  escli social "query"                              Search all platforms
+  escli social "query" --platform reddit             Reddit only
+  escli social "query" --platform x,linkedin         Multiple platforms
+  escli social "query" --time week --raw             Last week, full content
+  escli social "query" --answer                      Include AI summary
+"""
+
+import argparse
+import json
+import sys
+import time
+
+from ..services.credentials import get_key_for_service
+
+TAVILY_API = "https://api.tavily.com"
+
+PLATFORM_DOMAINS = {
+    "reddit": ["reddit.com"],
+    "x": ["x.com", "twitter.com"],
+    "twitter": ["x.com", "twitter.com"],
+    "tiktok": ["tiktok.com"],
+    "linkedin": ["linkedin.com"],
+    "instagram": ["instagram.com"],
+    "facebook": ["facebook.com"],
+    "youtube": ["youtube.com"],
+    "combined": ["reddit.com", "x.com", "twitter.com", "tiktok.com",
+                 "linkedin.com", "instagram.com", "facebook.com"],
+}
+
+VALID_PLATFORMS = list(PLATFORM_DOMAINS.keys())
+VALID_TIME_RANGES = ["day", "week", "month", "year"]
+VALID_DEPTHS = ["basic", "advanced", "fast", "ultra-fast"]
+
+
+def _get_api_key() -> str:
+    key = get_key_for_service("tavily", "TAVILY_API_KEY")
+    if not key:
+        print("  ✗ no Tavily API key. Set TAVILY_API_KEY or add one via the dashboard.", file=sys.stderr)
+        sys.exit(1)
+    return key
+
+
+def _resolve_domains(platform_str: str | None) -> list[str]:
+    """Resolve platform string to domain list."""
+    if not platform_str:
+        return PLATFORM_DOMAINS["combined"]
+
+    domains = []
+    for p in platform_str.lower().split(","):
+        p = p.strip()
+        if p in PLATFORM_DOMAINS:
+            domains.extend(PLATFORM_DOMAINS[p])
+        else:
+            print(f"  ✗ unknown platform: {p}", file=sys.stderr)
+            print(f"  valid: {', '.join(VALID_PLATFORMS)}", file=sys.stderr)
+            sys.exit(2)
+
+    return list(dict.fromkeys(domains))  # dedupe preserving order
+
+
+def cmd_social(args):
+    """Search social media platforms."""
+    import httpx
+
+    api_key = _get_api_key()
+    query = " ".join(args.query)
+    if not query:
+        print("  ✗ search query required", file=sys.stderr)
+        return 1
+
+    platform = getattr(args, "platform", None)
+    domains = _resolve_domains(platform)
+    t0 = time.time()
+
+    if not args.quiet:
+        platform_label = platform or "all platforms"
+        print(f"  ▸ searching {platform_label}: {query}", file=sys.stderr)
+
+    # Build request
+    body: dict = {
+        "query": query,
+        "include_domains": domains,
+        "max_results": getattr(args, "max_results", 10) or 10,
+        "search_depth": getattr(args, "depth", "advanced") or "advanced",
+        "include_answer": getattr(args, "answer", False),
+        "include_raw_content": getattr(args, "raw", False),
+        "include_images": getattr(args, "images", False),
+        "include_usage": True,
+    }
+
+    time_range = getattr(args, "time", None)
+    if time_range:
+        body["time_range"] = time_range
+
+    country = getattr(args, "country", None)
+    if country:
+        body["country"] = country
+
+    try:
+        resp = httpx.post(
+            f"{TAVILY_API}/search",
+            json=body,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+    except httpx.HTTPStatusError as e:
+        error_msg = str(e)
+        try:
+            error_msg = e.response.json().get("detail", {}).get("error", str(e))
+        except Exception:
+            pass
+        if args.json:
+            print(json.dumps({"ok": False, "data": None, "error": {"code": f"tavily.{e.response.status_code}", "message": error_msg}, "meta": {}}))
+        else:
+            print(f"  ✗ {error_msg}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        if args.json:
+            print(json.dumps({"ok": False, "data": None, "error": {"code": "tavily.network", "message": str(e), "retryable": True}, "meta": {}}))
+        else:
+            print(f"  ✗ {e}", file=sys.stderr)
+        return 1
+
+    elapsed = round(time.time() - t0, 1)
+    results = data.get("results", [])
+    answer = data.get("answer")
+
+    if args.json:
+        print(json.dumps({
+            "ok": True,
+            "data": {
+                "answer": answer,
+                "results": [{
+                    "title": r.get("title", ""),
+                    "url": r.get("url", ""),
+                    "content": r.get("content", ""),
+                    "score": r.get("score"),
+                    "raw_content": r.get("raw_content") if getattr(args, "raw", False) else None,
+                } for r in results],
+                "platform": platform or "combined",
+                "query": query,
+            },
+            "error": None,
+            "meta": {
+                "elapsed_seconds": elapsed,
+                "result_count": len(results),
+                "credits": data.get("usage", {}).get("credits"),
+            },
+        }))
+        return 0
+
+    # Human output
+    if answer:
+        print(f"\n  {answer}\n")
+
+    for r in results:
+        title = r.get("title", "")
+        url = r.get("url", "")
+        content = r.get("content", "")
+        score = r.get("score", 0)
+
+        # Detect platform from URL
+        platform_tag = ""
+        for p, doms in PLATFORM_DOMAINS.items():
+            if p in ("combined", "twitter"):
+                continue
+            if any(d in url for d in doms):
+                platform_tag = p
+                break
+
+        print(f"  {f'[{platform_tag}] ' if platform_tag else ''}{title}")
+        print(f"  {url}")
+        if content:
+            text = content.strip().replace("\n", " ")[:200]
+            print(f"    {text}")
+        print()
+
+    if not args.quiet:
+        credits = data.get("usage", {}).get("credits", "?")
+        print(f"  {len(results)} results · {elapsed}s · {credits} credit(s)", file=sys.stderr)
+
+    return 0
+
+
+# ── Parser ───────────────────────────────────────────────────────
+
+def register(subparsers):
+    """Register the social subcommand."""
+    F = argparse.RawDescriptionHelpFormatter
+
+    p = subparsers.add_parser(
+        "social", help="Social media search (Tavily)",
+        formatter_class=F,
+        epilog="""platforms:
+  reddit, x, tiktok, linkedin, instagram, facebook, youtube, combined (default)
+
+examples:
+  escli social "what are people saying about Claude Code"
+  escli social "AI trends 2026" --platform reddit
+  escli social "product reviews" --platform tiktok,instagram --time week
+  escli social "company sentiment" --platform linkedin,x --answer
+  escli social "breaking news" --platform x --time day --raw --max-results 15
+  escli --json --quiet social "brand perception" --platform reddit,x
+
+time ranges:
+  day     Last 24 hours (breaking news, reactions)
+  week    Last 7 days
+  month   Last 30 days (broader trends)
+  year    Last 12 months
+""")
+
+    p.add_argument("query", nargs="+", help="What to search for on social media")
+    p.add_argument("--platform", "-p", default=None, metavar="P",
+                   help=f"Platform(s) to search, comma-separated ({', '.join(VALID_PLATFORMS)})")
+    p.add_argument("--time", "-t", default=None, choices=VALID_TIME_RANGES, metavar="T",
+                   help="Time range: day, week, month, year")
+    p.add_argument("--max-results", "-n", type=int, default=10, metavar="N",
+                   help="Max results (1-20, default: 10)")
+    p.add_argument("--depth", default="advanced", choices=VALID_DEPTHS,
+                   help="Search depth (default: advanced)")
+    p.add_argument("--answer", "-a", action="store_true",
+                   help="Include AI-synthesized answer")
+    p.add_argument("--raw", action="store_true",
+                   help="Include full post content (raw markdown)")
+    p.add_argument("--images", action="store_true",
+                   help="Include images from results")
+    p.add_argument("--country", default=None, metavar="CC",
+                   help="Country for geo-targeted results (e.g. 'united states')")
+    p.set_defaults(func=cmd_social)
+
+    return p