nexus-alpha 1.0.0__tar.gz

nexus_alpha-1.0.0/PKG-INFO

@@ -0,0 +1,214 @@
+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.*

nexus_alpha-1.0.0/README.md

@@ -0,0 +1,178 @@
+# 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.*

nexus_alpha-1.0.0/nexus_alpha/__init__.py

@@ -0,0 +1,38 @@
+"""
+NEXUS Alpha Python SDK
+======================
+Institutional-grade alternative data signals from SEC EDGAR filings.
+
+Quick start::
+
+    from nexus_alpha import NexusAlpha
+
+    client = NexusAlpha("your-api-key")
+
+    # Top signals right now
+    signals = client.signals.top(limit=10)
+    for s in signals:
+        print(s.ticker, s.signal, s.confidence, s.rationale)
+
+    # Full history as a DataFrame
+    df = client.signals.history(min_confidence=0.65).to_dataframe()
+
+    # Live WebSocket stream
+    def on_signal(signal):
+        print(f"NEW SIGNAL: {signal['ticker']} → {signal['signal']}")
+
+    client.stream(on_signal)  # blocks; Ctrl-C to stop
+
+Docs: https://nexusalpha.io/docs
+"""
+
+from .client import NexusAlpha
+from .exceptions import NexusAlphaError, AuthError, RateLimitError, APIError
+from .models import Signal, SignalCollection, PerformanceReport
+
+__version__ = "1.0.0"
+__all__ = [
+    "NexusAlpha",
+    "NexusAlphaError", "AuthError", "RateLimitError", "APIError",
+    "Signal", "SignalCollection", "PerformanceReport",
+]