infinity-context 0.1.0__py3-none-any.whl

infinity_context_adapters/extraction/whisper_engine.py

@@ -0,0 +1,386 @@
+"""Optional faster-whisper ASR extraction engine for audio and video assets."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import json
+import tempfile
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any
+
+from infinity_context_core.ports.extraction import (
+    ExtractedElement,
+    ExtractionArtifactCandidate,
+    ExtractionRequest,
+    ExtractionResult,
+)
+
+from infinity_context_adapters.extraction.content import (
+    _MEDIA_TYPES,
+    ExtractionEngine,
+    SupportDecision,
+    _format_timestamp_ms,
+    _limit_text,
+    _safe_suffix,
+    _unsupported,
+)
+from infinity_context_adapters.extraction.media_tools import (
+    media_manifest_artifact,
+    probe_media_with_ffprobe,
+)
+
+_ASR_PROFILES = {
+    "asr",
+    "faster_whisper",
+    "local_asr",
+    "media_local_asr",
+}
+
+
+class FasterWhisperTranscriptionEngine(ExtractionEngine):
+    name = "faster_whisper_transcript"
+
+    def __init__(
+        self,
+        *,
+        model_name: str = "base",
+        device: str = "auto",
+        compute_type: str = "default",
+        model_factory: Callable[[str, str, str], Any] | None = None,
+    ) -> None:
+        self._model_name = model_name
+        self._device = device
+        self._compute_type = compute_type
+        self._model_factory = model_factory
+
+    async def supports(self, request: ExtractionRequest) -> SupportDecision:
+        if not _profile_wants_asr(request.parser_profile):
+            return SupportDecision(False, reason="parser_profile_not_asr")
+        if not _is_media_content_type(request.detected_content_type):
+            return SupportDecision(False, reason="not_audio_or_video")
+        if self._model_factory is not None:
+            return SupportDecision(True)
+        if _load_whisper_model_factory() is not None:
+            return SupportDecision(True)
+        return SupportDecision(False, reason="faster_whisper_not_installed")
+
+    async def extract(self, request: ExtractionRequest) -> ExtractionResult:
+        try:
+            return await asyncio.wait_for(
+                asyncio.to_thread(self._extract_sync, request),
+                timeout=max(0.001, float(request.limits.parser_timeout_seconds)),
+            )
+        except TimeoutError:
+            return _fallback_unsupported(
+                request,
+                code="asset_extraction.asr_timeout",
+                message="Local ASR transcription timed out",
+                parser_version=_faster_whisper_version(),
+                metadata={
+                    "parser_timeout_seconds": request.limits.parser_timeout_seconds,
+                },
+            )
+
+    def _extract_sync(self, request: ExtractionRequest) -> ExtractionResult:
+        probe = probe_media_with_ffprobe(request)
+        if probe.duration_seconds and probe.duration_seconds > request.limits.max_media_seconds:
+            return _fallback_unsupported(
+                request,
+                code="asset_extraction.asr_media_too_long",
+                message="Media duration exceeds local ASR limit",
+                parser_version=_faster_whisper_version(),
+                metadata={
+                    "duration_seconds": probe.duration_seconds,
+                    "max_media_seconds": request.limits.max_media_seconds,
+                },
+            )
+
+        model_factory = self._model_factory or _load_whisper_model_factory()
+        if model_factory is None:
+            return _fallback_unsupported(
+                request,
+                code="asset_extraction.asr_dependency_missing",
+                message="faster-whisper is not installed for this parser profile",
+                parser_version=None,
+            )
+
+        model_name = _model_name_for_profile(request.parser_profile, self._model_name)
+        try:
+            with tempfile.NamedTemporaryFile(suffix=_safe_suffix(request.filename)) as media_file:
+                media_file.write(request.content)
+                media_file.flush()
+                model = model_factory(model_name, self._device, self._compute_type)
+                segments, info = model.transcribe(media_file.name)
+                segment_items = tuple(_segment_item(segment) for segment in segments)
+        except Exception:
+            return _fallback_unsupported(
+                request,
+                code="asset_extraction.asr_transcription_failed",
+                message="Local ASR transcription failed",
+                parser_version=_faster_whisper_version(),
+                metadata={"asr_model": model_name},
+            )
+
+        segment_items = tuple(item for item in segment_items if item.text)
+        if not segment_items:
+            return _fallback_unsupported(
+                request,
+                code="asset_extraction.asr_no_speech",
+                message="Local ASR returned no speech segments",
+                parser_version=_faster_whisper_version(),
+                metadata={"asr_model": model_name},
+            )
+
+        lines = [f"# {request.filename.strip() or 'Media transcript'}", "## Transcript"]
+        elements: list[ExtractedElement] = []
+        for item in segment_items:
+            lines.append(
+                f"[{_format_timestamp_ms(item.start_ms)} - "
+                f"{_format_timestamp_ms(item.end_ms)}] {item.text}"
+            )
+            elements.append(
+                ExtractedElement(
+                    kind="transcript_segment",
+                    text=item.text,
+                    time_start_ms=item.start_ms,
+                    time_end_ms=item.end_ms,
+                    confidence=item.confidence,
+                    metadata={"source": self.name, "asr_model": model_name},
+                )
+            )
+
+        markdown = _limit_text("\n".join(lines), request.limits.max_output_chars)
+        transcript_text = "\n".join(
+            f"{_format_timestamp_ms(item.start_ms)} --> "
+            f"{_format_timestamp_ms(item.end_ms)}\n{item.text}"
+            for item in segment_items
+        )
+        transcript_features = _local_transcript_feature_metadata(segment_items)
+        duration_seconds = (
+            _positive_float(getattr(info, "duration", None)) or probe.duration_seconds
+        )
+        language = _safe_text(getattr(info, "language", None))
+        metadata = {
+            "byte_size": request.byte_size,
+            "mime_detected": request.detected_content_type,
+            "duration_seconds": duration_seconds,
+            "segment_count": len(elements),
+            "transcript_status": "extracted",
+            "asr_model": model_name,
+            "asr_device": self._device,
+            "asr_compute_type": self._compute_type,
+            "language_probability": _positive_float(getattr(info, "language_probability", None)),
+            "output_chars": len(markdown),
+            **transcript_features,
+            **(probe.metadata or {}),
+        }
+        transcript_json = json.dumps(
+            {
+                "schema_name": "infinity_context.transcript",
+                "schema_version": 1,
+                "asset_id": request.asset_id,
+                "filename": request.filename,
+                "content_type": request.detected_content_type,
+                "duration_seconds": duration_seconds,
+                "language": language,
+                "provider": {
+                    "name": self.name,
+                    "model": model_name,
+                    "version": _faster_whisper_version(),
+                },
+                "features": transcript_features,
+                "text": "\n".join(item.text for item in segment_items),
+                "segments": [
+                    {
+                        "text": item.text,
+                        "start_ms": item.start_ms,
+                        "end_ms": item.end_ms,
+                        "confidence": item.confidence,
+                        "speaker": None,
+                        "metadata": {"source": self.name, "asr_model": model_name},
+                    }
+                    for item in segment_items
+                ],
+                "words": [],
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        ).encode("utf-8")
+        return ExtractionResult(
+            status="succeeded",
+            normalized_content_type=request.detected_content_type,
+            title=request.filename.strip() or "Media transcript",
+            markdown=markdown,
+            elements=tuple(elements),
+            artifacts=(
+                media_manifest_artifact(
+                    request=request,
+                    probe=probe,
+                    parser_name=self.name,
+                ),
+                ExtractionArtifactCandidate(
+                    artifact_type="transcript",
+                    filename="transcript.txt",
+                    content_type="text/plain",
+                    content=transcript_text.encode("utf-8"),
+                    metadata={
+                        "parser": self.name,
+                        "segment_count": len(elements),
+                        "asr_model": model_name,
+                        **transcript_features,
+                    },
+                ),
+                ExtractionArtifactCandidate(
+                    artifact_type="transcript_json",
+                    filename="transcript.json",
+                    content_type="application/json",
+                    content=transcript_json,
+                    metadata={
+                        "parser": self.name,
+                        "segment_count": len(elements),
+                        "word_count": 0,
+                        "asr_model": model_name,
+                        **transcript_features,
+                    },
+                ),
+            ),
+            technical_metadata=metadata,
+            diagnostics={"engine": self.name},
+            language=language,
+            parser_name=self.name,
+            parser_version=_faster_whisper_version(),
+            model_version=model_name,
+        )
+
+
+def _profile_wants_asr(parser_profile: str) -> bool:
+    normalized = parser_profile.strip().lower()
+    return normalized in _ASR_PROFILES or normalized.startswith(
+        ("asr:", "faster_whisper:", "media_local_asr:")
+    )
+
+
+def _model_name_for_profile(parser_profile: str, default: str) -> str:
+    normalized = parser_profile.strip()
+    if ":" not in normalized:
+        return default
+    prefix, value = normalized.split(":", 1)
+    if prefix.lower() in {"asr", "faster_whisper", "media_local_asr"} and value.strip():
+        return value.strip()
+    return default
+
+
+def _is_media_content_type(content_type: str) -> bool:
+    return content_type in _MEDIA_TYPES or content_type.startswith(("audio/", "video/"))
+
+
+def _load_whisper_model_factory() -> Callable[[str, str, str], Any] | None:
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError:
+        return None
+
+    def build_model(model_name: str, device: str, compute_type: str) -> Any:
+        return WhisperModel(model_name, device=device, compute_type=compute_type)
+
+    return build_model
+
+
+class _SegmentItem:
+    def __init__(
+        self,
+        *,
+        start_ms: int,
+        end_ms: int,
+        text: str,
+        confidence: float | None,
+    ) -> None:
+        self.start_ms = start_ms
+        self.end_ms = end_ms
+        self.text = text
+        self.confidence = confidence
+
+
+def _segment_item(segment: object) -> _SegmentItem:
+    start_seconds = _positive_float(getattr(segment, "start", None)) or 0
+    end_seconds = _positive_float(getattr(segment, "end", None)) or start_seconds
+    return _SegmentItem(
+        start_ms=int(round(start_seconds * 1000)),
+        end_ms=int(round(end_seconds * 1000)),
+        text=_safe_text(getattr(segment, "text", None)) or "",
+        confidence=_segment_confidence(segment),
+    )
+
+
+def _local_transcript_feature_metadata(
+    segment_items: tuple[_SegmentItem, ...],
+) -> dict[str, object]:
+    features: list[str] = []
+    if segment_items:
+        features.append("segments")
+    if any(item.start_ms is not None or item.end_ms is not None for item in segment_items):
+        features.append("time_ranges")
+    return {
+        "transcript_features": features,
+        "transcript_feature_names": ",".join(features),
+        "has_time_ranges": "time_ranges" in features,
+        "has_speaker_labels": False,
+        "has_word_timestamps": False,
+    }
+
+
+def _segment_confidence(segment: object) -> float | None:
+    avg_logprob = _number(getattr(segment, "avg_logprob", None))
+    if avg_logprob is not None:
+        return max(0.0, min(1.0, 1.0 + avg_logprob))
+    no_speech_prob = _number(getattr(segment, "no_speech_prob", None))
+    if no_speech_prob is not None:
+        return max(0.0, min(1.0, 1.0 - no_speech_prob))
+    return None
+
+
+def _fallback_unsupported(
+    request: ExtractionRequest,
+    *,
+    code: str,
+    message: str,
+    parser_version: str | None,
+    metadata: dict[str, object] | None = None,
+) -> ExtractionResult:
+    result = _unsupported(
+        request,
+        parser_name=FasterWhisperTranscriptionEngine.name,
+        parser_version=parser_version,
+        code=code,
+        message=message,
+        metadata=metadata,
+    )
+    return replace(result, diagnostics={**result.diagnostics, "fallback_allowed": True})
+
+
+def _faster_whisper_version() -> str | None:
+    try:
+        return importlib.metadata.version("faster-whisper")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _positive_float(value: object) -> float | None:
+    number = _number(value)
+    if number is None or number <= 0:
+        return None
+    return number
+
+
+def _number(value: object) -> float | None:
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _safe_text(value: object) -> str | None:
+    text = str(value).strip()
+    return text or None

infinity_context_adapters/features/__init__.py

@@ -0,0 +1,7 @@
+"""Feature-owned adapter mirrors.
+
+Each package under this namespace mirrors a core feature id and owns only
+infrastructure seams for that feature.
+"""
+
+__all__ = ("context_building", "document_ingestion", "memory_facts", "memory_scopes")

infinity_context_adapters/features/context_building/__init__.py

@@ -0,0 +1,53 @@
+"""Adapter seams for the context_building feature.
+
+The adapters in this package implement the feature-owned context candidate
+port without importing provider SDKs. Postgres remains the canonical source,
+while Qdrant and Graphiti are derived candidate sources behind deferred seams.
+"""
+
+from infinity_context_core.features.context_building.public import FEATURE_ID
+
+from infinity_context_adapters.features.context_building.candidate_provider_chain import (
+    ContextCandidateProviderChain,
+    create_context_candidate_provider_chain,
+)
+from infinity_context_adapters.features.context_building.graphiti_candidate_provider import (
+    GraphitiContextCandidateProvider,
+    create_graphiti_context_candidate_provider,
+)
+from infinity_context_adapters.features.context_building.in_memory_candidate_provider import (
+    InMemoryContextCandidateProvider,
+    create_in_memory_context_candidate_provider,
+)
+from infinity_context_adapters.features.context_building.postgres_candidate_provider import (
+    PostgresContextCandidateProvider,
+    create_postgres_context_candidate_provider,
+)
+from infinity_context_adapters.features.context_building.qdrant_candidate_provider import (
+    QdrantContextCandidateProvider,
+    create_qdrant_context_candidate_provider,
+)
+from infinity_context_adapters.features.context_building.query_request import (
+    ContextCandidateAdapterQuery,
+    context_candidate_adapter_query_from_request,
+)
+from infinity_context_adapters.features.context_building.records import (
+    ContextCandidateRecord,
+)
+
+__all__ = (
+    "FEATURE_ID",
+    "ContextCandidateAdapterQuery",
+    "ContextCandidateProviderChain",
+    "ContextCandidateRecord",
+    "GraphitiContextCandidateProvider",
+    "InMemoryContextCandidateProvider",
+    "PostgresContextCandidateProvider",
+    "QdrantContextCandidateProvider",
+    "create_context_candidate_provider_chain",
+    "create_graphiti_context_candidate_provider",
+    "create_in_memory_context_candidate_provider",
+    "create_postgres_context_candidate_provider",
+    "create_qdrant_context_candidate_provider",
+    "context_candidate_adapter_query_from_request",
+)

infinity_context_adapters/features/context_building/candidate_provider_chain.py

@@ -0,0 +1,68 @@
+"""Composition seam for multiple context candidate providers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, replace
+from typing import ClassVar
+
+from infinity_context_core.features.context_building.public import (
+    FEATURE_ID,
+    ContextCandidateProviderPort,
+    ContextCandidateRequest,
+    ContextItem,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ContextCandidateProviderChain:
+    """Merge feature-owned candidate providers without exposing adapter internals."""
+
+    providers: tuple[ContextCandidateProviderPort, ...]
+
+    adapter_name: ClassVar[str] = "context_candidate_provider_chain"
+    feature_id: ClassVar[str] = FEATURE_ID
+
+    def __post_init__(self) -> None:
+        if not self.providers:
+            raise ValueError("ContextCandidateProviderChain requires at least one provider")
+
+    async def find_candidates(
+        self,
+        request: ContextCandidateRequest,
+    ) -> tuple[ContextItem, ...]:
+        selected: list[ContextItem] = []
+        seen_ids: set[str] = set()
+
+        for provider in self.providers:
+            remaining = request.limit - len(selected)
+            if remaining < 1:
+                break
+
+            provider_request = (
+                request if remaining == request.limit else replace(request, limit=remaining)
+            )
+            for item in await provider.find_candidates(provider_request):
+                if item.item_id in seen_ids:
+                    continue
+
+                selected.append(item)
+                seen_ids.add(item.item_id)
+                if len(selected) >= request.limit:
+                    return tuple(selected)
+
+        return tuple(selected)
+
+
+def create_context_candidate_provider_chain(
+    providers: Iterable[ContextCandidateProviderPort],
+) -> ContextCandidateProviderChain:
+    """Create a deterministic provider chain from concrete feature adapters."""
+
+    return ContextCandidateProviderChain(providers=tuple(providers))
+
+
+__all__ = (
+    "ContextCandidateProviderChain",
+    "create_context_candidate_provider_chain",
+)

infinity_context_adapters/features/context_building/graphiti_candidate_provider.py

@@ -0,0 +1,44 @@
+"""Graphiti-derived candidate provider seam for context_building."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from infinity_context_core.features.context_building.public import (
+    FEATURE_ID,
+    ContextCandidateProviderPort,
+    ContextCandidateRequest,
+    ContextItem,
+)
+
+
+class GraphitiContextCandidateProvider:
+    """Placeholder for future graph-derived context candidates."""
+
+    adapter_name = "graphiti"
+    feature_id = FEATURE_ID
+
+    async def find_candidates(
+        self,
+        _request: ContextCandidateRequest,
+    ) -> tuple[ContextItem, ...]:
+        _raise_not_implemented("find_candidates")
+
+
+def create_graphiti_context_candidate_provider() -> ContextCandidateProviderPort:
+    """Create the feature-owned Graphiti candidate provider placeholder."""
+
+    return GraphitiContextCandidateProvider()
+
+
+def _raise_not_implemented(operation: str) -> NoReturn:
+    raise NotImplementedError(
+        f"context_building Graphiti candidate provider {operation} is a placeholder seam; "
+        "real Graphiti graph recall wiring is deferred."
+    )
+
+
+__all__ = (
+    "GraphitiContextCandidateProvider",
+    "create_graphiti_context_candidate_provider",
+)

infinity_context_adapters/features/context_building/in_memory_candidate_provider.py

@@ -0,0 +1,62 @@
+"""In-memory candidate provider for context_building adapter tests and wiring."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import ClassVar
+
+from infinity_context_core.features.context_building.public import (
+    FEATURE_ID,
+    ContextCandidateProviderPort,
+    ContextCandidateRequest,
+    ContextItem,
+)
+
+from infinity_context_adapters.features.context_building.query_request import (
+    ContextCandidateAdapterQuery,
+)
+from infinity_context_adapters.features.context_building.records import (
+    ContextCandidateRecord,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class InMemoryContextCandidateProvider:
+    """Stdlib-only candidate provider that honors context_building scope rules."""
+
+    records: tuple[ContextCandidateRecord, ...] = ()
+
+    adapter_name: ClassVar[str] = "in_memory"
+    feature_id: ClassVar[str] = FEATURE_ID
+
+    async def find_candidates(
+        self,
+        request: ContextCandidateRequest,
+    ) -> tuple[ContextItem, ...]:
+        adapter_query = ContextCandidateAdapterQuery.from_candidate_request(request)
+        matching_records = [
+            record for record in self.records if record.matches_request(adapter_query)
+        ]
+        ranked_records = sorted(
+            enumerate(matching_records),
+            key=lambda item: (-item[1].priority, -item[1].score, item[0]),
+        )
+        return tuple(
+            record.to_context_item()
+            for _, record in ranked_records[: adapter_query.limit]
+        )
+
+
+def create_in_memory_context_candidate_provider(
+    records: Iterable[ContextCandidateRecord] = (),
+) -> ContextCandidateProviderPort:
+    """Create a deterministic in-memory implementation of the candidate port."""
+
+    return InMemoryContextCandidateProvider(records=tuple(records))
+
+
+__all__ = (
+    "InMemoryContextCandidateProvider",
+    "create_in_memory_context_candidate_provider",
+)

infinity_context_adapters/features/context_building/postgres_candidate_provider.py

@@ -0,0 +1,44 @@
+"""Postgres canonical candidate provider seam for context_building."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from infinity_context_core.features.context_building.public import (
+    FEATURE_ID,
+    ContextCandidateProviderPort,
+    ContextCandidateRequest,
+    ContextItem,
+)
+
+
+class PostgresContextCandidateProvider:
+    """Placeholder for future canonical context candidate queries."""
+
+    adapter_name = "postgres"
+    feature_id = FEATURE_ID
+
+    async def find_candidates(
+        self,
+        _request: ContextCandidateRequest,
+    ) -> tuple[ContextItem, ...]:
+        _raise_not_implemented("find_candidates")
+
+
+def create_postgres_context_candidate_provider() -> ContextCandidateProviderPort:
+    """Create the feature-owned Postgres candidate provider placeholder."""
+
+    return PostgresContextCandidateProvider()
+
+
+def _raise_not_implemented(operation: str) -> NoReturn:
+    raise NotImplementedError(
+        f"context_building Postgres candidate provider {operation} is a placeholder seam; "
+        "real canonical query wiring is deferred."
+    )
+
+
+__all__ = (
+    "PostgresContextCandidateProvider",
+    "create_postgres_context_candidate_provider",
+)