Metadata-Version: 2.4
Name: alphainfo
Version: 1.0.3
Summary: Python client for alphainfo.io — Structural Regime Detection API
Home-page: https://github.com/alphainfo-io/python-sdk
Author: alphainfo.io
Author-email: "alphainfo.io" <support@alphainfo.io>
License: MIT
Project-URL: Homepage, https://alphainfo.io
Project-URL: Documentation, https://alphainfo.io/docs
Project-URL: Repository, https://github.com/alphainfo-io/python-sdk
Project-URL: Changelog, https://alphainfo.io/changelog
Keywords: alphainfo,structural-analysis,regime-detection,time-series,anomaly-detection,signal-processing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# alphainfo

**Python client for the [alphainfo](https://alphainfo.io) Structural Intelligence API.**

Detect structural regime changes in time series — biomedical signals, financial markets, energy grids, seismic data, IoT sensors, and more. No model training required.

```python
from alphainfo import AlphaInfo

client = AlphaInfo(api_key="ai_your_key")
result = client.analyze(signal=ecg_data, sampling_rate=360.0, domain="biomedical")

print(result.confidence_band)   # 'stable', 'transition', or 'unstable'
print(result.structural_score)  # 0.0 to 1.0
print(result.analysis_id)       # UUID for audit trail
```

## Installation

```bash
pip install alphainfo
```

Requires Python 3.8+. Only dependency: [httpx](https://www.python-httpx.org/).

## Quick Start

### 1. Get your API key

Sign up at [alphainfo.io/register](https://alphainfo.io/register) — free tier includes 50 analyses/month.

### 2. Analyze a signal

```python
from alphainfo import AlphaInfo

client = AlphaInfo(api_key="ai_your_key")

# Any time series: ECG, market prices, sensor readings, power grid...
result = client.analyze(
    signal=[1.2, 1.3, 1.1, 2.8, 3.1, 3.0, ...],
    sampling_rate=250.0,
    domain="biomedical",
)

if result.change_detected:
    print(f"Regime change detected! Band: {result.confidence_band}")
    print(f"Structural score: {result.structural_score:.3f}")
    print(f"Audit ID: {result.analysis_id}")
```

### 3. Analyze market data

```python
# The API fetches market data automatically
market = client.analyze_market("AAPL", interval="1d")
print(f"AAPL regime: {market.confidence_band}")
print(f"Score: {market.structural_score:.3f}")
```

### 4. Batch analysis

```python
# Analyze up to 100 signals in one call
batch = client.analyze_batch(
    signals=[signal_1, signal_2, signal_3],
    sampling_rate=1000.0,
    domain="sensors",
)

for item in batch.results:
    if item.success:
        print(f"Signal {item.index}: {item.confidence_band} ({item.structural_score:.3f})")
    else:
        print(f"Signal {item.index}: error — {item.error}")
```

### 5. Multi-channel (vector) analysis

```python
# Multi-lead ECG, multi-axis accelerometer, etc.
vector = client.analyze_vector(
    channels={
        "lead_I": ecg_lead_1,
        "lead_II": ecg_lead_2,
        "lead_III": ecg_lead_3,
    },
    sampling_rate=360.0,
    domain="biomedical",
)

print(f"Aggregated score: {vector.structural_score:.3f}")
for name, ch in vector.channels.items():
    print(f"  {name}: {ch.confidence_band}")
```

### 6. Audit trail

```python
# Replay any past analysis
replay = client.audit_replay("550e8400-e29b-41d4-a716-446655440000")
print(f"Original score: {replay.output['structural_score']}")

# List recent analyses
history = client.audit_list(limit=10)
for entry in history:
    print(f"{entry.analysis_id} — {entry.structural_score}")
```

## Async Support

```python
from alphainfo import AsyncAlphaInfo

async with AsyncAlphaInfo(api_key="ai_your_key") as client:
    result = await client.analyze(signal=data, sampling_rate=250.0)
    market = await client.analyze_market("BTC-USD")
```

All methods available on `AlphaInfo` are also available on `AsyncAlphaInfo`.

## Error Handling

```python
from alphainfo import AlphaInfo, AuthError, RateLimitError, ValidationError

client = AlphaInfo(api_key="ai_your_key")

try:
    result = client.analyze(signal=data, sampling_rate=250.0)
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid input: {e.message}")
```

**Exception hierarchy:**

| Exception | HTTP Code | When |
|-----------|-----------|------|
| `AuthError` | 401 | Invalid or missing API key |
| `ValidationError` | 400, 413 | Bad input or signal too large |
| `RateLimitError` | 429 | Quota or concurrency limit exceeded |
| `NotFoundError` | 404 | Analysis ID not found (audit) |
| `APIError` | 5xx | Server error |
| `TimeoutError` | — | Request timed out after retries |
| `NetworkError` | — | Connection failed |

All inherit from `AlphaInfoError`.

## Configuration

```python
client = AlphaInfo(
    api_key="ai_your_key",
    base_url="https://alphainfo.io",  # default
    timeout=30.0,                      # seconds (default)
    max_retries=3,                     # automatic retry on transient errors
)
```

The client automatically retries on:
- Network timeouts and connection errors
- HTTP 429 (rate limits) — respects `Retry-After` header
- HTTP 5xx (server errors)

Non-retryable errors (401, 400, 404) are raised immediately.

## Rate Limit Info

```python
result = client.analyze(signal=data, sampling_rate=250.0)
info = client.rate_limit_info
if info:
    print(f"Remaining: {info.remaining}/{info.limit}")
```

## Domains

| Domain | Use case |
|--------|----------|
| `generic` | Default — works for any signal |
| `biomedical` | ECG, EEG, EMG, SpO2 |
| `finance` | Market prices, returns, volume |
| `energy` | Power grid frequency, load |
| `seismic` | Earthquake, vibration sensors |
| `sensors` | IoT, industrial sensors |
| `mlops` | Model drift, data quality |
| `security` | Network traffic, intrusion |
| `industrial` | Machinery, SCADA |

## Links

- [API Documentation](https://alphainfo.io/docs)
- [Benchmarks](https://alphainfo.io/benchmarks)
- [Dashboard](https://alphainfo.io/dashboard)

## License

MIT
