Metadata-Version: 2.5
Name: scenario-navigator
Version: 0.2.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<2,>=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.
