feat: enable retrieval of existing transcripts

GitOrigin-RevId: 369957adcacc25eaf6191b60d0cf06176a7ffbbb

Author: dmccrystal

README.md

@@ -678,3 +678,38 @@ import assemblyai as aai
 
 aai.settings.polling_interval = 1.0
 ```
+
+## Retrieving Existing Transcripts
+
+### Retrieving a Single Transcript
+
+If you previously created a transcript, you can use its ID to retrieve it later.
+
+```python
+import assemblyai as aai
+
+transcript = aai.Transcript.get_by_id("<TRANSCRIPT_ID>")
+
+print(transcript.id)
+print(transcript.text)
+```
+
+### Retrieving Multiple Transcripts as a Group
+
+You can also retrieve multiple existing transcripts and combine them into a single `TranscriptGroup` object. This allows you to perform operations on the transcript group as a single unit, such as querying the combined transcripts with LeMUR.
+
+```python
+import assemblyai as aai
+
+transcript_group = aai.TranscriptGroup.get_by_ids(["<TRANSCRIPT_ID_1>", "<TRANSCRIPT_ID_2>"])
+
+summary = transcript_group.lemur.summarize(context="Customers asking for cars", answer_format="TLDR")
+
+print(summary)
+```
+
+### Retrieving Transcripts Asynchronously
+
+Both `Transcript.get_by_id` and `TranscriptGroup.get_by_ids` have asynchronous counterparts, `Transcript.get_by_id_async` and `TranscriptGroup.get_by_ids_async`, respectively. These functions immediately return a `Future` object, rather than blocking until the transcript(s) are retrieved.
+
+See the above section on [Synchronous vs Asynchronous](#synchronous-vs-asynchronous) for more information.

assemblyai/transcriber.py

@@ -236,6 +236,30 @@ def from_response(
 
         return self
 
+    @classmethod
+    def get_by_id(cls, transcript_id: str) -> Self:
+        """Fetch an existing transcript. Blocks until the transcript is completed.
+
+        Args:
+            transcript_id: the id of the transcript to fetch
+
+        Returns:
+            The transcript object identified by the given id.
+        """
+        return cls(transcript_id=transcript_id).wait_for_completion()
+
+    @classmethod
+    def get_by_id_async(cls, transcript_id: str) -> concurrent.futures.Future[Self]:
+        """Fetch an existing transcript asynchronously.
+
+        Args:
+            transcript_id: the id of the transcript to fetch
+
+        Returns:
+            A future that will resolve to the transcript object identified by the given id.
+        """
+        return cls(transcript_id=transcript_id).wait_for_completion_async()
+
     @property
     def id(self) -> Optional[str]:
         "The unique identifier of your transcription"
@@ -526,6 +550,7 @@ def __init__(
             transcript_ids=transcript_ids,
             client=self._client,
         )
+        self._executor = concurrent.futures.ThreadPoolExecutor()
 
     @property
     def transcripts(self) -> List[Transcript]:
@@ -542,6 +567,16 @@ def __iter__(self) -> Iterator[Transcript]:
 
         return iter(self.transcripts)
 
+    @classmethod
+    def get_by_ids(cls, transcript_ids: List[str]) -> Self:
+        return cls(transcript_ids=transcript_ids).wait_for_completion()
+
+    @classmethod
+    def get_by_ids_async(
+        cls, transcript_ids: List[str]
+    ) -> concurrent.futures.Future[Self]:
+        return cls(transcript_ids=transcript_ids).wait_for_completion_async()
+
     @property
     def status(self) -> types.TranscriptStatus:
         """
@@ -595,6 +630,11 @@ def wait_for_completion(self) -> Self:
 
         return self
 
+    def wait_for_completion_async(
+        self,
+    ) -> concurrent.futures.Future[Self]:
+        return self._executor.submit(self.wait_for_completion)
+
 
 class _TranscriberImpl:
     """

tests/unit/test_transcript.py

@@ -304,3 +304,44 @@ def test_get_sentences_and_paragraphs_fails(httpx_mock: HTTPXMock):
 
     # check whether we mocked everything
     assert len(httpx_mock.get_requests()) == 2
+
+
+def test_get_by_id(httpx_mock: HTTPXMock):
+    transcript_id = "123"
+    mock_transcript_response = factories.generate_dict_factory(
+        factories.TranscriptCompletedResponseFactory
+    )()
+    httpx_mock.add_response(
+        url=f"{aai.settings.base_url}/transcript/{transcript_id}",
+        status_code=httpx.codes.OK,
+        method="GET",
+        json=mock_transcript_response,
+    )
+
+    transcript = aai.Transcript.get_by_id(transcript_id)
+
+    assert isinstance(transcript, aai.Transcript)
+    assert transcript.status == aai.TranscriptStatus.completed
+    assert transcript.id == transcript_id
+    assert transcript.error is None
+
+
+def test_get_by_id_async(httpx_mock: HTTPXMock):
+    transcript_id = "123"
+    mock_transcript_response = factories.generate_dict_factory(
+        factories.TranscriptCompletedResponseFactory
+    )()
+    httpx_mock.add_response(
+        url=f"{aai.settings.base_url}/transcript/{transcript_id}",
+        status_code=httpx.codes.OK,
+        method="GET",
+        json=mock_transcript_response,
+    )
+
+    transcript_future = aai.Transcript.get_by_id_async(transcript_id)
+    transcript = transcript_future.result()
+
+    assert isinstance(transcript, aai.Transcript)
+    assert transcript.status == aai.TranscriptStatus.completed
+    assert transcript.id == transcript_id
+    assert transcript.error is None

tests/unit/test_transcript_group.py

@@ -1,5 +1,8 @@
 import uuid
 
+import httpx
+from pytest_httpx import HTTPXMock
+
 import assemblyai as aai
 import assemblyai as aai
 from tests.unit import factories
@@ -71,3 +74,54 @@ def test_transcript_group_check_status():
 
     transcript_group.add_transcript(transcript_error)
     assert transcript_group.status == aai.TranscriptStatus.error
+
+
+def test_get_by_ids(httpx_mock: HTTPXMock):
+    transcript_ids = ["123", "456"]
+    mock_transcript_response = factories.generate_dict_factory(
+        factories.TranscriptCompletedResponseFactory
+    )()
+    for transcript_id in transcript_ids:
+        httpx_mock.add_response(
+            url=f"{aai.settings.base_url}/transcript/{transcript_id}",
+            status_code=httpx.codes.OK,
+            method="GET",
+            json=mock_transcript_response,
+        )
+
+    transcript_group = aai.TranscriptGroup.get_by_ids(transcript_ids)
+
+    assert isinstance(transcript_group, aai.TranscriptGroup)
+    assert transcript_group.status == aai.TranscriptStatus.completed
+    for transcript in transcript_group:
+        assert transcript.id in transcript_ids
+        transcript_ids.remove(transcript.id)
+
+        assert transcript.error is None
+    assert len(transcript_ids) == 0
+
+
+def test_get_by_id_async(httpx_mock: HTTPXMock):
+    transcript_ids = ["123", "456"]
+    mock_transcript_response = factories.generate_dict_factory(
+        factories.TranscriptCompletedResponseFactory
+    )()
+    for transcript_id in transcript_ids:
+        httpx_mock.add_response(
+            url=f"{aai.settings.base_url}/transcript/{transcript_id}",
+            status_code=httpx.codes.OK,
+            method="GET",
+            json=mock_transcript_response,
+        )
+
+    transcript_group_future = aai.TranscriptGroup.get_by_ids_async(transcript_ids)
+    transcript_group = transcript_group_future.result()
+
+    assert isinstance(transcript_group, aai.TranscriptGroup)
+    assert transcript_group.status == aai.TranscriptStatus.completed
+    for transcript in transcript_group:
+        assert transcript.id in transcript_ids
+        transcript_ids.remove(transcript.id)
+
+        assert transcript.error is None
+    assert len(transcript_ids) == 0