plasmid-oracle 0.2.0a0__py3-none-any.whl

plasmid_oracle/__init__.py

@@ -0,0 +1,96 @@
+"""Evidence-first plasmid annotation and characterization."""
+
+from plasmid_oracle.api import annotate, annotate_async, plasmid
+from plasmid_oracle.databases import DatabaseSetupResult, setup
+from plasmid_oracle.errors import (
+    InvalidLocationError,
+    InvalidProviderResultError,
+    InvalidSequenceError,
+    InvalidSerializedPlasmidError,
+    PlasmidOracleError,
+    ProviderExecutionError,
+    ProviderUnavailableError,
+)
+from plasmid_oracle.model import (
+    AnalysisManifest,
+    Annotation,
+    AnnotationSource,
+    Characterization,
+    CharacterizationCall,
+    EvidenceMetrics,
+    Integrity,
+    Location,
+    Plasmid,
+    ProviderRun,
+    ProviderStatus,
+    QualityFlag,
+    ResolutionConflict,
+    ResolutionStatus,
+    ResolvedAnnotation,
+    SequenceInfo,
+    SequenceWarning,
+    Span,
+    Strand,
+    Topology,
+)
+from plasmid_oracle.pipeline import (
+    AnnotationProvider,
+    DoctorReport,
+    ProviderContext,
+    ProviderDiagnostic,
+    ProviderResult,
+    ProviderSpec,
+    doctor,
+)
+from plasmid_oracle.resolution import resolve_annotations
+from plasmid_oracle.serialization import from_dict, from_json, to_dict, to_json
+
+__version__ = "0.2.0a0"
+
+__all__ = [
+    "AnalysisManifest",
+    "Annotation",
+    "AnnotationProvider",
+    "AnnotationSource",
+    "Characterization",
+    "CharacterizationCall",
+    "DatabaseSetupResult",
+    "DoctorReport",
+    "EvidenceMetrics",
+    "Integrity",
+    "InvalidLocationError",
+    "InvalidProviderResultError",
+    "InvalidSerializedPlasmidError",
+    "InvalidSequenceError",
+    "Location",
+    "Plasmid",
+    "PlasmidOracleError",
+    "ProviderContext",
+    "ProviderDiagnostic",
+    "ProviderExecutionError",
+    "ProviderUnavailableError",
+    "ProviderResult",
+    "ProviderRun",
+    "ProviderSpec",
+    "ProviderStatus",
+    "QualityFlag",
+    "ResolutionConflict",
+    "ResolutionStatus",
+    "ResolvedAnnotation",
+    "SequenceInfo",
+    "SequenceWarning",
+    "Span",
+    "Strand",
+    "Topology",
+    "__version__",
+    "annotate",
+    "annotate_async",
+    "doctor",
+    "from_dict",
+    "from_json",
+    "plasmid",
+    "resolve_annotations",
+    "setup",
+    "to_dict",
+    "to_json",
+]

plasmid_oracle/__main__.py

@@ -0,0 +1,3 @@
+from plasmid_oracle.cli import main
+
+raise SystemExit(main())

plasmid_oracle/_immutability.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, cast
+
+
+def freeze_value(value: Any) -> Any:
+    """Recursively freeze common mutable container values."""
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: freeze_value(item) for key, item in value.items()})
+    if isinstance(value, list | tuple):
+        return tuple(freeze_value(item) for item in value)
+    if isinstance(value, set | frozenset):
+        return frozenset(freeze_value(item) for item in value)
+    return value
+
+
+def freeze_mapping(value: Mapping[str, object] | None) -> Mapping[str, object]:
+    if value is None:
+        return MappingProxyType({})
+    return cast(Mapping[str, object], freeze_value(value))

