feat(api)!: made universal classification endpoint multi-input only

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 2
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/isaacus%2Fisaacus-c224b4437a8a19d29aa29506fdb44ffc5316d5ba3600feee90678acdb2557e23.yml
-openapi_spec_hash: 6b74504e14f7e1aa631e6bd76d596f48
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/isaacus%2Fisaacus-213d554b23f35e746460af23dd32bdde471230549ad223518c86d42ea917a180.yml
+openapi_spec_hash: 3672281fe031a42fc59e3a2af758a8f8
 config_hash: 1d603d50b7183a492ad6df5f728a1863

README.md

@@ -34,9 +34,9 @@ client = Isaacus(
 universal_classification = client.classifications.universal.create(
     model="kanon-universal-classifier",
     query="This is a confidentiality clause.",
-    text="I agree not to tell anyone about the document.",
+    texts=["I agree not to tell anyone about the document."],
 )
-print(universal_classification.chunks)
+print(universal_classification.classifications)
 ```
 
 While you can provide an `api_key` keyword argument,
@@ -62,9 +62,9 @@ async def main() -> None:
     universal_classification = await client.classifications.universal.create(
         model="kanon-universal-classifier",
         query="This is a confidentiality clause.",
-        text="I agree not to tell anyone about the document.",
+        texts=["I agree not to tell anyone about the document."],
     )
-    print(universal_classification.chunks)
+    print(universal_classification.classifications)
 
 
 asyncio.run(main())
@@ -93,7 +93,7 @@ client = Isaacus()
 universal_classification = client.classifications.universal.create(
     model="kanon-universal-classifier",
     query="This is a confidentiality clause.",
-    text="I agree not to tell anyone about the document.",
+    texts=["I agree not to tell anyone about the document."],
     chunking_options={
         "overlap_ratio": 0.1,
         "overlap_tokens": None,
@@ -122,7 +122,7 @@ try:
     client.classifications.universal.create(
         model="kanon-universal-classifier",
         query="This is a confidentiality clause.",
-        text="I agree not to tell anyone about the document.",
+        texts=["I agree not to tell anyone about the document."],
     )
 except isaacus.APIConnectionError as e:
     print("The server could not be reached")
@@ -169,7 +169,7 @@ client = Isaacus(
 client.with_options(max_retries=5).classifications.universal.create(
     model="kanon-universal-classifier",
     query="This is a confidentiality clause.",
-    text="I agree not to tell anyone about the document.",
+    texts=["I agree not to tell anyone about the document."],
 )
 ```
 
@@ -196,7 +196,7 @@ client = Isaacus(
 client.with_options(timeout=5.0).classifications.universal.create(
     model="kanon-universal-classifier",
     query="This is a confidentiality clause.",
-    text="I agree not to tell anyone about the document.",
+    texts=["I agree not to tell anyone about the document."],
 )
 ```
 
@@ -241,12 +241,12 @@ client = Isaacus()
 response = client.classifications.universal.with_raw_response.create(
     model="kanon-universal-classifier",
     query="This is a confidentiality clause.",
-    text="I agree not to tell anyone about the document.",
+    texts=["I agree not to tell anyone about the document."],
 )
 print(response.headers.get('X-My-Header'))
 
 universal = response.parse()  # get the object that `classifications.universal.create()` would have returned
-print(universal.chunks)
+print(universal.classifications)
 ```
 
 These methods return an [`APIResponse`](https://github.com/isaacus-dev/isaacus-python/tree/main/src/isaacus/_response.py) object.
@@ -263,7 +263,7 @@ To stream the response body, use `.with_streaming_response` instead, which requi
 with client.classifications.universal.with_streaming_response.create(
     model="kanon-universal-classifier",
     query="This is a confidentiality clause.",
-    text="I agree not to tell anyone about the document.",
+    texts=["I agree not to tell anyone about the document."],
 ) as response:
     print(response.headers.get("X-My-Header"))
 

src/isaacus/resources/classifications/universal.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import List, Optional
 from typing_extensions import Literal
 
 import httpx
@@ -52,7 +52,7 @@ def create(
         *,
         model: Literal["kanon-universal-classifier", "kanon-universal-classifier-mini"],
         query: str,
-        text: str,
+        texts: List[str],
         chunking_options: Optional[universal_create_params.ChunkingOptions] | NotGiven = NOT_GIVEN,
         is_iql: bool | NotGiven = NOT_GIVEN,
         scoring_method: Literal["auto", "chunk_max", "chunk_avg", "chunk_min"] | NotGiven = NOT_GIVEN,
@@ -64,24 +64,24 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> UniversalClassification:
         """
-        Classify the relevance of a legal document to a query with an Isaacus universal
+        Classify the relevance of legal documents to a query with an Isaacus universal
         legal AI classifier.
 
         Args:
           model: The ID of the [model](https://docs.isaacus.com/models#universal-classification)
               to use for universal classification.
 
           query: The [Isaacus Query Language (IQL)](https://docs.isaacus.com/iql) query or, if
-              IQL is disabled, the statement, to evaluate the text against.
+              IQL is disabled, the statement, to evaluate the texts against.
 
               The query must contain at least one non-whitespace character.
 
-              Unlike the text being classified, the query cannot be so long that it exceeds
+              Unlike the texts being classified, the query cannot be so long that it exceeds
               the maximum input length of the universal classifier.
 
-          text: The text to classify.
+          texts: The texts to classify.
 
-              The text must contain at least one non-whitespace character.
+              The texts must contain at least one non-whitespace character.
 
           chunking_options: Options for how to split text into smaller chunks.
 
@@ -92,13 +92,13 @@ def create(
 
               `auto` is the default scoring method and is recommended for most use cases.
               Currently, it is equivalent to `chunk_max`. In the future, it will automatically
-              select the best method based on the model and input.
+              select the best method based on the model and inputs.
 
-              `chunk_max` uses the highest confidence score of all of the text's chunks.
+              `chunk_max` uses the highest confidence score of all of the texts' chunks.
 
-              `chunk_avg` averages the confidence scores of all of the text's chunks.
+              `chunk_avg` averages the confidence scores of all of the texts' chunks.
 
-              `chunk_min` uses the lowest confidence score of all of the text's chunks.
+              `chunk_min` uses the lowest confidence score of all of the texts' chunks.
 
           extra_headers: Send extra headers
 
@@ -114,7 +114,7 @@ def create(
                 {
                     "model": model,
                     "query": query,
-                    "text": text,
+                    "texts": texts,
                     "chunking_options": chunking_options,
                     "is_iql": is_iql,
                     "scoring_method": scoring_method,
@@ -153,7 +153,7 @@ async def create(
         *,
         model: Literal["kanon-universal-classifier", "kanon-universal-classifier-mini"],
         query: str,
-        text: str,
+        texts: List[str],
         chunking_options: Optional[universal_create_params.ChunkingOptions] | NotGiven = NOT_GIVEN,
         is_iql: bool | NotGiven = NOT_GIVEN,
         scoring_method: Literal["auto", "chunk_max", "chunk_avg", "chunk_min"] | NotGiven = NOT_GIVEN,
@@ -165,24 +165,24 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> UniversalClassification:
         """
-        Classify the relevance of a legal document to a query with an Isaacus universal
+        Classify the relevance of legal documents to a query with an Isaacus universal
         legal AI classifier.
 
         Args:
           model: The ID of the [model](https://docs.isaacus.com/models#universal-classification)
               to use for universal classification.
 
           query: The [Isaacus Query Language (IQL)](https://docs.isaacus.com/iql) query or, if
-              IQL is disabled, the statement, to evaluate the text against.
+              IQL is disabled, the statement, to evaluate the texts against.
 
               The query must contain at least one non-whitespace character.
 
-              Unlike the text being classified, the query cannot be so long that it exceeds
+              Unlike the texts being classified, the query cannot be so long that it exceeds
               the maximum input length of the universal classifier.
 
-          text: The text to classify.
+          texts: The texts to classify.
 
-              The text must contain at least one non-whitespace character.
+              The texts must contain at least one non-whitespace character.
 
           chunking_options: Options for how to split text into smaller chunks.
 
@@ -193,13 +193,13 @@ async def create(
 
               `auto` is the default scoring method and is recommended for most use cases.
               Currently, it is equivalent to `chunk_max`. In the future, it will automatically
-              select the best method based on the model and input.
+              select the best method based on the model and inputs.
 
-              `chunk_max` uses the highest confidence score of all of the text's chunks.
+              `chunk_max` uses the highest confidence score of all of the texts' chunks.
 
-              `chunk_avg` averages the confidence scores of all of the text's chunks.
+              `chunk_avg` averages the confidence scores of all of the texts' chunks.
 
-              `chunk_min` uses the lowest confidence score of all of the text's chunks.
+              `chunk_min` uses the lowest confidence score of all of the texts' chunks.
 
           extra_headers: Send extra headers
 
@@ -215,7 +215,7 @@ async def create(
                 {
                     "model": model,
                     "query": query,
-                    "text": text,
+                    "texts": texts,
                     "chunking_options": chunking_options,
                     "is_iql": is_iql,
                     "scoring_method": scoring_method,

src/isaacus/types/classifications/universal_classification.py

@@ -4,15 +4,22 @@
 
 from ..._models import BaseModel
 
-__all__ = ["UniversalClassification", "Chunk", "Usage"]
+__all__ = ["UniversalClassification", "Classification", "ClassificationChunk", "Usage"]
 
 
-class Chunk(BaseModel):
+class ClassificationChunk(BaseModel):
     end: int
-    """The end index of the chunk in the original text."""
+    """
+    The index of the character in the original text where the chunk ends, beginning
+    from `0` (such that, in Python, the chunk is equivalent to `text[start:end+1]`).
+    """
 
     index: int
-    """The index of the chunk in the list of chunks."""
+    """
+    The original position of the chunk in the outputted list of chunks before
+    sorting, starting from `0` (and, therefore, ending at the number of chunks minus
+    `1`).
+    """
 
     score: float
     """
@@ -24,19 +31,17 @@ class Chunk(BaseModel):
     """
 
     start: int
-    """The start index of the chunk in the original text."""
+    """
+    The index of the character in the original text where the chunk starts,
+    beginning from `0`.
+    """
 
     text: str
     """The text of the chunk."""
 
 
-class Usage(BaseModel):
-    input_tokens: int
-    """The number of tokens inputted to the model."""
-
-
-class UniversalClassification(BaseModel):
-    chunks: Optional[List[Chunk]] = None
+class Classification(BaseModel):
+    chunks: Optional[List[ClassificationChunk]] = None
     """
     The text as broken into chunks by
     [semchunk](https://github.com/isaacus-dev/semchunk), each chunk with its own
@@ -45,6 +50,12 @@ class UniversalClassification(BaseModel):
     If no chunking occurred, this will be `null`.
     """
 
+    index: int
+    """
+    The index of the text in the input array of texts, starting from `0` (and,
+    therefore, ending at the number of texts minus `1`).
+    """
+
     score: float
     """
     A score of the likelihood that the query expressed about the text is supported
@@ -54,5 +65,18 @@ class UniversalClassification(BaseModel):
     score less than `0.5` indicates that the text does not support the query.
     """
 
+
+class Usage(BaseModel):
+    input_tokens: int
+    """The number of tokens inputted to the model."""
+
+
+class UniversalClassification(BaseModel):
+    classifications: List[Classification]
+    """
+    The classifications of the texts, by relevance to the query, in order from
+    highest to lowest relevance score.
+    """
+
     usage: Usage
     """Statistics about the usage of resources in the process of classifying the text."""

src/isaacus/types/classifications/universal_create_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import List, Optional
 from typing_extensions import Literal, Required, TypedDict
 
 __all__ = ["UniversalCreateParams", "ChunkingOptions"]
@@ -18,18 +18,18 @@ class UniversalCreateParams(TypedDict, total=False):
     query: Required[str]
     """
     The [Isaacus Query Language (IQL)](https://docs.isaacus.com/iql) query or, if
-    IQL is disabled, the statement, to evaluate the text against.
+    IQL is disabled, the statement, to evaluate the texts against.
 
     The query must contain at least one non-whitespace character.
 
-    Unlike the text being classified, the query cannot be so long that it exceeds
+    Unlike the texts being classified, the query cannot be so long that it exceeds
     the maximum input length of the universal classifier.
     """
 
-    text: Required[str]
-    """The text to classify.
+    texts: Required[List[str]]
+    """The texts to classify.
 
-    The text must contain at least one non-whitespace character.
+    The texts must contain at least one non-whitespace character.
     """
 
     chunking_options: Optional[ChunkingOptions]
@@ -46,13 +46,13 @@ class UniversalCreateParams(TypedDict, total=False):
 
     `auto` is the default scoring method and is recommended for most use cases.
     Currently, it is equivalent to `chunk_max`. In the future, it will automatically
-    select the best method based on the model and input.
+    select the best method based on the model and inputs.
 
-    `chunk_max` uses the highest confidence score of all of the text's chunks.
+    `chunk_max` uses the highest confidence score of all of the texts' chunks.
 
-    `chunk_avg` averages the confidence scores of all of the text's chunks.
+    `chunk_avg` averages the confidence scores of all of the texts' chunks.
 
-    `chunk_min` uses the lowest confidence score of all of the text's chunks.
+    `chunk_min` uses the lowest confidence score of all of the texts' chunks.
     """