Metadata-Version: 2.4
Name: sharp-sparc
Version: 0.1.0
Summary: Hosted statistical capability for identifying a compact predictive feature core in high-dimensional biological data.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

# sharp-sparc

Hosted statistical capability for identifying a compact predictive feature core in high-dimensional biological data.

`sharp-sparc` is the thin, official Python client for SPARC. It provides reproducible statistical discovery and decision boundaries for high-dimensional biological datasets ($P \gg N$).

---

## Installation

```bash
pip install sharp-sparc
```

---

## 5-Line Quickstart

```python
from sharp_sparc import SPARC

# 1. Initialize client with your API key
sparc = SPARC(api_key="sparc_live_...")

# 2. Discover predictive core signals from tabular data
result = sparc.discover(X, y, top_k=20, approve_upload=True)

# 3. Inspect discovered core signals
for rank, signal in enumerate(result.core_signals, start=1):
    print(f"#{rank}: {signal.name} (relevance={signal.predictive_relevance:.4f})")
```

---

## Privacy Boundary and Local Preflight

SPARC enforces a strict privacy boundary:
1. **Local Metadata Inspection:** Your dataset's dimensions, non-finite cell counts, and SHA256 digest are computed **locally on your machine**. Raw cell values and feature names never leave your environment during preflight.
2. **Explicit Caller Approval:** Raw data uploads only after explicit caller approval using a server-issued signed URL (`approve_upload=True`). All remote uploads enforce TLS (`https://`) transport.

### Discovering from a Local CSV/TSV File

```python
result = sparc.discover_file(
    path="patient_cohort_rnaseq.csv",
    target_column="treatment_response",
    top_k=15,
    approve_upload=True,
)
```

---

## Granular REST Lifecycle

For production pipelines and workflow orchestrators, `sharp-sparc` exposes the full granular lifecycle:

```python
from sharp_sparc import SPARC, inspect_dataset

client = SPARC(api_key="sparc_live_...")

# 1. Check account quota
account = client.get_account_status()
print(f"Tier: {account.tier}, Runs Remaining: {account.runs_remaining}")

# 2. Inspect aggregate metadata locally
metadata = inspect_dataset("data.csv", target_index=10)

# 3. Validate against tier limits (zero raw data sent)
preflight = client.preflight(metadata=metadata)

# 4. Stream upload with signed authorization
upload = client.upload_dataset(
    file_path_or_data="data.csv",
    preflight_token=preflight.upload_token,
    metadata=metadata,
)

# 5. Submit analysis with idempotency protection
receipt = client.submit_analysis(
    dataset_ref=upload.dataset_ref,
    target_column="target",
    top_k=10,
    idempotency_key="pipeline-run-2026-08-batch-1",
)

# 6. Poll status
status = client.poll_analysis(receipt.job_id)

# 7. Export standalone Python and C++ decision trees (Pro tier)
coretree = client.export_coretree(receipt.job_id)
print(coretree.python_source)
```

---

## Async Client (`AsyncSPARC`)

```python
import asyncio
from sharp_sparc import AsyncSPARC

async def main():
    async with AsyncSPARC(api_key="sparc_live_...") as client:
        account = await client.get_account_status()
        print(f"Account Tier: {account.tier}")

asyncio.run(main())
```

---

## Canonical API Route Map

| Operation | Canonical REST Endpoint |
|---|---|
| Account Status | `GET /v1/account` |
| Preflight Validation | `POST /v1/preflight` |
| Upload Authorization | `POST /v1/datasets/uploads` |
| Direct Data Upload | `PUT /v1/datasets/uploads/{dataset_id}` |
| Upload Completion | `POST /v1/datasets/uploads/{dataset_id}/complete` |
| Submit Analysis | `POST /v1/analyses` (supports `Idempotency-Key`) |
| Poll Job Status | `GET /v1/analyses/{job_id}` |
| Job Results | `GET /v1/analyses/{job_id}/result` |
| Cancel Job | `POST /v1/analyses/{job_id}/cancel` |
| Export CoreTree Code | `GET /v1/analyses/{job_id}/coretree` |
