scenario-navigator 0.1.0__tar.gz

scenario_navigator-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+dist/
+*.egg-info/

scenario_navigator-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: scenario-navigator
+Version: 0.1.0
+Summary: Official Python SDK for the Scenario Navigator API — news scenario in, ranked stock impact out.
+Project-URL: Homepage, https://scenarionavigator.io
+Project-URL: Documentation, https://scenarionavigator.io/docs
+Author-email: Scenario Navigator <partners@scenarionavigator.io>
+License: MIT
+Keywords: api,finance,llm,news,stocks
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# scenario-navigator
+
+Official Python SDK for the [Scenario Navigator API](https://scenarionavigator.io) — news scenario in, ranked stock impact out.
+
+## Install
+
+```bash
+pip install scenario-navigator
+```
+
+## Quickstart (no signup)
+
+```python
+from scenario_navigator_sdk import Client
+
+client = Client.with_trial_token()          # free 1-hour trial key
+analysis = client.analyze("OPEC announces a surprise 2M barrel production cut")
+
+for stock in analysis.benefiting:
+    print(stock.stock, stock.confidence, "—", stock.reason)
+```
+
+With a partner key: `Client(api_key="sn_live_...")`.
+
+## Depths
+
+| depth | latency | notes |
+|---|---|---|
+| `instant` | seconds | synchronous, no web search, confidence caps at `medium`, `preliminary=True` |
+| `fast` (default) | ~1 min | full ensemble with live web search |
+| `deep` | 2–3 min | deepest research pass |
+
+```python
+quick = client.analyze("Fed cuts rates 50bps", depth="instant")
+deep  = client.analyze("Fed cuts rates 50bps", depth="deep", timeout=400)
+```
+
+## The instant read path: the feed
+
+Trending market scenarios are pre-analyzed around the clock — no submission, <100ms:
+
+```python
+feed = client.feed(limit=10, include_analysis=True)
+for item in feed["items"]:
+    print(item["text"], item["analysis"])
+```
+
+## Webhooks
+
+```python
+hook = client.create_webhook("https://example.com/sn-webhook")
+print(hook["secret"])  # shown once — store it
+
+# In your webhook handler:
+from scenario_navigator_sdk import verify_webhook_signature
+ok = verify_webhook_signature(request_body_bytes,
+                              request.headers["X-SN-Signature"],
+                              secret=hook["secret"])
+```
+
+## Account
+
+```python
+client.usage()        # today / month-to-date / 30-day series + your limits
+client.rotate_key()   # new key returned; old key lives 24h
+```
+
+## MCP server (AI agents)
+
+```bash
+pip install "scenario-navigator[mcp]"
+SCEN_NAV_TOKEN=sn_live_... python -m scenario_navigator_sdk.mcp_server
+```
+
+Exposes `analyze_scenario` and `trending_scenarios` tools over MCP stdio.
+
+## Errors
+
+All failures raise `ApiError` with `status_code`, `code` (e.g. `rate_limited`,
+`quota_exceeded`), and `request_id` — include the `request_id` in support requests.

scenario_navigator-0.1.0/README.md

@@ -0,0 +1,80 @@
+# scenario-navigator
+
+Official Python SDK for the [Scenario Navigator API](https://scenarionavigator.io) — news scenario in, ranked stock impact out.
+
+## Install
+
+```bash
+pip install scenario-navigator
+```
+
+## Quickstart (no signup)
+
+```python
+from scenario_navigator_sdk import Client
+
+client = Client.with_trial_token()          # free 1-hour trial key
+analysis = client.analyze("OPEC announces a surprise 2M barrel production cut")
+
+for stock in analysis.benefiting:
+    print(stock.stock, stock.confidence, "—", stock.reason)
+```
+
+With a partner key: `Client(api_key="sn_live_...")`.
+
+## Depths
+
+| depth | latency | notes |
+|---|---|---|
+| `instant` | seconds | synchronous, no web search, confidence caps at `medium`, `preliminary=True` |
+| `fast` (default) | ~1 min | full ensemble with live web search |
+| `deep` | 2–3 min | deepest research pass |
+
+```python
+quick = client.analyze("Fed cuts rates 50bps", depth="instant")
+deep  = client.analyze("Fed cuts rates 50bps", depth="deep", timeout=400)
+```
+
+## The instant read path: the feed
+
+Trending market scenarios are pre-analyzed around the clock — no submission, <100ms:
+
+```python
+feed = client.feed(limit=10, include_analysis=True)
+for item in feed["items"]:
+    print(item["text"], item["analysis"])
+```
+
+## Webhooks
+
+```python
+hook = client.create_webhook("https://example.com/sn-webhook")
+print(hook["secret"])  # shown once — store it
+
+# In your webhook handler:
+from scenario_navigator_sdk import verify_webhook_signature
+ok = verify_webhook_signature(request_body_bytes,
+                              request.headers["X-SN-Signature"],
+                              secret=hook["secret"])
+```
+
+## Account
+
+```python
+client.usage()        # today / month-to-date / 30-day series + your limits
+client.rotate_key()   # new key returned; old key lives 24h
+```
+
+## MCP server (AI agents)
+
+```bash
+pip install "scenario-navigator[mcp]"
+SCEN_NAV_TOKEN=sn_live_... python -m scenario_navigator_sdk.mcp_server
+```
+
+Exposes `analyze_scenario` and `trending_scenarios` tools over MCP stdio.
+
+## Errors
+
+All failures raise `ApiError` with `status_code`, `code` (e.g. `rate_limited`,
+`quota_exceeded`), and `request_id` — include the `request_id` in support requests.

scenario_navigator-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scenario-navigator"
+version = "0.1.0"
+description = "Official Python SDK for the Scenario Navigator API — news scenario in, ranked stock impact out."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Scenario Navigator", email = "partners@scenarionavigator.io" }]
+dependencies = ["requests>=2.28"]
+keywords = ["finance", "stocks", "news", "llm", "api"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+
+[project.urls]
+Homepage = "https://scenarionavigator.io"
+Documentation = "https://scenarionavigator.io/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["scenario_navigator_sdk"]

scenario_navigator-0.1.0/scenario_navigator_sdk/__init__.py

@@ -0,0 +1,253 @@
+"""Scenario Navigator Python SDK.
+
+    from scenario_navigator_sdk import Client
+
+    client = Client(api_key="sn_live_...")          # or a trial token
+    analysis = client.analyze("OPEC announces a surprise 2M barrel cut")
+    for stock in analysis.benefiting:
+        print(stock.stock, stock.confidence, stock.reason)
+
+No key yet? ``Client.with_trial_token()`` mints a free 1-hour trial key.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import requests
+
+__all__ = [
+    "Client",
+    "Analysis",
+    "Stock",
+    "ApiError",
+    "verify_webhook_signature",
+]
+
+DEFAULT_BASE_URL = "https://api.scenarionavigator.io"
+
+
+class ApiError(Exception):
+    """API returned an error. Carries status_code, code, and request_id."""
+
+    def __init__(self, status_code: int, detail: Any, code: str = "error",
+                 request_id: Optional[str] = None):
+        self.status_code = status_code
+        self.detail = detail
+        self.code = code
+        self.request_id = request_id
+        super().__init__(f"[{status_code} {code}] {detail} (request_id={request_id})")
+
+
+@dataclass
+class Stock:
+    stock: str
+    name: Optional[str] = None
+    reason: Optional[str] = None
+    confidence: str = "low"  # high | medium | low
+
+
+@dataclass
+class Analysis:
+    benefiting: List[Stock] = field(default_factory=list)
+    hurting: List[Stock] = field(default_factory=list)
+    depth: Optional[str] = None
+    preliminary: bool = False
+    slug: Optional[str] = None
+    scenario_id: Optional[str] = None
+    job_id: Optional[str] = None
+
+    @classmethod
+    def _from_results(cls, results: Dict[str, Any], **extra) -> "Analysis":
+        def stocks(items):
+            return [
+                Stock(
+                    stock=i.get("stock", ""),
+                    name=i.get("name"),
+                    reason=i.get("reason"),
+                    confidence=i.get("confidence", "low"),
+                )
+                for i in (items or [])
+            ]
+
+        return cls(
+            benefiting=stocks(results.get("benefiting")),
+            hurting=stocks(results.get("hurting")),
+            **extra,
+        )
+
+
+class Client:
+    """Synchronous client for the Scenario Navigator public API."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0, session: Optional[requests.Session] = None):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+
+    # ------------------------------------------------------------------ util
+    @classmethod
+    def with_trial_token(cls, base_url: str = DEFAULT_BASE_URL) -> "Client":
+        """Mint a free trial key (1 hour, limited runs) and return a Client."""
+        resp = requests.post(f"{base_url.rstrip('/')}/api/public/v1/trial-token",
+                             timeout=15)
+        if resp.status_code != 200:
+            raise ApiError(resp.status_code, resp.text)
+        return cls(resp.json()["token"], base_url=base_url)
+
+    def _request(self, method: str, path: str, **kwargs) -> Dict[str, Any]:
+        headers = kwargs.pop("headers", {})
+        headers.setdefault("Authorization", f"Bearer {self.api_key}")
+        # allow_redirects=False: the API's duplicate-scenario 303 must reach
+        # this handler, not be silently followed as a GET by requests.
+        resp = self._session.request(
+            method, f"{self.base_url}{path}", headers=headers,
+            timeout=self.timeout, allow_redirects=False, **kwargs,
+        )
+        if resp.status_code == 303:
+            # Duplicate scenario — surface the existing slug.
+            location = resp.headers.get("Location", "")
+            raise ApiError(303, f"Duplicate scenario: {location}", code="duplicate")
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {"detail": resp.text}
+        if resp.status_code >= 400:
+            err = body.get("error", {}) if isinstance(body, dict) else {}
+            raise ApiError(
+                resp.status_code,
+                body.get("detail") if isinstance(body, dict) else body,
+                code=err.get("code", "error"),
+                request_id=err.get("request_id"),
+            )
+        return body
+
+    # ------------------------------------------------------------- analysis
+    def analyze(self, text: str, depth: str = "fast", *, wait: bool = True,
+                timeout: float = 300.0, poll_interval: float = 3.0,
+                visibility: Optional[str] = None,
+                idempotency_key: Optional[str] = None) -> Analysis:
+        """Submit a scenario. depth: "instant" (sync, seconds), "fast", "deep".
+
+        With wait=True (default) the async depths poll until completion and
+        return the finished Analysis. With wait=False, returns an Analysis
+        carrying only job_id/slug/scenario_id — poll with get_job().
+        """
+        payload: Dict[str, Any] = {"text": text, "depth": depth}
+        if visibility:
+            payload["visibility"] = visibility
+        headers = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        try:
+            body = self._request("POST", "/api/public/v1/scenarios",
+                                 json=payload, headers=headers)
+        except ApiError as exc:
+            if exc.code != "duplicate":
+                raise
+            # Duplicate: the Location points at the existing scenario —
+            # return its saved analysis instead of failing.
+            slug = str(exc.detail).rstrip("/").rsplit("/", 1)[-1]
+            existing = self.get_scenario(slug)
+            return Analysis._from_results(
+                existing.get("analysis_results") or {},
+                depth=depth, slug=slug,
+                scenario_id=existing.get("id"),
+            )
+
+        if depth == "instant":
+            results = (body.get("result") or {}).get("results") or {}
+            return Analysis._from_results(
+                results, depth="instant",
+                preliminary=bool(body.get("preliminary")),
+            )
+
+        stub = Analysis(job_id=body.get("job_id"), slug=body.get("slug"),
+                        scenario_id=body.get("scenario_id"), depth=depth)
+        if not wait:
+            return stub
+
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            job = self.get_job(stub.job_id)
+            status = job.get("status")
+            if status == "SUCCESS":
+                results = (job.get("result") or {}).get("results") or {}
+                return Analysis._from_results(
+                    results, depth=depth, job_id=stub.job_id,
+                    slug=stub.slug, scenario_id=stub.scenario_id,
+                )
+            if status == "FAILURE":
+                raise ApiError(500, (job.get("result") or {}).get(
+                    "error", "Analysis failed"), code="analysis_failed")
+            time.sleep(poll_interval)
+        raise ApiError(408, f"Timed out after {timeout}s waiting for job "
+                            f"{stub.job_id}", code="timeout")
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/public/v1/job/{job_id}")
+
+    def get_scenario(self, slug: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/public/v1/scenarios/{slug}")
+
+    # ------------------------------------------------------------------ feed
+    def feed(self, *, limit: int = 25, cursor: Optional[str] = None,
+             include_analysis: bool = False) -> Dict[str, Any]:
+        """Pre-analyzed trending scenarios — the <100ms read path."""
+        params: Dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        if include_analysis:
+            params["include"] = "analysis"
+        return self._request("GET", "/api/public/v1/feed/scenarios",
+                             params=params)
+
+    # ----------------------------------------------------------------- account
+    def usage(self) -> Dict[str, Any]:
+        return self._request("GET", "/api/public/v1/usage")
+
+    def rotate_key(self) -> Dict[str, Any]:
+        """Mint a replacement key (old key lives 24h). Update self.api_key."""
+        body = self._request("POST", "/api/public/v1/keys/rotate")
+        self.api_key = body["token"]
+        return body
+
+    # ---------------------------------------------------------------- webhooks
+    def create_webhook(self, url: str) -> Dict[str, Any]:
+        return self._request("POST", "/api/public/v1/webhooks",
+                             json={"url": url})
+
+    def list_webhooks(self) -> Dict[str, Any]:
+        return self._request("GET", "/api/public/v1/webhooks")
+
+    def delete_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        return self._request("DELETE",
+                             f"/api/public/v1/webhooks/{webhook_id}")
+
+
+def verify_webhook_signature(body: bytes, signature_header: str, secret: str,
+                             tolerance_seconds: int = 300) -> bool:
+    """Verify X-SN-Signature ("t=<unix>,v1=<hex>") for a webhook delivery.
+
+        if not verify_webhook_signature(request.body, sig_header, secret):
+            return 400
+    """
+    try:
+        parts = dict(p.split("=", 1) for p in signature_header.split(","))
+        ts = int(parts["t"])
+        provided = parts["v1"]
+    except (KeyError, ValueError, AttributeError):
+        return False
+    if abs(time.time() - ts) > tolerance_seconds:
+        return False
+    if isinstance(body, str):
+        body = body.encode()
+    expected = hmac.new(secret.encode(), b"%d." % ts + body,
+                        hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, provided)

scenario_navigator-0.1.0/scenario_navigator_sdk/mcp_server.py

@@ -0,0 +1,66 @@
+"""MCP server for Scenario Navigator — agent-native access to the API.
+
+Run (requires `pip install "scenario-navigator[mcp]"`):
+
+    SCEN_NAV_TOKEN=sn_live_... python -m scenario_navigator_sdk.mcp_server
+
+Or in an MCP client config:
+
+    {"command": "python", "args": ["-m", "scenario_navigator_sdk.mcp_server"],
+     "env": {"SCEN_NAV_TOKEN": "sn_live_..."}}
+
+Without SCEN_NAV_TOKEN a free trial key is minted automatically.
+"""
+from __future__ import annotations
+
+import os
+
+from . import Client
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as exc:  # pragma: no cover
+    raise SystemExit(
+        'MCP extra not installed — pip install "scenario-navigator[mcp]"'
+    ) from exc
+
+mcp = FastMCP("scenario-navigator")
+
+_client: Client | None = None
+
+
+def _get_client() -> Client:
+    global _client
+    if _client is None:
+        token = os.environ.get("SCEN_NAV_TOKEN")
+        base = os.environ.get("SCEN_NAV_BASE_URL", "https://api.scenarionavigator.io")
+        _client = (
+            Client(token, base_url=base) if token else Client.with_trial_token(base)
+        )
+    return _client
+
+
+@mcp.tool()
+def analyze_scenario(text: str, depth: str = "fast") -> dict:
+    """Analyze a news scenario: returns ranked benefiting/hurting US stocks
+    with confidence labels (high/medium/low). depth: "instant" (seconds,
+    preliminary), "fast" (~1 min), or "deep" (2-3 min, deepest research)."""
+    analysis = _get_client().analyze(text, depth=depth)
+    return {
+        "depth": analysis.depth,
+        "preliminary": analysis.preliminary,
+        "benefiting": [vars(s) for s in analysis.benefiting],
+        "hurting": [vars(s) for s in analysis.hurting],
+        "slug": analysis.slug,
+    }
+
+
+@mcp.tool()
+def trending_scenarios(limit: int = 10, include_analysis: bool = True) -> dict:
+    """Latest pre-analyzed trending market scenarios (instant, no submission
+    needed). Each item can include its ranked winners/losers inline."""
+    return _get_client().feed(limit=limit, include_analysis=include_analysis)
+
+
+if __name__ == "__main__":
+    mcp.run()