Add Summarization requests (#48)

* Add Summarization requests

Allows using the /summarize endpoint from the python client.

* Add examples to readme

Co-authored-by: Julius Kreuzer <[email protected]>

* bump version

Co-authored-by: Julius Kreuzer <[email protected]>

Changelog.md

@@ -1,76 +1,82 @@
 # Changelog
 
+## 2.3.0
+
+### New feature
+
+- Summarization of Documents
+
 ## 2.2.4
 
 ### Documentation
 
-* Update documentation for `hosting` parameter
+- Update documentation for `hosting` parameter
 
 ## 2.2.3
 
 ### Bugfix
 
-* Remove `message` field from CompletionResult
+- Remove `message` field from CompletionResult
 
 ## 2.2.2
 
 ### Bugfix
 
-* Document `hosting` parameter.
-* The hosting parameter determines in which datacenters the request may be processed.
-* Currently, we only support setting it to "aleph-alpha", which allows us to only process the request in our own datacenters.
-* Not setting this value, or setting it to null, allows us to process the request in both our own as well as external datacenters.
+- Document `hosting` parameter.
+- The hosting parameter determines in which datacenters the request may be processed.
+- Currently, we only support setting it to "aleph-alpha", which allows us to only process the request in our own datacenters.
+- Not setting this value, or setting it to null, allows us to process the request in both our own as well as external datacenters.
 
 ## 2.2.1
 
 ### Bugfix
 
-* Restore original error handling of HTTP status codes to before 2.2.0
-* Add dedicated exception BusyError for status code 503
+- Restore original error handling of HTTP status codes to before 2.2.0
+- Add dedicated exception BusyError for status code 503
 
 ## 2.2.0
 
 ### New feature
 
-* Retry failed HTTP requests via urllib for status codes 408, 429, 500, 502, 503, 504
+- Retry failed HTTP requests via urllib for status codes 408, 429, 500, 502, 503, 504
 
 ## 2.1.0
 
 ### New feature
 
-* Add new parameters to control how repetition penalties are applied for completion requests (see [docs](https://docs.aleph-alpha.com/api/#/paths/~1complete/post) for more information):
-  * `penalty_bias`
-  * `penalty_exceptions`
-  * `penalty_exceptions_include_stop_sequences`
+- Add new parameters to control how repetition penalties are applied for completion requests (see [docs](https://docs.aleph-alpha.com/api/#/paths/~1complete/post) for more information):
+  - `penalty_bias`
+  - `penalty_exceptions`
+  - `penalty_exceptions_include_stop_sequences`
 
 ## 2.0.0
 
 ### Breaking change
 
-* Make hosting parameter optional in semantic_embed on client. Changed order of parameters `hosting` and `request`.
+- Make hosting parameter optional in semantic_embed on client. Changed order of parameters `hosting` and `request`.
   Should not be an issue if you're not using semantic_embed from the client directly or if you're using keyword args.
 
 ### Experimental feature
 
-* Add experimental penalty parameters for completion
+- Add experimental penalty parameters for completion
 
 ## 1.7.1
 
-* Improved handling of text-based Documents in Q&A
+- Improved handling of text-based Documents in Q&A
 
 ## 1.7.0
 
-* Introduce `semantic_embed` endpoint on client and model.
-* Introduce timeout on client
+- Introduce `semantic_embed` endpoint on client and model.
+- Introduce timeout on client
 
 ## 1.6.0
 
-* Introduce AlephAlphaModel as a more convenient alternative to direct usage of AlephAlphaClient
+- Introduce AlephAlphaModel as a more convenient alternative to direct usage of AlephAlphaClient
 
 ## 1.1.0
 
-* Support for sending images to multimodal Models.
+- Support for sending images to multimodal Models.
 
 ## 1.0.0
 
-* Initial Release
+- Initial Release

README.md

@@ -327,6 +327,82 @@ print(result)
 ```
 
 
+### Summary with a Docx Document
+
+
+
+```python
+from aleph_alpha_client import Document, AlephAlphaClient, AlephAlphaModel, SummarizationRequest
+import os
+
+model = AlephAlphaModel(
+    AlephAlphaClient(host="https://api.aleph-alpha.com", token=os.getenv("AA_TOKEN")),
+    # You need to choose a model with qa support for this example.
+    model_name = "luminous-extended"
+)
+
+docx_file = "./tests/sample.docx"
+document = Document.from_docx_file(docx_file)
+
+request = SummarizationRequest(document)
+
+result = model.summarize(request)
+
+print(result)
+```
+
+
+### Summary with a Text
+
+
+```python
+from aleph_alpha_client import AlephAlphaClient, AlephAlphaModel, SummarizationRequest
+import os
+
+model = AlephAlphaModel(
+    AlephAlphaClient(host="https://api.aleph-alpha.com", token=os.getenv("AA_TOKEN")),
+    # You need to choose a model with qa support for this example.
+    model_name = "luminous-extended"
+)
+
+prompt = "In imperative programming, a computer program is a sequence of instructions in a programming language that a computer can execute or interpret."
+document = Document.from_text(prompt)
+
+request = SummarizationRequest(document)
+
+result = model.summarize(request)
+
+print(result)
+```
+
+
+### Summary with a multimodal prompt
+
+
+
+```python
+from aleph_alpha_client import Document, ImagePrompt, AlephAlphaClient, AlephAlphaModel, SummarizationRequest
+import os
+
+model = AlephAlphaModel(
+    AlephAlphaClient(host="https://api.aleph-alpha.com", token=os.getenv("AA_TOKEN")),
+    # You need to choose a model with qa support for this example.
+    model_name = "luminous-extended"
+)
+
+url = "https://upload.wikimedia.org/wikipedia/commons/thumb/7/74/2008-09-24_Blockbuster_in_Durham.jpg/330px-2008-09-24_Blockbuster_in_Durham.jpg"
+image = ImagePrompt.from_url(url)
+prompt = [image]
+document = Document.from_prompt(prompt)
+
+request = SummarizationRequest(document)
+
+result = model.summarize(request)
+
+print(result)
+```
+
+
 ### Tokenize a text prompt
 
 

aleph_alpha_client/__init__.py

@@ -15,6 +15,7 @@
 from .evaluation import EvaluationRequest, EvaluationResponse
 from .tokenization import TokenizationRequest, TokenizationResponse
 from .detokenization import DetokenizationRequest, DetokenizationResponse
+from .summarization import SummarizationRequest, SummarizationResponse
 from .utils import load_base64_from_url, load_base64_from_file
 from .document import Document
 from .version import __version__

aleph_alpha_client/aleph_alpha_client.py

@@ -14,6 +14,7 @@
 from aleph_alpha_client.explanation import ExplanationRequest
 from aleph_alpha_client.image import ImagePrompt
 from aleph_alpha_client.prompt import _to_prompt_item, _to_serializable_prompt
+from aleph_alpha_client.summarization import SummarizationRequest
 
 POOLING_OPTIONS = ["mean", "max", "last_token", "abs_max"]
 
@@ -591,6 +592,46 @@ def qa(
         response_json = self._translate_errors(response).json()
         return response_json
 
+    def summarize(
+        self,
+        model: str,
+        request: SummarizationRequest,
+        hosting: Optional[str] = None,
+    ):
+        """
+        Summarizes a document.
+
+        Parameters:
+            model (str, required):
+                Name of model to use. A model name refers to a model architecture (number of parameters among others). Always the latest version of model is used. The model output contains information as to the model version.
+
+            hosting (str, optional, default None):
+                Determines in which datacenters the request may be processed.
+                You can either set the parameter to "aleph-alpha" or omit it (defaulting to None).
+
+                Not setting this value, or setting it to None, gives us maximal flexibility in processing your request in our
+                own datacenters and on servers hosted with other providers. Choose this option for maximal availability.
+
+                Setting it to "aleph-alpha" allows us to only process the request in our own datacenters.
+                Choose this option for maximal data privacy.
+
+            request (SemanticEmbeddingRequest, required)
+                NamedTuple containing all necessary request parameters.
+        """
+        payload: Dict[str, Any] = {
+            "model": model,
+            "document": request.document._to_serializable_document(),
+            "disable_optimizations": request.disable_optimizations,
+        }
+
+        if hosting is not None:
+            payload["hosting"] = hosting
+
+        response = self.post_request(
+            self.host + "summarize", headers=self.request_headers, json=payload
+        )
+        return self._translate_errors(response).json()
+
     def _explain(
         self, model: str, request: ExplanationRequest, hosting: Optional[str] = None
     ):

aleph_alpha_client/aleph_alpha_model.py

@@ -16,6 +16,7 @@
 from aleph_alpha_client.explanation import ExplanationRequest
 from aleph_alpha_client.qa import QaRequest, QaResponse
 from aleph_alpha_client.tokenization import TokenizationRequest, TokenizationResponse
+from aleph_alpha_client.summarization import SummarizationRequest, SummarizationResponse
 
 
 class AlephAlphaModel:
@@ -94,6 +95,12 @@ def _explain(self, request: ExplanationRequest) -> Mapping[str, Any]:
             model=self.model_name, hosting=self.hosting, request=request
         )
 
+    def summarize(self, request: SummarizationRequest) -> SummarizationResponse:
+        response_json = self.client.summarize(
+            self.model_name, request, hosting=self.hosting
+        )
+        return SummarizationResponse.from_json(response_json)
+
     @staticmethod
     def as_request_dict(
         request: Union[CompletionRequest, EmbeddingRequest, EvaluationRequest]

aleph_alpha_client/summarization.py

@@ -0,0 +1,38 @@
+from typing import Any, Mapping, NamedTuple, Sequence
+
+from aleph_alpha_client.document import Document
+
+
+class SummarizationRequest(NamedTuple):
+    """
+    Summarizes a document.
+
+    Parameters:
+        document (Document, required):
+            A single document. This can be one of the following formats:
+
+            - Docx: A base64 encoded Docx file
+            - Text: A string of text
+            - Prompt: A multimodal prompt, as is used in our other tasks like Completion
+
+            Documents of types Docx and Text are usually preferred, and will have optimizations (such as chunking) applied to work better with the respective task that is being run.
+
+            Prompt documents are assumed to be used for advanced use cases, and will be left as-is.
+
+        disable_optimizations  (bool, default False)
+            We continually research optimal ways to work with our models. By default, we apply these optimizations to both your query, documents, and answers for you.
+            Our goal is to improve your results while using our API.
+            But you can always pass `disable_optimizations: true` and we will leave your document and summary untouched.
+    """
+
+    document: Document
+    disable_optimizations: bool = False
+
+
+class SummarizationResponse(NamedTuple):
+    model_version: str
+    summary: str
+
+    @classmethod
+    def from_json(cls, json: Mapping[str, Any]) -> "SummarizationResponse":
+        return cls(model_version=json["model_version"], summary=json["summary"])

aleph_alpha_client/version.py

@@ -1 +1 @@
-__version__ = "2.2.3"
+__version__ = "2.3.0"