Metadata-Version: 2.4
Name: systemsdata
Version: 0.1.1
Summary: Official Python client for the Systems Capital API — US equity price history and quantitative statistics.
License: MIT
Project-URL: Homepage, https://www.systemscapital.net
Project-URL: Documentation, https://www.systemscapital.net/docs/api
Project-URL: Bug Tracker, https://github.com/systemscapital/systemsdata-python/issues
Keywords: finance,stocks,equities,quantitative,market-data,returns,statistics
Classifier: Development Status :: 4 - Beta
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.31
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"

# systemsdata

Official Python client for the [Systems Capital](https://www.systemscapital.net) API —
US equity close-price history and quantitative return statistics for 2,600+ tickers,
updated every trading day.

---

## Install

```bash
pip install systemsdata
```

Optional pandas support:

```bash
pip install systemsdata[pandas]
```

---

## Quick start

### 1 — Get an API key

```bash
python -m systemsdata setup
```

This opens the signup/dashboard URL, then asks you to paste your key.
The key is stored in `~/.systemsdata/config.json` and loaded automatically
on every subsequent import.

Alternatively, set the environment variable:

```bash
export SYSTEMSDATA_API_KEY="sc_live_..."
```

Or authenticate inline:

```python
import systemsdata as sd
sd.auth("sc_live_...")
```

---

### 2 — Fetch statistics

```python
import systemsdata as sd

# 3-month kurtosis for AAPL (most recent data point)
result = sd.stats("AAPL", range="3m", metrics=["kurtosis"])
print(result.metrics["kurtosis"])   # → 1.2347

# All metrics, 1-year range, 3-month trailing window
result = sd.stats("NVDA", range="1y", window="3m")
print(result)
# StatsResult(
#   symbol='NVDA', window='3m',
#   period=2024-03-14 → 2025-03-14 (252 pts)
#   metrics:
#   avg_return: 0.1823
#   std_dev: 3.2841
#   kurtosis: 2.9103
#   ...
# )
```

### 3 — Fetch price history

```python
prices = sd.prices("AAPL", range="1y")
print(prices.end_date, prices.points[-1].close)  # → 2025-03-14  214.37

# pandas DataFrame (requires systemsdata[pandas])
df = prices.to_dataframe()
print(df.tail())
```

---

## API reference

### `sd.auth(api_key)`

Set the API key for the current session. Not needed if `SYSTEMSDATA_API_KEY`
is set or if you ran `python -m systemsdata setup`.

---

### `sd.stats(symbol, *, range, from_date, to_date, metrics, window) → StatsResult`

Compute quantitative return statistics at the most recent data point.

| Parameter   | Type            | Default    | Description |
|-------------|-----------------|------------|-------------|
| `symbol`    | `str`           | required   | Ticker, e.g. `"AAPL"` |
| `range`     | `str`           | `"3m"`     | `"1w"` \| `"1m"` \| `"3m"` \| `"1y"` \| `"all"` |
| `from_date` | `str \| None`   | `None`     | Custom start `YYYY-MM-DD` |
| `to_date`   | `str \| None`   | `None`     | Custom end `YYYY-MM-DD` |
| `metrics`   | `list[str] \| None` | all    | Subset to compute |
| `window`    | `str`           | `"period"` | Trailing calc window (see below) |

**Valid `metrics` keys:**
`avg_return`, `std_dev`, `median`, `mode`, `min`, `max`,
`skewness`, `kurtosis`, `annualized_return`, `price_slope`

**Valid `window` values:**
`"period"` (entire range), `"1d"`, `"1w"`, `"1m"`, `"3m"`, `"6m"`, `"1y"`, `"2y"`, `"5y"`

`range` controls which price data is loaded; `window` controls the trailing
slice used in each calculation. Example: `range="1y", window="3m"` loads
one year of data but computes stats using only the last 3 months.

---

### `sd.prices(symbol, *, range, from_date, to_date) → PriceHistory`

Fetch daily close-price history.

```python
h = sd.prices("MSFT", range="6m")
h.points       # list[PricePoint(date, close)]
h.to_dicts()   # list[{"date": ..., "close": ...}]
h.to_dataframe()  # pandas DataFrame with DatetimeIndex
```

---

## Credit model

| Action | Cost |
|--------|------|
| 1 data point (date + close) | 2 credits |
| 1 metric value | 1 credit |

Monthly bucket caching: loading the same symbol/month twice costs credits
only on the first load. Free tier: 5,000 credits/month (signed-in) or
500 (anonymous).

---

## Error handling

```python
from systemsdata import AuthError, QuotaError, NotFoundError

try:
    result = sd.stats("AAPL", range="3m")
except AuthError:
    print("Invalid or missing API key")
except QuotaError as e:
    print(f"Out of credits — upgrade at {e.upgrade_url}")
except NotFoundError:
    print("Symbol not found")
```

---

## CLI

```bash
python -m systemsdata setup   # interactive key setup
python -m systemsdata info    # show active key and config
python -m systemsdata test    # smoke-test with a live API call
```

---

## LLM / agent usage

The API ships an OpenAPI 3.1 spec at:

```
https://www.systemscapital.net/api/v1/openapi
```

LLM agents can register the two endpoints (`/data`, `/stats`) as tools and
pass the API key via the `Authorization: Bearer sc_live_...` header.

---

## License

MIT
