Metadata-Version: 2.5
Name: docling-gigaam
Version: 0.1.0
Summary: GigaAM v3 audio and video transcription pipelines for Docling
Project-URL: Documentation, https://github.com/mxl/docling-gigaam#readme
Project-URL: Issues, https://github.com/mxl/docling-gigaam/issues
Project-URL: Source, https://github.com/mxl/docling-gigaam
Author: Michael Ledin
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/docling_gigaam/_vendor/gigaam/LICENSE
Keywords: asr,docling,gigaam,russian,speech-to-text
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: docling<2.122,>=2.121
Requires-Dist: hydra-core<2,>=1.3
Requires-Dist: numpy>=1.26
Requires-Dist: omegaconf<3,>=2.3
Requires-Dist: packaging>=24
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: sentencepiece>=0.2
Requires-Dist: silero-vad<7,>=6.0
Requires-Dist: soundfile>=0.13
Requires-Dist: torch>=2.6
Requires-Dist: torchaudio>=2.6
Requires-Dist: tqdm>=4.67
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

# docling-gigaam

`docling-gigaam` adds Russian speech recognition through GigaAM v3 to Docling
2.121 without forking Docling. It provides standalone transcription plus custom
audio and video pipelines. Video conversion keeps Docling's inherited frame
sampling, scene detection, diarization, sentence merge, and timestamp merge.

## Install

Python 3.11 or newer and the system `ffmpeg` executable are required.

```bash
pip install docling-gigaam
```

On first transcription, the official GigaAM model host downloads approximately
450 MB of model weights plus the tokenizer into `docling-gigaam/` under the
selected cache root. `HF_HUB_CACHE` and `HF_HOME` are honored by default. Set
`cache_dir` to use another root, or `local_files_only=True` after prefetching.

## Standalone Usage

```python
from docling_gigaam import GigaAmTranscriber

segments = GigaAmTranscriber().transcribe("recording.mp3")
for segment in segments:
    print(segment.start_time, segment.end_time, segment.text)
```

Audio at or below 25 seconds uses the short path. Longer audio is decoded to
mono 16 kHz, segmented with Silero VAD, merged into model-sized chunks, and
processed in batches. Returned segment timestamps are absolute offsets from the
start of the source. Word timestamps are not provided in version 0.1.

## Audio With Docling

```python
from docling.datamodel.base_models import InputFormat
from docling.document_converter import DocumentConverter
from docling_gigaam import audio_format_option

converter = DocumentConverter(
    allowed_formats=[InputFormat.AUDIO],
    format_options={InputFormat.AUDIO: audio_format_option()},
)
result = converter.convert("recording.mp3")
print(result.document.export_to_markdown())
```

Each transcript segment is a Docling text item with a public `TrackSource`
containing its absolute start and end time.

## Video With Docling

```python
from docling.datamodel.base_models import InputFormat
from docling.document_converter import DocumentConverter
from docling_gigaam import GigaAmVideoPipelineOptions, video_format_option

options = GigaAmVideoPipelineOptions(
    generate_frame_images=True,
    frame_interval_seconds=10.0,
)
converter = DocumentConverter(
    allowed_formats=[InputFormat.VIDEO],
    format_options={InputFormat.VIDEO: video_format_option(options)},
)
result = converter.convert("meeting.mp4")
print(result.document.export_to_markdown())
```

## Model And Security

The package vendors the official MIT-licensed GigaAM inference runtime from
commit `7447938d791c4f3e643386ee22c33777004293a5`. It does not execute Hugging Face
remote code and does not depend on the stale `gigaam==0.1.0` PyPI release.

Model weights are not included in the wheel. The official `v3_e2e_rnnt`
checkpoint and tokenizer are downloaded lazily from the GigaAM project host.
The upstream MD5 checksum is verified before the checkpoint is loaded, so a
silently replaced model is rejected.

GigaAM v3 is intended for Russian speech. Accuracy for other languages is not a
supported scope of this package.

## Devices

`device="auto"` selects CUDA, then Apple MPS, then CPU. MPS is not tested by
GigaAM upstream and emits a warning. If MPS encounters unsupported operations,
set `PYTORCH_ENABLE_MPS_FALLBACK=1` or select CPU explicitly.

## Attribution

The pure Silero interval-merging logic in `docling_gigaam.vad` is adapted from
the MIT-licensed
[`SmetDenis/gigaam-openai-api-server`](https://github.com/SmetDenis/gigaam-openai-api-server),
which in turn follows GigaAM's long-form VAD merge design. This package adapts
only the focused chunking approach and does not copy the unrelated API server.
The GigaAM inference runtime and its license are recorded in
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).

## Development

```bash
uv sync --extra dev
uv run pytest -m "not integration"
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build
```

The integration scaffold is opt-in because it downloads the model:

```bash
DOCLING_GIGAAM_RUN_INTEGRATION=1 \
DOCLING_GIGAAM_SAMPLE=/path/to/russian.wav \
uv run pytest -m integration
```