plasmid_oracle/api.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable, Mapping
+from functools import partial
+from pathlib import Path
+
+from plasmid_oracle.model import (
+    AnalysisManifest,
+    Characterization,
+    Plasmid,
+    SequenceInfo,
+    Topology,
+)
+from plasmid_oracle.pipeline import (
+    PIPELINE_VERSION,
+    AnnotationProvider,
+    run_pipeline,
+)
+from plasmid_oracle.providers.builtin import providers_for_mode
+
+_VALID_MODES = frozenset({"minimal", "fast", "standard", "deep"})
+
+
+def plasmid(
+    *,
+    seq: str,
+    topology: Topology | str = Topology.CIRCULAR,
+    source_metadata: Mapping[str, object] | None = None,
+) -> Plasmid:
+    return Plasmid(
+        sequence=SequenceInfo.from_raw(seq, topology=topology),
+        evidence=(),
+        annotations=(),
+        characterization=Characterization(),
+        source_metadata=source_metadata or {},
+        analysis=AnalysisManifest(
+            pipeline_version=PIPELINE_VERSION,
+            mode="none",
+        ),
+    )
+
+
+def annotate(
+    *,
+    seq: str,
+    topology: Topology | str = Topology.CIRCULAR,
+    mode: str = "minimal",
+    providers: Iterable[AnnotationProvider] | None = None,
+    source_metadata: Mapping[str, object] | None = None,
+    strict: bool = True,
+    threads: int = 1,
+    timeout_seconds: float = 600.0,
+    cache: bool = False,
+    cache_dir: Path | None = None,
+    provider_workers: int = 1,
+) -> Plasmid:
+    if mode not in _VALID_MODES:
+        choices = ", ".join(sorted(_VALID_MODES))
+        raise ValueError(f"Unsupported annotation mode {mode!r}; expected one of: {choices}")
+
+    normalized = plasmid(
+        seq=seq,
+        topology=topology,
+        source_metadata=source_metadata,
+    )
+    selected_providers = providers_for_mode(mode) if providers is None else tuple(providers)
+    return run_pipeline(
+        normalized,
+        mode=mode,
+        providers=selected_providers,
+        strict=strict,
+        threads=threads,
+        timeout_seconds=timeout_seconds,
+        cache=cache,
+        cache_dir=cache_dir,
+        provider_workers=provider_workers,
+    )
+
+
+async def annotate_async(
+    *,
+    seq: str,
+    topology: Topology | str = Topology.CIRCULAR,
+    mode: str = "minimal",
+    providers: Iterable[AnnotationProvider] | None = None,
+    source_metadata: Mapping[str, object] | None = None,
+    strict: bool = True,
+    threads: int = 1,
+    timeout_seconds: float = 600.0,
+    cache: bool = False,
+    cache_dir: Path | None = None,
+    provider_workers: int = 1,
+) -> Plasmid:
+    operation = partial(
+        annotate,
+        seq=seq,
+        topology=topology,
+        mode=mode,
+        providers=providers,
+        source_metadata=source_metadata,
+        strict=strict,
+        threads=threads,
+        timeout_seconds=timeout_seconds,
+        cache=cache,
+        cache_dir=cache_dir,
+        provider_workers=provider_workers,
+    )
+    return await asyncio.to_thread(operation)

