feat!: add Action Items LeMUR GA feature (#29)

add Action Items LeMUR GA feature

Author: s0h3yl

README.md

@@ -218,6 +218,26 @@ for q in result.response:
     print(f"Answer: {q.answer}")
 ```
 
+</details>
+
+<details>
+  <summary>Use LeMUR to Ask for Action Items from a Single Transcript</summary>
+
+```python
+import assemblyai as aai
+
+transcriber = aai.Transcriber()
+transcript = transcriber.transcribe("https://example.org/customer.mp3")
+
+result = transcript.lemur.action_items(
+    context="Customers asking for help with resolving their problem",
+    answer_format="Three bullet points",
+)
+
+print(result.response)
+```
+
+
 </details>
 
 <details>

assemblyai/__init__.py

@@ -17,6 +17,7 @@
     IABResponse,
     IABResult,
     LanguageCode,
+    LemurActionItemsResponse,
     LemurError,
     LemurModel,
     LemurQuestion,
@@ -77,6 +78,7 @@
     "IABResult",
     "LanguageCode",
     "Lemur",
+    "LemurActionItemsResponse",
     "LemurError",
     "LemurModel",
     "LemurSource",

assemblyai/api.py

@@ -270,6 +270,27 @@ def lemur_summarize(
     return types.LemurSummaryResponse.parse_obj(response.json())
 
 
+def lemur_action_items(
+    client: httpx.Client,
+    request: types.LemurActionItemsRequest,
+    http_timeout: Optional[float],
+) -> types.LemurActionItemsResponse:
+    response = client.post(
+        f"{ENDPOINT_LEMUR}/action-items",
+        json=request.dict(
+            exclude_none=True,
+        ),
+        timeout=http_timeout,
+    )
+
+    if response.status_code != httpx.codes.ok:
+        raise types.LemurError(
+            f"failed to call Lemur action items: {_get_error_message(response)}"
+        )
+
+    return types.LemurActionItemsResponse.parse_obj(response.json())
+
+
 def lemur_task(
     client: httpx.Client,
     request: types.LemurTaskRequest,

assemblyai/lemur.py

@@ -58,6 +58,28 @@ def summarize(
 
         return response
 
+    def action_items(
+        self,
+        context: Optional[Union[str, Dict[str, Any]]],
+        answer_format: Optional[str],
+        final_model: Optional[types.LemurModel],
+        max_output_size: Optional[int],
+        timeout: Optional[float],
+    ) -> types.LemurActionItemsResponse:
+        response = api.lemur_action_items(
+            client=self._client.http_client,
+            request=types.LemurActionItemsRequest(
+                sources=self._sources,
+                context=context,
+                answer_format=answer_format,
+                final_model=final_model,
+                max_output_size=max_output_size,
+            ),
+            http_timeout=timeout,
+        )
+
+        return response
+
     def task(
         self,
         prompt: str,
@@ -175,6 +197,40 @@ def summarize(
             timeout=timeout,
         )
 
+    def action_items(
+        self,
+        context: Optional[Union[str, Dict[str, Any]]] = None,
+        answer_format: Optional[str] = None,
+        final_model: Optional[types.LemurModel] = None,
+        max_output_size: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> types.LemurActionItemsResponse:
+        """
+        Action Items allows you to generate action items from one or many transcripts.
+
+        You can provide the model with a context to get more pinpoint results while outputting the
+        results in a variety of formats described in human language.
+
+        See also Best Practices on LeMUR: https://www.assemblyai.com/docs/Guides/lemur_best_practices
+
+        Args:
+            context: An optional context on the transcript.
+            answer_format: The preferred format for the result action items.
+            final_model: The model that is used for the final prompt after compression is performed (options: "basic" and "default").
+            max_output_size: Max output size in tokens
+            timeout: The timeout in seconds to wait for the action items response.
+
+        Returns: The action items as a string.
+        """
+
+        return self._impl.action_items(
+            context=context,
+            answer_format=answer_format,
+            final_model=final_model,
+            max_output_size=max_output_size,
+            timeout=timeout,
+        )
+
     def task(
         self,
         prompt: str,

assemblyai/types.py

@@ -1781,6 +1781,23 @@ class LemurSummaryResponse(BaseModel):
     "The summary of your LeMUR request"
 
 
+class LemurActionItemsRequest(BaseLemurRequest):
+    context: Optional[Union[str, Dict[str, Any]]]
+    answer_format: Optional[str]
+
+
+class LemurActionItemsResponse(BaseModel):
+    """
+    The result of your Action Items LeMUR request.
+    """
+
+    request_id: str
+    "The unique identifier of your LeMUR request"
+
+    response: str
+    "The action items for your LeMUR request"
+
+
 class RealtimeMessageTypes(str, Enum):
     """
     The type of message received from the real-time API

setup.py

@@ -7,7 +7,7 @@
 
 setup(
     name="assemblyai",
-    version="0.14.0",
+    version="0.15.0",
     description="AssemblyAI Python SDK",
     author="AssemblyAI",
     author_email="engineering.sdk@assemblyai.com",

tests/unit/factories.py

@@ -177,6 +177,14 @@ class Meta:
     response = factory.Faker("text")
 
 
+class LemurActionItemsResponse(factory.Factory):
+    class Meta:
+        model = types.LemurActionItemsResponse
+
+    request_id = factory.Faker("uuid4")
+    response = factory.Faker("text")
+
+
 class LemurTaskResponse(factory.Factory):
     class Meta:
         model = types.LemurTaskResponse

tests/unit/test_lemur.py

@@ -152,7 +152,9 @@ def test_lemur_summarize_succeeds(httpx_mock: HTTPXMock):
     """
 
     # create a mock response of a LemurSummaryResponse
-    mock_lemur_summary = factories.generate_dict_factory(factories.LemurTaskResponse)()
+    mock_lemur_summary = factories.generate_dict_factory(
+        factories.LemurSummaryResponse
+    )()
 
     # mock the specific endpoints
     httpx_mock.add_response(
@@ -204,6 +206,72 @@ def test_lemur_summarize_fails(httpx_mock: HTTPXMock):
     assert len(httpx_mock.get_requests()) == 1
 
 
+def test_lemur_action_items_succeeds(httpx_mock: HTTPXMock):
+    """
+    Tests whether generating action items for a transcript via LeMUR succeeds.
+    """
+
+    # create a mock response of a LemurActionItemsResponse
+    mock_lemur_action_items = factories.generate_dict_factory(
+        factories.LemurActionItemsResponse
+    )()
+
+    # mock the specific endpoints
+    httpx_mock.add_response(
+        url=f"{aai.settings.base_url}{ENDPOINT_LEMUR}/action-items",
+        status_code=httpx.codes.OK,
+        method="POST",
+        json=mock_lemur_action_items,
+    )
+
+    # mimic the usage of the SDK
+    transcript = aai.Transcript(str(uuid.uuid4()))
+
+    lemur = aai.Lemur(sources=[aai.LemurSource(transcript)])
+    result = lemur.action_items(
+        context="Customers asking for help with resolving their problem",
+        answer_format="Three bullet points",
+    )
+
+    assert isinstance(result, aai.LemurActionItemsResponse)
+
+    action_items = result.response
+
+    # check the response
+    assert action_items == mock_lemur_action_items["response"]
+
+    # check whether we mocked everything
+    assert len(httpx_mock.get_requests()) == 1
+
+
+def test_lemur_action_items_fails(httpx_mock: HTTPXMock):
+    """
+    Tests whether generating action items for a transcript via LeMUR fails.
+    """
+
+    # mock the specific endpoints
+    httpx_mock.add_response(
+        url=f"{aai.settings.base_url}{ENDPOINT_LEMUR}/action-items",
+        status_code=httpx.codes.INTERNAL_SERVER_ERROR,
+        method="POST",
+        json={"error": "something went wrong"},
+    )
+
+    # mimic the usage of the SDK
+    transcript = aai.Transcript(str(uuid.uuid4()))
+
+    lemur = aai.Lemur(sources=[aai.LemurSource(transcript)])
+
+    with pytest.raises(aai.LemurError):
+        lemur.action_items(
+            context="Customers asking for help with resolving their problem",
+            answer_format="Three bullet points",
+        )
+
+    # check whether we mocked everything
+    assert len(httpx_mock.get_requests()) == 1
+
+
 def test_lemur_task_succeeds(httpx_mock: HTTPXMock):
     """
     Tests whether creating a task request succeeds.