Metadata-Version: 2.4
Name: quantumsignals-client
Version: 0.2.1
Summary: Python client for Quantum Signals APIs (streaming, inference, key management, backtest)
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: pydantic>=2.11.5
Requires-Dist: structlog>=24.1.0
Description-Content-Type: text/markdown

# Quantum Signals Client

Python client library for Quantum Signals APIs.

## Overview

This package provides a Python client for interacting with Quantum Signals services:

- **Streaming**: SSE-based signal streaming
- **Inference**: Model catalog and prediction endpoints
- **Key Management**: API key CRUD operations
- **Backtest**: Backtest results and metadata

## Configuration

The client reads configuration from environment variables:

```bash
# Required:
export QUANTUMSIGNALS_API_KEY=foobar
# Optional, defaults to production URL:
export QUANTUMSIGNALS_BASE_URL=http://localhost:8000
```

The API key can also be set explicitly:
```python
from quantumsignals.client import Client
client = Client(api_key="foobar")
client.set_api_key("foobar")
```

## Usage

### Init

```python
from quantumsignals.client import Client
client = Client()
```

### Fetching Available Models

```python
models = client.get_model_catalog()
```

### Streaming Signals

```python
# Stream real-time signals via SSE
for signal in client.stream_signals():
    print(f"{signal.time} | {signal.symbol}: {signal.signal}")
```

### Backtest Operations

```python
# Get most recent backtest for a model/symbol
backtest = client.get_most_recent_backtest(
    model_hash="abc123",
    symbol="AAPL"
)

# Get backtest metadata
metadata = client.get_backtest_metadata(backtest_id="uuid")

# Get backtest results (JSON, CSV, or Parquet)
results = client.get_backtest_results(
    backtest_id="uuid",
    format="json",
    page=1,
    page_size=100
)

# Get accuracy metrics
accuracy = client.get_backtest_accuracy(
    backtest_id="uuid",
    format="json"
)
```

### Context Manager Usage

```python
# Properly close HTTP connections
with Client() as client:
    client.login()
    models = client.get_model_catalog()
    # Client automatically closes on exit
```

## Development

This is a workspace package in the QS1 monorepo. See the main repository README for development setup.
