Metadata-Version: 2.4
Name: microcafe
Version: 0.1.0
Summary: Python SDK for microCafe - AI-powered microbiome analysis
Project-URL: Homepage, https://microcafe.ai
Project-URL: Documentation, https://docs.microcafe.ai
Project-URL: Repository, https://github.com/microcafe/microcafe-python
Project-URL: Issues, https://github.com/microcafe/microcafe-python/issues
Author-email: microCafe <support@microcafe.ai>
License: MIT
Keywords: 16S,api,bioinformatics,genomics,metagenomics,microbiome
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# microCafe Python SDK

Official Python SDK for [microCafe](https://microcafe.ai) — AI-powered microbiome analysis.

## Installation

```bash
pip install microcafe
```

## Quick Start

```python
from microcafe import Client

# Auto-reads API key from env var or ~/.microcafe/config.json
client = Client()

# Or pass explicitly
client = Client(api_key="mc_your_key_here")

# Classify a single sequence
result = client.classify("ATCGATCGATCG...")
print(result.predictions[0].genus)       # "Bacteroides"
print(result.predictions[0].confidence)  # 0.95

# Classify a file (submits, polls, returns abundance)
summary = client.classify_file("sequences.fq")
print(summary.summary.raw_counts)           # {"Bacteroides": 150, "Prevotella": 80}
print(summary.summary.relative_abundance)   # {"Bacteroides": 65.2, "Prevotella": 34.8}
```

## CLI Usage

```bash
# Save API key (stored in ~/.microcafe/config.json)
microcafe configure mc_your_key_here

# Classify a single sequence
microcafe classify "ATCGATCGATCG..."
microcafe classify "ATCGATCG..." --format json

# Classify a file (submits, shows progress bar, returns abundance)
microcafe classify-file sequences.fq
microcafe classify-file sequences.fq --output results.json
microcafe classify-file sequences.fq --format json

# Check job status
microcafe status <job_id>
microcafe status <job_id> --wait       # poll until complete

# Get abundance table
microcafe abundance <job_id>
microcafe abundance <job_id> --top 20  # show top 20 genera
microcafe abundance <job_id> --output abundance.json

# Get per-sequence predictions
microcafe predictions <job_id>
microcafe predictions <job_id> --output predictions.json
```

## Python API Reference

### Client

```python
from microcafe import Client

# Auto-resolves API key from env var or config file
client = Client()

# Or configure explicitly
client = Client(
    api_key="mc_xxx",           # Optional if env var or config file is set
    base_url="https://...",     # Optional, default: https://microcafe.ai/api
    timeout=300                 # Optional, request timeout in seconds
)
```

### Single Sequence Classification

```python
result = client.classify(
    sequence="ATCGATCG...",
    top_k=5  # Number of top predictions
)

print(result.sequence_length)
for pred in result.predictions:
    print(f"{pred.genus}: {pred.confidence}")
```

### File Classification

```python
# Submits file, polls for progress, returns abundance summary
summary = client.classify_file(
    file_path="sequences.fq",
    top_k=5,
    poll_interval=2.0,  # Seconds between status checks
    on_progress=lambda s: print(f"{s.progress}%")  # Optional callback
)

print(summary.summary.raw_counts)
print(summary.summary.relative_abundance)
```

### Job Management

```python
# Submit file (returns immediately)
job = client.classify_file_async("sequences.fq")
print(job.job_id)

# Check status
status = client.get_job_status(job.job_id)
print(f"{status.progress}% — {status.sequences_processed}/{status.total_sequences}")

# Wait for completion
final_status = client.wait_for_job(job.job_id)

# Get results
abundance = client.get_job_summary(job.job_id)    # abundance table
predictions = client.get_job_results(job.job_id)   # per-sequence predictions
```

## Environment Variables

```bash
export MICROCAFE_API_KEY=mc_your_key_here
```

```python
# No need to pass api_key if env var is set
client = Client()
```

## Error Handling

```python
from microcafe import Client, MicroCafeError, RateLimitError, AuthenticationError

try:
    result = client.classify("ATCG...")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except AuthenticationError:
    print("Invalid API key")
except MicroCafeError as e:
    print(f"Error: {e.message}")
```

## Supported File Formats

- FASTA (`.fasta`, `.fa`)
- FASTQ (`.fastq`, `.fq`)

## Links

- [microCafe Website](https://microcafe.ai)
- [API Documentation](https://microcafe.ai/api/docs)
- [Get API Key](https://microcafe.ai/dashboard/api-console)

## License

MIT