Metadata-Version: 2.4
Name: smarts-bio
Version: 0.1.2
Summary: Official Python SDK for the smarts.bio bioinformatics platform
Author-email: SmartsBio <dev@smarts.bio>
License: MIT
Project-URL: Homepage, https://smarts.bio
Project-URL: Documentation, https://smarts.bio/docs
Project-URL: Repository, https://github.com/smartsbio/python-sdk
Keywords: bioinformatics,genomics,ai,smarts.bio,sdk
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/smartsbio/python-sdk/main/assets/logo-white.svg" />
    <img src="https://raw.githubusercontent.com/smartsbio/python-sdk/main/assets/logo.svg" alt="smarts.bio" height="60" />
  </picture>
</p>

<h3 align="center">Official Python SDK for <a href="https://smarts.bio">smarts.bio</a></h3>

<p align="center">
  Run BLAST, GATK, AlphaFold, BWA, DESeq2, and dozens more bioinformatics tools — all through a single API.
</p>

<p align="center">
  <a href="https://pypi.org/project/smarts-bio/"><img src="https://img.shields.io/pypi/v/smarts-bio.svg" alt="PyPI version" /></a>
  <a href="https://smarts.bio/docs"><img src="https://img.shields.io/badge/docs-smarts.bio%2Fdocs-blue" alt="documentation" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /></a>
</p>

---

## Get started in 2 minutes

1. **Sign up** at [smarts.bio](https://smarts.bio) and create a free account
2. **Generate an API key** — Organization Settings → API Keys
3. **Install and run:**

```bash
pip install smarts-bio
```

```python
from smartsbio import SmartsBio

client = SmartsBio(api_key="sk_live_...")

response = client.query.run(
    "Run BLAST for ATGCGTAACCGTAA and find homologs in nr database",
    workspace_id="ws_abc",
)
print(response.answer)
```

**Full documentation → [smarts.bio/docs](https://smarts.bio/docs)**

---

## What can you do?

Ask the AI agent anything — it orchestrates the right tools automatically:

| Category | Tools |
|----------|-------|
| **Sequence analysis** | BLAST, HMMER, Clustal Omega, MUSCLE |
| **Variant calling** | GATK HaplotypeCaller, FreeBayes, DeepVariant |
| **Alignment** | BWA-MEM, STAR, HISAT2, Bowtie2 |
| **Structure prediction** | AlphaFold, RoseTTAFold, ESMFold |
| **RNA-seq / expression** | DESeq2, edgeR, Salmon, kallisto |
| **Genome annotation** | Prokka, Augustus, BRAKER |
| **Literature & databases** | PubMed, NCBI Gene, UniProt, STRING, ClinVar |
| **Pipelines** | WES alignment, somatic variant calling, RNA-seq differential expression |

> These are just some of the tools available. See the full updated list at [smarts.bio/docs](https://smarts.bio/docs).

---

## Installation

```bash
pip install smarts-bio
```

**Requirements:** Python 3.9+. Single dependency: `httpx`.

---

## Authentication

```python
# Pass directly
client = SmartsBio(api_key="sk_live_...")

# Or set SMARTSBIO_API_KEY environment variable
client = SmartsBio()
```

Generate your key at [chat.smarts.bio](https://chat.smarts.bio) → Organization Settings → API Keys.

---

## Examples

### Ask a bioinformatics question

```python
response = client.query.run(
    "Find BRCA1 variants associated with breast cancer and summarize the evidence",
    workspace_id="ws_abc",
)
print(response.answer)
```

### Real-time streaming

```python
for chunk in client.query.stream("Align these reads to GRCh38", workspace_id="ws_abc"):
    if chunk.type == "status":
        print(f"[{chunk.status}]")
    elif chunk.type == "content":
        print(chunk.content, end="", flush=True)
    elif chunk.type == "done":
        print("\nDone.")
```

### Run a bioinformatics pipeline

```python
# Upload your FASTQ files
r1 = client.files.upload("sample_R1.fastq.gz", "ws_abc")
r2 = client.files.upload("sample_R2.fastq.gz", "ws_abc")

# Launch a WES alignment pipeline
pipeline = client.pipelines.create(
    "ws_abc",
    input={"fastq_r1": r1.key, "fastq_r2": r2.key, "reference": "GRCh38"},
    pipeline_id="alignment-wes",
)

# Wait for results (polls automatically)
result = client.pipelines.wait(
    pipeline.id,
    "ws_abc",
    on_progress=lambda p: print(f"  {p.progress_pct}% — {p.current_step}"),
)
```

### Async client

```python
import asyncio
from smartsbio import SmartsBioAsync

async def main():
    async with SmartsBioAsync(api_key="sk_live_...") as client:
        response = await client.query.run(
            "Find BRCA1 variants",
            workspace_id="ws_abc",
        )
        print(response.answer)

asyncio.run(main())
```

### Visualize results

```python
result = client.visualizations.viewer_url("orgs/.../variants.vcf", "ws_abc")
print(f"Open in browser: {result.viewer_url}")
```

---

## SDK Modules

| Module | Description |
|--------|-------------|
| `client.query` | Ask the AI agent — sync or streaming SSE |
| `client.workspaces` | List and manage workspaces |
| `client.conversations` | Retrieve conversation history |
| `client.tools` | List available tools and run them directly |
| `client.files` | Upload, download, and manage files |
| `client.pipelines` | Launch and monitor long-running bioinformatics pipelines |
| `client.visualizations` | Generate shareable viewer URLs and render plots |

---

## Error Handling

```python
from smartsbio import AuthenticationError, PermissionDeniedError, RateLimitError, APIError

try:
    client.query.run("...")
except AuthenticationError:
    print("Invalid API key")
except PermissionDeniedError as e:
    print(f"Key lacks required scope: {e.required_scope}")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except APIError as e:
    print(f"API error {e.status}: {e.message}")
```

---

## Configuration

```python
client = SmartsBio(
    api_key="sk_live_...",
    timeout=120,       # seconds (default: 120)
    max_retries=3,     # retries on 429 / 5xx (default: 3)
)
```

---

## More Examples

See the [`examples/`](./examples) directory:

- [`query_sync.py`](./examples/query_sync.py) — basic AI query
- [`query_stream.py`](./examples/query_stream.py) — real-time streaming output
- [`query_async.py`](./examples/query_async.py) — async client with streaming
- [`list_tools.py`](./examples/list_tools.py) — enumerate available tools
- [`upload_and_pipeline.py`](./examples/upload_and_pipeline.py) — upload files and run a pipeline
- [`viewer_url.py`](./examples/viewer_url.py) — generate a bio-viewer link

---

## Documentation & Support

- **Full docs:** [smarts.bio/docs](https://smarts.bio/docs)
- **Platform:** [smarts.bio](https://smarts.bio)
- **Issues:** [GitHub Issues](https://github.com/smartsbio/python-sdk/issues)
- **Email:** support@smarts.bio

---

<p align="center">
  Built with ❤️ by the <a href="https://smarts.bio">smarts.bio</a> team
</p>