plasmid_oracle/cli.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from plasmid_oracle import __version__
+from plasmid_oracle.api import annotate
+from plasmid_oracle.databases import setup as setup_database
+from plasmid_oracle.errors import PlasmidOracleError
+from plasmid_oracle.pipeline import DoctorReport, doctor
+from plasmid_oracle.reporting import render_text
+from plasmid_oracle.serialization import to_json
+
+
+def _single_fasta(path: Path) -> tuple[str, str]:
+    identifier: str | None = None
+    sequence_lines: list[str] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith(">"):
+            if identifier is not None:
+                raise ValueError("FASTA input must contain exactly one sequence")
+            identifier = line[1:].split(maxsplit=1)[0] or path.stem
+        elif line.strip():
+            if identifier is None:
+                raise ValueError("FASTA sequence data appeared before its header")
+            sequence_lines.append(line.strip())
+    if identifier is None or not sequence_lines:
+        raise ValueError("FASTA input does not contain a sequence")
+    return identifier, "".join(sequence_lines)
+
+
+def _doctor_payload(report: DoctorReport) -> dict[str, object]:
+    return {
+        "mode": report.mode,
+        "ready": report.ready,
+        "providers": [
+            {
+                "name": provider.name,
+                "available": provider.available,
+                "provider_version": provider.provider_version,
+                "tool_version": provider.tool_version,
+                "database_versions": dict(provider.database_versions),
+                "issues": list(provider.issues),
+            }
+            for provider in report.providers
+        ],
+    }
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="plasmid-oracle",
+        description="Evidence-first plasmid annotation and characterization",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    annotate_parser = commands.add_parser("annotate", help="Annotate one plasmid")
+    source = annotate_parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--sequence", help="Raw DNA sequence")
+    source.add_argument("--fasta", type=Path, help="Single-record FASTA file")
+    annotate_parser.add_argument(
+        "--topology",
+        choices=("circular", "linear"),
+        default="circular",
+    )
+    annotate_parser.add_argument(
+        "--mode",
+        choices=("minimal", "fast", "standard", "deep"),
+        default="minimal",
+    )
+    annotate_parser.add_argument("--threads", type=int, default=1)
+    annotate_parser.add_argument(
+        "--provider-workers",
+        type=int,
+        default=1,
+        help="Maximum providers to run concurrently within the total thread budget",
+    )
+    annotate_parser.add_argument("--timeout", type=float, default=600.0)
+    annotate_parser.add_argument(
+        "--cache",
+        action="store_true",
+        help="Reuse results with matching sequence, tool, database, and parameter identity",
+    )
+    annotate_parser.add_argument("--cache-dir", type=Path)
+    annotate_parser.add_argument(
+        "--tolerant",
+        action="store_true",
+        help="Return partial results and record unavailable or failed providers",
+    )
+    annotate_parser.add_argument("--output", type=Path)
+    annotate_parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        help="Output format; defaults to text on stdout and JSON for files",
+    )
+
+    doctor_parser = commands.add_parser("doctor", help="Check provider readiness")
+    doctor_parser.add_argument(
+        "--mode",
+        choices=("minimal", "fast", "standard", "deep"),
+        default="standard",
+    )
+    doctor_parser.add_argument("--json", action="store_true")
+    doctor_parser.add_argument("--threads", type=int, default=1)
+
+    setup_parser = commands.add_parser(
+        "setup",
+        help="Install or update an external provider database",
+    )
+    setup_parser.add_argument(
+        "component",
+        choices=("plannotate", "amrfinderplus", "mob-suite"),
+    )
+    setup_parser.add_argument("--force", action="store_true")
+    setup_parser.add_argument(
+        "--mob-database",
+        type=Path,
+        help="MOB-suite database directory",
+    )
+    setup_parser.add_argument("--timeout", type=float, default=7200.0)
+    setup_parser.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = _parser().parse_args(argv)
+    try:
+        if arguments.command == "doctor":
+            report = doctor(mode=arguments.mode, threads=arguments.threads)
+            payload = _doctor_payload(report)
+            if arguments.json:
+                print(json.dumps(payload, indent=2, sort_keys=True))
+            else:
+                print(f"Mode: {report.mode} ({'ready' if report.ready else 'not ready'})")
+                for provider in report.providers:
+                    state = "ready" if provider.available else "unavailable"
+                    print(f"{provider.name}: {state}")
+                    for issue in provider.issues:
+                        print(f"  {issue}")
+            return 0 if report.ready else 1
+
+        if arguments.command == "setup":
+            result = setup_database(
+                arguments.component,
+                force=arguments.force,
+                mob_database_dir=arguments.mob_database,
+                timeout_seconds=arguments.timeout,
+            )
+            payload = {
+                "component": result.component,
+                "path": str(result.path) if result.path is not None else None,
+                "detail": result.detail,
+            }
+            if arguments.json:
+                print(json.dumps(payload, indent=2, sort_keys=True))
+            else:
+                print(result.detail)
+                if result.path is not None:
+                    print(f"Path: {result.path}")
+            return 0
+
+        metadata: dict[str, object] = {}
+        sequence = arguments.sequence
+        if arguments.fasta is not None:
+            identifier, sequence = _single_fasta(arguments.fasta)
+            metadata["id"] = identifier
+            metadata["source"] = str(arguments.fasta)
+        assert sequence is not None
+        plasmid = annotate(
+            seq=sequence,
+            topology=arguments.topology,
+            mode=arguments.mode,
+            source_metadata=metadata,
+            strict=not arguments.tolerant,
+            threads=arguments.threads,
+            timeout_seconds=arguments.timeout,
+            cache=arguments.cache,
+            cache_dir=arguments.cache_dir,
+            provider_workers=arguments.provider_workers,
+        )
+        output_format = arguments.format or ("json" if arguments.output is not None else "text")
+        output = to_json(plasmid) if output_format == "json" else render_text(plasmid)
+        if arguments.output is None:
+            print(output)
+        else:
+            arguments.output.parent.mkdir(parents=True, exist_ok=True)
+            descriptor, temporary_name = tempfile.mkstemp(
+                prefix=f".{arguments.output.name}.",
+                dir=arguments.output.parent,
+                text=True,
+            )
+            try:
+                with os.fdopen(descriptor, "w", encoding="utf-8") as temporary:
+                    temporary.write(output + "\n")
+                    temporary.flush()
+                    os.fsync(temporary.fileno())
+                os.replace(temporary_name, arguments.output)
+            except BaseException:
+                Path(temporary_name).unlink(missing_ok=True)
+                raise
+        return 0
+    except (PlasmidOracleError, ValueError, OSError) as error:
+        print(f"plasmid-oracle: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plasmid_oracle/databases/__init__.py

@@ -0,0 +1,3 @@
+from plasmid_oracle.databases.setup import DatabaseSetupResult, setup
+
+__all__ = ["DatabaseSetupResult", "setup"]

plasmid_oracle/databases/setup.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from plasmid_oracle.errors import ProviderUnavailableError
+from plasmid_oracle.execution import ProcessRunner, SubprocessRunner
+from plasmid_oracle.providers._external import (
+    ExecutableResolver,
+    default_executable_resolver,
+    require_executable,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseSetupResult:
+    component: str
+    path: Path | None
+    detail: str
+
+
+def _setup_plannotate(*, force: bool) -> DatabaseSetupResult:
+    if importlib.util.find_spec("plannotate") is None:
+        raise ProviderUnavailableError(
+            "pLannotate is not installed; install plasmid-oracle[plannotate]"
+        )
+    resources = importlib.import_module("plannotate.resources")
+    auto_download = os.environ.get("PLANNOTATE_AUTO_DOWNLOAD")
+    os.environ["PLANNOTATE_AUTO_DOWNLOAD"] = "1"
+    try:
+        installed = Path(resources.download_db(force=force))
+    finally:
+        if auto_download is None:
+            os.environ.pop("PLANNOTATE_AUTO_DOWNLOAD", None)
+        else:
+            os.environ["PLANNOTATE_AUTO_DOWNLOAD"] = auto_download
+    return DatabaseSetupResult(
+        component="plannotate",
+        path=installed,
+        detail="pLannotate database installed and checksum-verified by pLannotate",
+    )
+
+
+def setup(
+    component: str,
+    *,
+    force: bool = False,
+    mob_database_dir: Path | None = None,
+    runner: ProcessRunner | None = None,
+    executable_resolver: ExecutableResolver = default_executable_resolver,
+    timeout_seconds: float = 7200,
+) -> DatabaseSetupResult:
+    normalized = component.strip().lower().replace("-", "_")
+    process_runner = runner or SubprocessRunner(default_timeout_seconds=timeout_seconds)
+
+    if normalized == "plannotate":
+        return _setup_plannotate(force=force)
+
+    if normalized in {"amrfinder", "amrfinderplus"}:
+        executable = require_executable("amrfinder", executable_resolver)
+        command = [executable, "--force_update" if force else "--update"]
+        process_runner.run(command, timeout_seconds=timeout_seconds)
+        return DatabaseSetupResult(
+            component="amrfinderplus",
+            path=None,
+            detail="AMRFinderPlus database updated in its upstream default directory",
+        )
+
+    if normalized in {"mob", "mob_suite"}:
+        database_dir = mob_database_dir
+        if database_dir is None:
+            configured = os.environ.get("PLASMID_ORACLE_MOB_DATABASE")
+            database_dir = Path(configured) if configured else None
+        if database_dir is None:
+            raise ValueError(
+                "MOB-suite setup requires mob_database_dir or PLASMID_ORACLE_MOB_DATABASE"
+            )
+        database_dir = database_dir.expanduser()
+        executable = require_executable("mob_init", executable_resolver)
+        process_runner.run(
+            (
+                executable,
+                "--database_directory",
+                os.fspath(database_dir),
+            ),
+            timeout_seconds=timeout_seconds,
+        )
+        return DatabaseSetupResult(
+            component="mob_suite",
+            path=database_dir,
+            detail="MOB-suite database initialized",
+        )
+
+    raise ValueError("Unknown database component; expected plannotate, amrfinderplus, or mob_suite")

plasmid_oracle/errors.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from plasmid_oracle.model import ProviderRun
+
+
+class PlasmidOracleError(Exception):
+    """Base exception for Plasmid Oracle."""
+
+
+class InvalidSequenceError(PlasmidOracleError, ValueError):
+    """Raised when DNA cannot be normalized without changing its meaning."""
+
+
+class InvalidLocationError(PlasmidOracleError, ValueError):
+    """Raised when sequence coordinates do not form a valid location."""
+
+
+class InvalidProviderResultError(PlasmidOracleError, ValueError):
+    """Raised when a provider returns evidence outside the canonical contract."""
+
+
+class InvalidSerializedPlasmidError(PlasmidOracleError, ValueError):
+    """Raised when serialized data violates the versioned plasmid schema."""
+
+
+class ProviderUnavailableError(PlasmidOracleError, RuntimeError):
+    """Raised when a provider dependency or database is not installed."""
+
+
+class ProviderExecutionError(PlasmidOracleError):
+    """Raised when a requested provider does not complete."""
+
+    def __init__(
+        self,
+        provider_name: str,
+        provider_runs: Sequence[ProviderRun],
+    ) -> None:
+        self.provider_name = provider_name
+        self.provider_runs = tuple(provider_runs)
+        failed_run = next(
+            (run for run in reversed(self.provider_runs) if run.name == provider_name),
+            self.provider_runs[-1],
+        )
+        detail = failed_run.error or "unknown provider error"
+        super().__init__(f"Provider {provider_name!r} failed: {detail}")

plasmid_oracle/execution/__init__.py

@@ -0,0 +1,15 @@
+from plasmid_oracle.execution.process import (
+    CommandFailedError,
+    CommandTimeoutError,
+    ProcessResult,
+    ProcessRunner,
+    SubprocessRunner,
+)
+
+__all__ = [
+    "CommandFailedError",
+    "CommandTimeoutError",
+    "ProcessResult",
+    "ProcessRunner",
+    "SubprocessRunner",
+]