microcafe 0.1.0

Python SDK for microCafe - AI-powered microbiome analysis

microCafe Python SDK

Official Python SDK for microCafe — AI-powered microbiome analysis.

Installation

pip install microcafe

Quick Start

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

# 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

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

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

# 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

# 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

export MICROCAFE_API_KEY=mc_your_key_here

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

Error Handling

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
• API Documentation
• Get API Key

License

MIT