seqevi 0.3.2__tar.gz → 0.3.4__tar.gz

{seqevi-0.3.2 → seqevi-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seqevi
-Version: 0.3.2
+Version: 0.3.4
 Summary: Content-addressed, reusable protein sequence annotation evidence.
 Author-Email: Fuqing Zhang <fu.qing.zhang.work@gmail.com>, FuqingZhang <103730099+FuqingZh@users.noreply.github.com>
 License-Expression: MIT
@@ -45,11 +45,11 @@ single-file DuckDB result for the current FASTA.
 ## Status
 
 The target architecture and v1.1 result contracts are approved. The SeqEvi
-The 0.3.2 candidate source tree uses strict protein sequence identity, the single-host
+0.3.4 source tree uses strict protein sequence identity, the single-host
 SQLite/POSIX Store, the external tool runner, exact cache-miss orchestration,
 and atomic DuckDB result materialization.
 
-SeqEvi 0.3.2 provides managed setup for dbCAN only. The `eggnog` and
+SeqEvi 0.3.4 provides managed setup for dbCAN only. The `eggnog` and
 `interpro-pfam` adapters remain supported through explicit runtimes and named
 host profiles; managed setup for them is later feature work. The
 [Slice D gate record](docs/benchmarks/20260806-v1.4-dbcan-public-release-gate.md)

{seqevi-0.3.2 → seqevi-0.3.4}/README.md

@@ -11,11 +11,11 @@ single-file DuckDB result for the current FASTA.
 ## Status
 
 The target architecture and v1.1 result contracts are approved. The SeqEvi
-The 0.3.2 candidate source tree uses strict protein sequence identity, the single-host
+0.3.4 source tree uses strict protein sequence identity, the single-host
 SQLite/POSIX Store, the external tool runner, exact cache-miss orchestration,
 and atomic DuckDB result materialization.
 
-SeqEvi 0.3.2 provides managed setup for dbCAN only. The `eggnog` and
+SeqEvi 0.3.4 provides managed setup for dbCAN only. The `eggnog` and
 `interpro-pfam` adapters remain supported through explicit runtimes and named
 host profiles; managed setup for them is later feature work. The
 [Slice D gate record](docs/benchmarks/20260806-v1.4-dbcan-public-release-gate.md)

{seqevi-0.3.2 → seqevi-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "seqevi"
-version = "0.3.2"
+version = "0.3.4"
 description = "Content-addressed, reusable protein sequence annotation evidence."
 authors = [
     { name = "Fuqing Zhang", email = "fu.qing.zhang.work@gmail.com" },

{seqevi-0.3.2 → seqevi-0.3.4}/src/seqevi/__init__.py

@@ -1,6 +1,6 @@
 """Content-addressed protein sequence annotation evidence."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 from .api import annotate, scan_annotations
 

{seqevi-0.3.2 → seqevi-0.3.4}/src/seqevi/annotate.py

@@ -26,6 +26,14 @@ from .evidence import (
     EvidenceSource,
     EvidenceStatus,
 )
+from .progress import (
+    ProgressEvent,
+    ProgressPhase,
+    ProgressSink,
+    ProgressState,
+    ProgressUnit,
+    emit_progress,
+)
 from .result import RESULT_FORMAT_VERSION, materialize_result_database
 from .runner import ToolCancelledError, ToolCommand, ToolRunResult, ToolRunner
 from .sequence import (
@@ -134,6 +142,7 @@ def run_annotation(
     threads: int = 1,
     output_format: Literal["duckdb"] = "duckdb",
     result_metadata: Mapping[str, str] | None = None,
+    progress_sink: ProgressSink | None = None,
 ) -> AnnotationSummary:
     """Resolve exact evidence, compute misses, and publish one DuckDB result."""
 
@@ -148,11 +157,30 @@ def run_annotation(
 
     started = time.perf_counter()
     fasta_started = time.perf_counter()
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.STAGING,
+            ProgressState.STARTED,
+            "staging FASTA",
+        ),
+    )
     fasta_stage_root = Path(
         tempfile.mkdtemp(prefix=".seqevi-fasta-", dir=output_dir.parent)
     )
     stage = stage_fasta(fasta_path, fasta_stage_root)
     fasta_staging_seconds = time.perf_counter() - fasta_started
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.STAGING,
+            ProgressState.COMPLETED,
+            "FASTA staged",
+            completed=stage.unique_sequences,
+            total=stage.unique_sequences,
+            unit=ProgressUnit.SEQUENCES,
+        ),
+    )
     try:
         work_dir = Path(
             tempfile.mkdtemp(prefix=".seqevi-annotate-", dir=output_dir.parent)
@@ -201,6 +229,14 @@ def run_annotation(
                 claim_session.cancellation_signal if claim_session is not None else None
             ),
         )
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.STORE_LOOKUP,
+                ProgressState.STARTED,
+                "store lookup",
+            ),
+        )
 
         for identity_batch in batched(iter_staged_identities(stage), _STORE_BATCH_SIZE):
             queries = tuple(
@@ -238,6 +274,17 @@ def run_annotation(
                 cached = store.lookup_many(queries)
             store_lookup_seconds += time.perf_counter() - lookup_started
             lookup_batches += 1
+            emit_progress(
+                progress_sink,
+                ProgressEvent(
+                    ProgressPhase.STORE_LOOKUP,
+                    ProgressState.RUNNING,
+                    "store lookup",
+                    completed=len(keys_by_sequence_id),
+                    total=stage.unique_sequences,
+                    unit=ProgressUnit.SEQUENCES,
+                ),
+            )
             if claim_session is None:
                 for query in queries:
                     if query.key not in cached:
@@ -259,6 +306,7 @@ def run_annotation(
                     timeout_seconds=timeout_seconds,
                     threads=threads,
                     claim_session=claim_session,
+                    progress_sink=progress_sink,
                 )
                 commit_batches += batch_metrics.commit_batches
                 adapter_seconds += batch_metrics.adapter_seconds
@@ -281,6 +329,7 @@ def run_annotation(
                 timeout_seconds=timeout_seconds,
                 threads=threads,
                 claim_session=claim_session,
+                progress_sink=progress_sink,
             )
             commit_batches += batch_metrics.commit_batches
             adapter_seconds += batch_metrics.adapter_seconds
@@ -288,7 +337,16 @@ def run_annotation(
             existing_finalizations += batch_metrics.existing_finalizations
             computed_ids.difference_update(batch_metrics.peer_completed_sequence_ids)
 
+        waited_for_claim = bool(busy_queries)
         while busy_queries:
+            emit_progress(
+                progress_sink,
+                ProgressEvent(
+                    ProgressPhase.CLAIM_WAIT,
+                    ProgressState.RUNNING,
+                    "waiting for peer claims",
+                ),
+            )
             time.sleep(busy_retry_after or 1.0)
             next_retry_after: float | None = None
             next_busy = []
@@ -328,6 +386,7 @@ def run_annotation(
                     timeout_seconds=timeout_seconds,
                     threads=threads,
                     claim_session=claim_session,
+                    progress_sink=progress_sink,
                 )
                 commit_batches += batch_metrics.commit_batches
                 adapter_seconds += batch_metrics.adapter_seconds
@@ -339,8 +398,38 @@ def run_annotation(
             busy_queries = next_busy
             busy_retry_after = next_retry_after
 
+        if waited_for_claim:
+            emit_progress(
+                progress_sink,
+                ProgressEvent(
+                    ProgressPhase.CLAIM_WAIT,
+                    ProgressState.COMPLETED,
+                    "peer claims resolved",
+                ),
+            )
+
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.STORE_LOOKUP,
+                ProgressState.COMPLETED,
+                "store lookup completed",
+                completed=stage.unique_sequences,
+                total=stage.unique_sequences,
+                unit=ProgressUnit.SEQUENCES,
+            ),
+        )
+
         if claim_session is not None:
             claim_session.raise_if_lost()
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.STORE_FETCH,
+                ProgressState.STARTED,
+                "fetching evidence",
+            ),
+        )
         fetch_started = time.perf_counter()
         fetched_by_key = store.fetch_many(keys_by_sequence_id.values())
         store_fetch_seconds = time.perf_counter() - fetch_started
@@ -351,6 +440,17 @@ def run_annotation(
             raise AnnotationError(
                 f"Store did not expose {len(missing_keys)} terminal evidence records"
             )
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.STORE_FETCH,
+                ProgressState.COMPLETED,
+                "evidence fetched",
+                completed=len(fetched_by_key),
+                total=stage.unique_sequences,
+                unit=ProgressUnit.SEQUENCES,
+            ),
+        )
         fetched_by_sequence_id = {
             key.sequence_id: fetched for key, fetched in fetched_by_key.items()
         }
@@ -366,6 +466,14 @@ def run_annotation(
         statuses = [
             fetched.record.status for fetched in fetched_by_sequence_id.values()
         ]
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.PACKAGE,
+                ProgressState.STARTED,
+                "packaging result",
+            ),
+        )
         package_started = time.perf_counter()
         if output_format != "duckdb":
             raise AnnotationError(f"unsupported output format: {output_format}")
@@ -413,6 +521,17 @@ def run_annotation(
                 unlink_owned_output()
                 raise
         package_seconds = time.perf_counter() - package_started
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.PACKAGE,
+                ProgressState.COMPLETED,
+                "result packaged",
+                completed=stage.unique_sequences,
+                total=stage.unique_sequences,
+                unit=ProgressUnit.SEQUENCES,
+            ),
+        )
     except BaseException as error:
         primary_failure = error
         if not isinstance(error, Exception):
@@ -538,6 +657,7 @@ def _run_annotation_batch(
     timeout_seconds: float | None,
     threads: int,
     claim_session: ClaimSession | None = None,
+    progress_sink: ProgressSink | None = None,
 ) -> _BatchMetrics:
     batch_dir = work_dir / f"batch-{batch_number:06d}"
     batch_dir.mkdir()
@@ -546,6 +666,15 @@ def _run_annotation_batch(
         claim_session.raise_if_lost()
     with misses_fasta.open("w", encoding="ascii", newline="\n") as handle:
         handle.writelines(iter_fasta_lines(identities))
+    tool_message = f"{_tool_display_name(adapter)} · tool batch {batch_number}"
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.TOOL,
+            ProgressState.STARTED,
+            f"{tool_message} running",
+        ),
+    )
     adapter_started = time.perf_counter()
     try:
         batch = adapter.run_batch(
@@ -561,12 +690,31 @@ def _run_annotation_batch(
             claim_session.raise_if_lost()
         raise
     adapter_seconds = time.perf_counter() - adapter_started
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.TOOL,
+            ProgressState.COMPLETED,
+            f"{tool_message} completed",
+            completed=len(identities),
+            total=len(identities),
+            unit=ProgressUnit.SEQUENCES,
+        ),
+    )
     if claim_session is not None:
         claim_session.raise_if_lost()
     commits = _build_commits(batch=batch, identities=identities, adapter=adapter)
     batches = 0
     peer_completed_sequence_ids: set[str] = set()
     existing_finalizations = 0
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.STORE_COMMIT,
+            ProgressState.STARTED,
+            f"committing tool batch {batch_number}",
+        ),
+    )
     commit_started = time.perf_counter()
     for commit_batch in batched(commits, _STORE_BATCH_SIZE):
         if claim_session is None:
@@ -585,6 +733,17 @@ def _run_annotation_batch(
                 outcome is CommitOutcome.EXISTING for outcome in outcomes
             )
             batches += 1
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.STORE_COMMIT,
+            ProgressState.COMPLETED,
+            f"tool batch {batch_number} committed",
+            completed=len(identities),
+            total=len(identities),
+            unit=ProgressUnit.SEQUENCES,
+        ),
+    )
     return _BatchMetrics(
         commit_batches=batches,
         adapter_seconds=adapter_seconds,
@@ -594,6 +753,14 @@ def _run_annotation_batch(
     )
 
 
+def _tool_display_name(adapter: AnnotationAdapter) -> str:
+    return {
+        "eggnog": "eggNOG-mapper",
+        "interpro-pfam": "InterProScan/Pfam",
+        "dbcan-cazyme": "dbCAN",
+    }.get(adapter.contract.name, adapter.contract.name)
+
+
 def _build_commits(
     *,
     batch: AdapterBatchResult,

{seqevi-0.3.2 → seqevi-0.3.4}/src/seqevi/api.py

@@ -24,6 +24,13 @@ from .execution_profile import (
     load_execution_profile,
     load_named_profile,
 )
+from .progress import (
+    ProgressEvent,
+    ProgressPhase,
+    ProgressSink,
+    ProgressState,
+    emit_progress,
+)
 from .result import RESULT_FORMAT_VERSION, scan_annotations as _scan_annotations
 from .store import open_evidence_store
 
@@ -162,7 +169,16 @@ def _run_annotation_application(
     threads: int | None,
     timeout_seconds: float | None,
     adapter_factory: Callable[[AdapterConfiguration], AnnotationAdapter] | None = None,
+    progress_sink: ProgressSink | None = None,
 ) -> AnnotationInvocation:
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.ANNOTATION,
+            ProgressState.STARTED,
+            "starting annotation",
+        ),
+    )
     inputs = resolve_annotation_inputs(
         profile=profile,
         config=config,
@@ -174,6 +190,14 @@ def _run_annotation_application(
         timeout_seconds=timeout_seconds,
     )
     if inputs.profile is not None and inputs.profile.version == 2:
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.ANNOTATION,
+                ProgressState.RUNNING,
+                "managed annotation running",
+            ),
+        )
         managed = run_oci_annotation(
             fasta=fasta.expanduser().resolve(),
             output=output.expanduser().resolve(),
@@ -182,12 +206,29 @@ def _run_annotation_application(
             threads=inputs.threads,
             timeout_seconds=inputs.timeout_seconds,
         )
-        return AnnotationInvocation(
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.FINALIZATION,
+                ProgressState.STARTED,
+                "validating result",
+            ),
+        )
+        invocation = AnnotationInvocation(
             relation=_scan_annotations(managed.output),
             summary=managed.summary,
             adapter=managed.adapter,
             result_schema_id=managed.result_schema_id,
         )
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.COMPLETED,
+                ProgressState.COMPLETED,
+                "annotation completed",
+            ),
+        )
+        return invocation
     if inputs.executable is None:
         raise AnnotationError("local annotation requires an executable")
     factory = create_adapter if adapter_factory is None else adapter_factory
@@ -210,13 +251,31 @@ def _run_annotation_application(
             threads=inputs.threads,
             output_format="duckdb",
             result_metadata=metadata,
+            progress_sink=progress_sink,
+        )
+        emit_progress(
+            progress_sink,
+            ProgressEvent(
+                ProgressPhase.FINALIZATION,
+                ProgressState.STARTED,
+                "closing Store and validating result",
+            ),
         )
-    return AnnotationInvocation(
+    invocation = AnnotationInvocation(
         relation=_scan_annotations(summary.output_dir),
         summary=summary,
         adapter=metadata["Adapter"],
         result_schema_id=metadata["ResultSchemaID"],
     )
+    emit_progress(
+        progress_sink,
+        ProgressEvent(
+            ProgressPhase.COMPLETED,
+            ProgressState.COMPLETED,
+            "annotation completed",
+        ),
+    )
+    return invocation
 
 
 def resolve_annotation_inputs(

{seqevi-0.3.2 → seqevi-0.3.4}/src/seqevi/cli.py

@@ -3,10 +3,14 @@
 from __future__ import annotations
 
 import json
+import logging
 import shutil
 import sys
+import threading
+import time
+from collections.abc import Callable
 from pathlib import Path
-from typing import Annotated, NoReturn
+from typing import Annotated, NoReturn, TextIO
 
 import typer
 
@@ -27,8 +31,12 @@ from .execution_profile import (
     profile_example,
     redacted_effective_configuration,
 )
+from .progress import ProgressEvent, ProgressState
 from .resource_lock import resource_lock_path
 
+_LOGGER = logging.getLogger(__name__)
+_PROGRESS_REFRESH_SECONDS = 1.0
+
 app = typer.Typer(
     name="seqevi",
     help="Content-addressed protein sequence annotation evidence.",
@@ -63,6 +71,116 @@ def _resolve_executable(value: str) -> Path:
     return Path(resolved).resolve()
 
 
+class _ProgressRenderer:
+    """Render the latest private progress event on one transient stderr line."""
+
+    def __init__(
+        self,
+        *,
+        stream: TextIO,
+        refresh_seconds: float = _PROGRESS_REFRESH_SECONDS,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._stream = stream
+        self._refresh_seconds = refresh_seconds
+        self._monotonic = monotonic
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._latest: ProgressEvent | None = None
+        self._phase_started = monotonic()
+        self._line_visible = False
+        self._thread: threading.Thread | None = None
+
+    def __call__(self, event: ProgressEvent) -> None:
+        now = self._monotonic()
+        with self._lock:
+            if (
+                self._latest is None
+                or self._latest.phase is not event.phase
+                or event.state is ProgressState.STARTED
+            ):
+                self._phase_started = now
+            self._latest = event
+            self._write_locked(now)
+            if self._thread is None:
+                self._thread = threading.Thread(
+                    target=self._refresh,
+                    name="seqevi-progress",
+                    daemon=True,
+                )
+                self._thread.start()
+
+    def close(self) -> None:
+        """Stop the timer and remove the transient line before final output."""
+
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+        with self._lock:
+            if self._line_visible:
+                self._stream.write("\r\x1b[K")
+                self._stream.flush()
+                self._line_visible = False
+
+    def _refresh(self) -> None:
+        try:
+            while not self._stop.wait(self._refresh_seconds):
+                with self._lock:
+                    self._write_locked(self._monotonic())
+        except Exception:
+            _LOGGER.exception("annotation progress renderer refresh failed")
+
+    def _write_locked(self, now: float) -> None:
+        if self._latest is None:
+            return
+        elapsed = (
+            self._latest.elapsed_seconds
+            if self._latest.elapsed_seconds is not None
+            else max(0.0, now - self._phase_started)
+        )
+        text = _render_progress_event(self._latest, elapsed_seconds=elapsed)
+        self._stream.write(f"\r{text}\x1b[K")
+        self._stream.flush()
+        self._line_visible = True
+
+
+def _render_progress_event(event: ProgressEvent, *, elapsed_seconds: float) -> str:
+    parts = [f"[seqevi] {event.message}"]
+    if event.completed is not None:
+        assert event.total is not None
+        assert event.unit is not None
+        fraction = f"{event.completed:,}/{event.total:,} {event.unit.value}"
+        percentage = 100.0 if event.total == 0 else event.completed / event.total * 100
+        parts.append(f"{fraction} ({percentage:.0f}%)")
+    if event.state is not ProgressState.COMPLETED:
+        parts.append(_format_elapsed(elapsed_seconds))
+    return " · ".join(parts)
+
+
+def _format_elapsed(elapsed_seconds: float) -> str:
+    seconds = int(max(0.0, elapsed_seconds))
+    hours, remainder = divmod(seconds, 3_600)
+    minutes, seconds = divmod(remainder, 60)
+    if hours:
+        return f"{hours}h{minutes:02d}m{seconds:02d}s"
+    if minutes:
+        return f"{minutes}m{seconds:02d}s"
+    return f"{seconds}s"
+
+
+def _stderr_is_interactive() -> bool:
+    return sys.stderr.isatty()
+
+
+def _close_progress_renderer(renderer: _ProgressRenderer | None) -> None:
+    if renderer is None:
+        return
+    try:
+        renderer.close()
+    except Exception:
+        _LOGGER.exception("annotation progress renderer shutdown failed")
+
+
 @app.callback()
 def root(
     context: typer.Context,
@@ -177,6 +295,13 @@ def annotate_command(
             help="Worker threads; overrides the profile default.",
         ),
     ] = None,
+    progress: Annotated[
+        bool,
+        typer.Option(
+            "--progress",
+            help="Show interactive SeqEvi phase and liveness progress on stderr.",
+        ),
+    ] = False,
     json_output: Annotated[
         bool,
         typer.Option(
@@ -187,6 +312,11 @@ def annotate_command(
 ) -> None:
     """Reuse exact evidence and publish one immutable DuckDB result."""
 
+    renderer = (
+        _ProgressRenderer(stream=sys.stderr)
+        if progress and not json_output and _stderr_is_interactive()
+        else None
+    )
     try:
         invocation = _run_annotation_application(
             fasta=fasta,
@@ -200,8 +330,11 @@ def annotate_command(
             threads=threads,
             timeout_seconds=timeout_seconds,
             adapter_factory=create_adapter,
+            progress_sink=renderer,
         )
     except (AnnotationError, FastaValidationError, StoreError) as error:
+        _close_progress_renderer(renderer)
+        renderer = None
         if json_output:
             typer.echo(
                 json.dumps(
@@ -218,6 +351,8 @@ def annotate_command(
         else:
             typer.echo(f"Error: {error}", err=True)
         raise typer.Exit(code=1) from error
+    finally:
+        _close_progress_renderer(renderer)
 
     summary = invocation.summary
     if json_output: