microcafe 0.1.0__py3-none-any.whl

microcafe/__init__.py

@@ -0,0 +1,54 @@
+# src/microcafe/__init__.py
+"""
+microCafe Python SDK - AI-powered microbiome analysis.
+
+Usage:
+    from microcafe import Client
+    
+    client = Client(api_key="mc_your_key_here")
+    
+    # Single sequence
+    result = client.classify("ATCGATCG...")
+    print(result.predictions[0].genus)
+    
+    # File classification
+    summary = client.classify_file("sequences.fq")
+    print(summary.summary.raw_counts)
+"""
+
+from .client import Client
+from .exceptions import (
+    MicroCafeError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    JobNotFoundError,
+    JobNotCompletedError,
+    ServerError,
+)
+from .models import (
+    Prediction,
+    ClassificationResult,
+    Summary,
+    JobStatus,
+    JobResults,
+    JobSummary,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "MicroCafeError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "JobNotFoundError",
+    "JobNotCompletedError",
+    "ServerError",
+    "Prediction",
+    "ClassificationResult",
+    "Summary",
+    "JobStatus",
+    "JobResults",
+    "JobSummary",
+]

microcafe/cli.py

@@ -0,0 +1,354 @@
+# src/microcafe/cli.py
+"""Command-line interface for microCafe."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from .client import Client
+from .exceptions import MicroCafeError
+
+
+def get_api_key(ctx_api_key: str = None) -> str:
+    """Get API key from argument, env var, or config file."""
+    if ctx_api_key:
+        return ctx_api_key
+
+    env_key = os.environ.get("MICROCAFE_API_KEY")
+    if env_key:
+        return env_key
+
+    config_path = Path.home() / ".microcafe" / "config.json"
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+                if config.get("api_key"):
+                    return config["api_key"]
+        except Exception:
+            pass
+
+    click.echo("Error: No API key provided.", err=True)
+    click.echo("Set via: --api-key, MICROCAFE_API_KEY env var, or 'microcafe configure'", err=True)
+    sys.exit(1)
+
+
+def format_output(data: dict, fmt: str):
+    """Output data in the requested format."""
+    if fmt == "json":
+        click.echo(json.dumps(data, indent=2))
+    else:
+        for key, value in data.items():
+            if isinstance(value, dict):
+                click.echo(f"\n{key}:")
+                for k, v in value.items():
+                    click.echo(f"  {k}: {v}")
+            else:
+                click.echo(f"{key}: {value}")
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="microcafe")
+def main():
+    """microCafe CLI - AI-powered microbiome analysis."""
+    pass
+
+
+@main.command()
+@click.argument("api_key")
+def configure(api_key: str):
+    """Save API key to config file."""
+    config_dir = Path.home() / ".microcafe"
+    config_dir.mkdir(exist_ok=True)
+
+    config_path = config_dir / "config.json"
+    config = {"api_key": api_key}
+
+    with open(config_path, "w") as f:
+        json.dump(config, f, indent=2)
+
+    click.echo(f"API key saved to {config_path}")
+
+
+@main.command()
+@click.argument("sequence")
+@click.option("--api-key", "-k", help="API key (or set MICROCAFE_API_KEY)")
+@click.option("--top-k", "-n", default=5, help="Number of predictions (default: 5)")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table", help="Output format")
+def classify(sequence: str, api_key: str, top_k: int, fmt: str):
+    """Classify a single DNA sequence."""
+    api_key = get_api_key(api_key)
+
+    try:
+        client = Client(api_key=api_key)
+        result = client.classify(sequence, top_k=top_k)
+
+        if fmt == "json":
+            format_output({
+                "sequence_length": result.sequence_length,
+                "predictions": [
+                    {"genus": p.genus, "confidence": p.confidence}
+                    for p in result.predictions
+                ]
+            }, fmt)
+        else:
+            click.echo(f"Sequence length: {result.sequence_length}")
+            click.echo("\nPredictions:")
+            for i, p in enumerate(result.predictions, 1):
+                bar = "█" * int(p.confidence * 20)
+                click.echo(f"  {i}. {p.genus:<20} {p.confidence:.4f}  {bar}")
+
+    except MicroCafeError as e:
+        click.echo(f"Error: {e.message}", err=True)
+        sys.exit(1)
+
+
+@main.command("classify-file")
+@click.argument("file_path", type=click.Path(exists=True))
+@click.option("--api-key", "-k", help="API key (or set MICROCAFE_API_KEY)")
+@click.option("--top-k", "-n", default=5, help="Number of predictions (default: 5)")
+@click.option("--output", "-o", type=click.Path(), help="Output file for results")
+@click.option("--no-wait", is_flag=True, help="Submit and return job ID without waiting")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table", help="Output format")
+def classify_file(file_path: str, api_key: str, top_k: int, output: str, no_wait: bool, fmt: str):
+    """Classify sequences from a FASTA/FASTQ file."""
+    api_key = get_api_key(api_key)
+
+    try:
+        client = Client(api_key=api_key)
+
+        click.echo(f"Uploading {file_path}...")
+        job = client.classify_file_async(file_path, top_k=top_k)
+        click.echo(f"Job submitted: {job.job_id}")
+
+        if no_wait:
+            click.echo(f"\nCheck status:  microcafe status {job.job_id}")
+            click.echo(f"Get abundance: microcafe abundance {job.job_id}")
+            return
+
+        # Poll with progress bar
+        with click.progressbar(length=100, label="Processing") as bar:
+            last_progress = 0
+            while True:
+                status = client.get_job_status(job.job_id)
+
+                increment = int(status.progress) - last_progress
+                if increment > 0:
+                    bar.update(increment)
+                    last_progress = int(status.progress)
+
+                if status.is_completed:
+                    bar.update(100 - last_progress)
+                    break
+
+                if status.is_failed:
+                    click.echo(f"\nJob failed: {status.error_message}", err=True)
+                    sys.exit(1)
+
+                import time
+                time.sleep(2.0)
+
+        # Fetch abundance summary
+        summary = client.get_job_summary(job.job_id)
+
+        result_data = {
+            "job_id": summary.job_id,
+            "file_name": summary.file_name,
+            "total_sequences": summary.total_sequences,
+            "unique_genera": summary.summary.unique_genera,
+            "raw_counts": summary.summary.raw_counts,
+            "relative_abundance": summary.summary.relative_abundance,
+        }
+
+        if output:
+            with open(output, "w") as f:
+                json.dump(result_data, f, indent=2)
+            click.echo(f"\nResults saved to {output}")
+        elif fmt == "json":
+            format_output(result_data, fmt)
+        else:
+            click.echo(f"\nResults for {summary.file_name}:")
+            click.echo(f"  Total sequences: {summary.total_sequences}")
+            click.echo(f"  Unique genera:   {summary.summary.unique_genera}")
+            click.echo(f"\nTop genera by abundance:")
+            sorted_abundance = sorted(
+                summary.summary.relative_abundance.items(),
+                key=lambda x: x[1],
+                reverse=True,
+            )[:10]
+            for i, (genus, abundance) in enumerate(sorted_abundance, 1):
+                count = summary.summary.raw_counts.get(genus, 0)
+                bar = "█" * int(abundance / 5)
+                click.echo(f"  {i:>2}. {genus:<20} {abundance:>6.2f}%  ({count:>5})  {bar}")
+
+    except MicroCafeError as e:
+        click.echo(f"Error: {e.message}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("job_id")
+@click.option("--api-key", "-k", help="API key (or set MICROCAFE_API_KEY)")
+@click.option("--wait", "-w", is_flag=True, help="Poll until job completes")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table", help="Output format")
+def status(job_id: str, api_key: str, wait: bool, fmt: str):
+    """Check status of a classification job."""
+    api_key = get_api_key(api_key)
+
+    try:
+        client = Client(api_key=api_key)
+
+        if wait:
+            click.echo(f"Waiting for job {job_id}...")
+            with click.progressbar(length=100, label="Processing") as bar:
+                last_progress = 0
+                while True:
+                    job_status = client.get_job_status(job_id)
+
+                    increment = int(job_status.progress) - last_progress
+                    if increment > 0:
+                        bar.update(increment)
+                        last_progress = int(job_status.progress)
+
+                    if not job_status.is_running:
+                        bar.update(100 - last_progress)
+                        break
+
+                    import time
+                    time.sleep(2.0)
+
+            click.echo(f"\nJob {job_status.status}.")
+            if job_status.is_completed:
+                click.echo(f"\nGet results:")
+                click.echo(f"  microcafe abundance {job_id}")
+                click.echo(f"  microcafe predictions {job_id}")
+            return
+
+        job_status = client.get_job_status(job_id)
+
+        if fmt == "json":
+            format_output({
+                "job_id": job_status.job_id,
+                "status": job_status.status,
+                "progress": job_status.progress,
+                "total_sequences": job_status.total_sequences,
+                "sequences_processed": job_status.sequences_processed,
+                "sequences_failed": job_status.sequences_failed,
+                "file_name": job_status.file_name,
+                "error_message": job_status.error_message,
+            }, fmt)
+        else:
+            click.echo(f"Job:       {job_status.job_id}")
+            click.echo(f"Status:    {job_status.status}")
+            click.echo(f"Progress:  {job_status.progress:.1f}%")
+            click.echo(f"Sequences: {job_status.sequences_processed}/{job_status.total_sequences}")
+            if job_status.sequences_failed:
+                click.echo(f"Failed:    {job_status.sequences_failed}")
+            if job_status.error_message:
+                click.echo(f"Error:     {job_status.error_message}")
+
+            if job_status.is_completed:
+                click.echo(f"\nGet results:")
+                click.echo(f"  microcafe abundance {job_id}")
+                click.echo(f"  microcafe predictions {job_id}")
+
+    except MicroCafeError as e:
+        click.echo(f"Error: {e.message}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("job_id")
+@click.option("--api-key", "-k", help="API key (or set MICROCAFE_API_KEY)")
+@click.option("--top", "-t", default=10, help="Number of top genera to show (default: 10)")
+@click.option("--output", "-o", type=click.Path(), help="Output file")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table", help="Output format")
+def abundance(job_id: str, api_key: str, top: int, output: str, fmt: str):
+    """Get abundance table (raw counts & relative abundance) of a completed job."""
+    api_key = get_api_key(api_key)
+
+    try:
+        client = Client(api_key=api_key)
+        job_summary = client.get_job_summary(job_id)
+
+        result_data = {
+            "job_id": job_summary.job_id,
+            "file_name": job_summary.file_name,
+            "total_sequences": job_summary.total_sequences,
+            "unique_genera": job_summary.summary.unique_genera,
+            "raw_counts": job_summary.summary.raw_counts,
+            "relative_abundance": job_summary.summary.relative_abundance,
+        }
+
+        if output:
+            with open(output, "w") as f:
+                json.dump(result_data, f, indent=2)
+            click.echo(f"Abundance data saved to {output}")
+        elif fmt == "json":
+            format_output(result_data, fmt)
+        else:
+            click.echo(f"Abundance for {job_summary.file_name}:")
+            click.echo(f"  Total sequences: {job_summary.total_sequences}")
+            click.echo(f"  Unique genera:   {job_summary.summary.unique_genera}")
+            click.echo(f"\nTop {top} genera by abundance:")
+            sorted_abundance = sorted(
+                job_summary.summary.relative_abundance.items(),
+                key=lambda x: x[1],
+                reverse=True,
+            )[:top]
+            for i, (genus, abd) in enumerate(sorted_abundance, 1):
+                count = job_summary.summary.raw_counts.get(genus, 0)
+                bar = "█" * int(abd / 5)
+                click.echo(f"  {i:>2}. {genus:<20} {abd:>6.2f}%  ({count:>5})  {bar}")
+
+    except MicroCafeError as e:
+        click.echo(f"Error: {e.message}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("job_id")
+@click.option("--api-key", "-k", help="API key (or set MICROCAFE_API_KEY)")
+@click.option("--output", "-o", type=click.Path(), help="Output file")
+def predictions(job_id: str, api_key: str, output: str):
+    """Get full per-sequence predictions of a completed job."""
+    api_key = get_api_key(api_key)
+
+    try:
+        client = Client(api_key=api_key)
+        job_results = client.get_job_results(job_id)
+
+        result_data = {
+            "job_id": job_results.job_id,
+            "total_sequences": job_results.total_sequences,
+            "model_version": job_results.model_version,
+            "predictions": [
+                {
+                    "sequence_id": r.sequence_id,
+                    "sequence_length": r.sequence_length,
+                    "predictions": [
+                        {"genus": p.genus, "confidence": p.confidence}
+                        for p in r.predictions
+                    ],
+                }
+                for r in job_results.results
+            ],
+        }
+
+        if output:
+            with open(output, "w") as f:
+                json.dump(result_data, f, indent=2)
+            click.echo(f"Predictions saved to {output}")
+        else:
+            click.echo(json.dumps(result_data, indent=2))
+
+    except MicroCafeError as e:
+        click.echo(f"Error: {e.message}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()