Metadata-Version: 2.4
Name: nexus-alpha
Version: 1.0.0
Summary: Python SDK for NEXUS Alpha — institutional alternative data signals from SEC EDGAR filings
Author-email: NEXUS Alpha <ksaaus1@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://nexusalpha.io
Project-URL: Documentation, https://nexusalpha.io/docs
Project-URL: Repository, https://github.com/nexus-alpha/nexus-alpha-python
Project-URL: Bug Tracker, https://github.com/nexus-alpha/nexus-alpha-python/issues
Keywords: finance,alternative-data,sec,edgar,signals,quant,hedge-fund
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"
Provides-Extra: stream
Requires-Dist: websocket-client>=1.6; extra == "stream"
Provides-Extra: all
Requires-Dist: pandas>=1.5; extra == "all"
Requires-Dist: websocket-client>=1.6; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: responses; extra == "dev"
Requires-Dist: pandas>=1.5; extra == "dev"
Requires-Dist: websocket-client>=1.6; extra == "dev"

# NEXUS Alpha Python SDK

**Institutional alternative data signals from SEC EDGAR filings.**

[![PyPI](https://img.shields.io/pypi/v/nexus-alpha)](https://pypi.org/project/nexus-alpha/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## Installation

```bash
pip install nexus-alpha          # Core (REST API only)
pip install nexus-alpha[pandas]  # + DataFrame support
pip install nexus-alpha[stream]  # + WebSocket streaming
pip install nexus-alpha[all]     # Everything
```

## Quick Start

```python
from nexus_alpha import NexusAlpha

client = NexusAlpha("your-api-key")
# Or: NEXUS_ALPHA_API_KEY=your-key in env, then NexusAlpha()

# Top signals right now
for s in client.signals.top(limit=10):
    print(f"{s.ticker:6s} | {s.signal:12s} | conf={s.confidence:.3f} | {s.freshness_status}")
    print(f"  {s.rationale[:100] if s.rationale else ''}")
```

**Output:**
```
NVDA   | OVERWEIGHT   | conf=0.712 | LIVE
  GPU demand accelerating; data center revenue beat by 18%
MSFT   | BUY          | conf=0.683 | LIVE
  Azure growth +29% YoY; AI copilot ARR surpassed $5B
```

## Signal Retrieval

```python
# Search with filters
signals = client.signals.search(
    ticker="NVDA",
    signal="BUY",
    min_confidence=0.65,
)

# Full history → pandas DataFrame (Tier 1+)
df = client.signals.history(
    date_from="2024-01-01",
    date_to="2024-12-31",
    min_confidence=0.65,
    limit=500,
).to_dataframe()

print(df[["ticker", "signal_date", "signal", "confidence"]].head())
```

## Bulk CSV Export (Tier 2+)

```python
# Downloads up to 10,000 signals as a DataFrame
df = client.data.export(date_from="2022-01-01")
df.to_csv("nexus_signals.csv", index=False)
print(f"Downloaded {len(df)} signals")
```

## Analytics & Backtest

```python
perf = client.analytics.performance()

# Best hold period (highest Sharpe)
best = perf.best_hold_period
print(f"Best: {best.hold_days}d hold | Sharpe {best.sharpe_annualized} | WR {best.win_rate:.1%}")
# Best: 60d hold | Sharpe 1.2 | WR 70.6%

# Equity curve → DataFrame
eq_df = perf.equity_curve.to_dataframe()
print(eq_df[["quarter", "portfolio_return", "spy_return", "excess_return"]])

# Per-confidence-bucket breakdown
for band, stats in best.by_confidence_bucket.items():
    print(f"  {band}: {stats['win_rate']:.0%} WR, {stats['mean']:+.1f}% avg return")
```

## Real-Time Signal Stream (Tier 1+)

### Blocking (foreground)
```python
def handle_signal(signal: dict):
    print(f"📡 NEW: {signal['ticker']} → {signal['signal']} (conf={signal['confidence']:.3f})")
    print(f"   {signal.get('rationale', '')}")

client.stream(handle_signal)  # blocks; Ctrl-C to stop
```

### Non-blocking (background thread)
```python
import time

thread = client.stream_async(handle_signal)

# Do other work while signals stream in
while True:
    time.sleep(1)
```

## Account Usage

```python
usage = client.account.usage()
print(f"Tier: {usage.tier_name}")
print(f"Requests today: {usage.requests_today}")
print(f"Remaining this hour: {usage.remaining_this_hour()}")
```

## Error Handling

```python
from nexus_alpha import NexusAlpha, AuthError, RateLimitError, TierError

try:
    signals = client.signals.history(limit=5000)
except TierError as e:
    print(f"Need Tier {e.required_tier}+ — upgrade at nexusalpha.io")
except RateLimitError:
    print("Rate limit hit — wait for next hour window")
except AuthError:
    print("Invalid API key")
```

## Environment Variable

Set `NEXUS_ALPHA_API_KEY` to avoid passing the key in code:

```bash
export NEXUS_ALPHA_API_KEY=your-api-key
```

```python
client = NexusAlpha()  # reads from env automatically
```

## API Tiers

| Tier | Price | Rate limit | History | Bulk export | Stream |
|------|-------|-----------|---------|-------------|--------|
| Insight | $5k/mo | 100/hr | 500 rows | ❌ | ✅ |
| Intelligence | $15k/mo | 500/hr | 5,000 rows | ✅ (10k) | ✅ |
| Institutional | $50k/mo | 5,000/hr | 5,000 rows | ✅ (10k) | ✅ |

Subscribe at [nexusalpha.io](https://nexusalpha.io).

## Backtest Summary

Walk-forward validated 2022–2025 (long-only signals):

| Hold Period | Avg Return | vs SPY | Sharpe | Win Rate |
|-------------|-----------|--------|--------|----------|
| 20 days | +0.61% | −0.11% | 0.35 | 58.8% |
| 40 days | +3.63% | +1.34% | 1.13 | 58.8% |
| **60 days** | **+4.79%** | **+2.45%** | **1.20** | **70.6%** |

**Key finding:** 0.65–0.70 confidence band → 90% win rate, +12.3% avg return at 60d.
IC is negative above 0.75 confidence → signals capped at 0.75.

⚠️ **Important:** Per-signal excess return (+2.45% vs SPY) reflects information edge per trade.
Full equal-weight portfolio simulation: +9.5% vs SPY +26.2% (2022–2025). These signals
are designed as **information overlays** on existing positions, not standalone portfolios.
[Full methodology →](https://nexusalpha.io/methodology)

---

*Signals are informational only and do not constitute investment advice.
NEXUS Alpha is not a registered investment adviser.*
