sapling-py 4.1.0__tar.gz → 4.2.0__tar.gz

{sapling_py-4.1.0/sapling_py.egg-info → sapling_py-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sapling-py
-Version: 4.1.0
+Version: 4.2.0
 Summary: Sapling Python Client
 Home-page: https://sapling.ai
 Author: Sapling Intelligence
@@ -40,7 +40,9 @@ Compare against leading grammar checking tools and APIs like Grammarly (Grammerl
 ## Overview
 
 Sapling is a toolkit for helping developers build language model-powered applications.
-The API provides spelling and grammar checking, autocomplete, tone detection, rephrasing, AI detection, and more.
+The API provides spelling and grammar checking, autocomplete, tone detection, rephrasing, AI detection,
+zero-shot text classification, structured data extraction, PII detection and redaction, content safety
+scoring, SEO analysis, and more.
 
 Key Features:
 - **60% More Corrections**: Outperforms [competing solutions](https://sapling.ai/comparison/api#sapling) at similar accuracy levels using state-of-the-art generative AI models.

{sapling_py-4.1.0 → sapling_py-4.2.0}/README.md

@@ -8,7 +8,9 @@ Compare against leading grammar checking tools and APIs like Grammarly (Grammerl
 ## Overview
 
 Sapling is a toolkit for helping developers build language model-powered applications.
-The API provides spelling and grammar checking, autocomplete, tone detection, rephrasing, AI detection, and more.
+The API provides spelling and grammar checking, autocomplete, tone detection, rephrasing, AI detection,
+zero-shot text classification, structured data extraction, PII detection and redaction, content safety
+scoring, SEO analysis, and more.
 
 Key Features:
 - **60% More Corrections**: Outperforms [competing solutions](https://sapling.ai/comparison/api#sapling) at similar accuracy levels using state-of-the-art generative AI models.

{sapling_py-4.1.0 → sapling_py-4.2.0}/sapling/client.py

@@ -1,5 +1,6 @@
 import requests
 import uuid
+from collections.abc import Iterable
 
 
 class SaplingError(Exception):
@@ -631,6 +632,92 @@ class SaplingClient:
         }
         return self._request(url, data)
 
+    def extract(
+        self,
+        text,
+        fields,
+        context=None,
+    ):
+        '''
+        Extracts structured data from unstructured text: you name the fields you
+        want, the API returns their values pulled from the document. Every value is
+        grounded in a verbatim span of the input, so this is extraction rather than
+        summarization or inference; a field the text does not state is reported
+        missing rather than guessed.
+
+        Example::
+
+            client.extract(
+                'Invoice INV-1042 for Acme Corp, total $1,299.00, due March 5, 2026.',
+                fields=[
+                    'invoice_number',
+                    {'name': 'total', 'type': 'number', 'description': 'Amount due',
+                     'required': True},
+                    {'name': 'due_date', 'type': 'date'},
+                    'purchase_order',
+                ],
+                context='A vendor invoice',
+            )
+            # {'data': {'invoice_number': 'INV-1042', 'total': 1299.0,
+            #           'due_date': '2026-03-05', 'purchase_order': None},
+            #  'fields': [{'name': 'invoice_number', 'type': 'string',
+            #              'value': 'INV-1042', 'evidence': 'Invoice INV-1042',
+            #              'found': True},
+            #             {'name': 'total', 'type': 'number', 'value': 1299.0,
+            #              'evidence': 'total $1,299.00', 'found': True},
+            #             {'name': 'due_date', 'type': 'date', 'value': '2026-03-05',
+            #              'evidence': 'due March 5, 2026', 'found': True},
+            #             {'name': 'purchase_order', 'type': 'string', 'value': None,
+            #              'evidence': '', 'found': False}],
+            #  'missing': ['purchase_order']}
+
+        :param text: Document to extract from, plain text or HTML (tags are
+            stripped), up to 10,000 characters.
+        :type text: str
+        :param fields: 1-20 fields to extract. Each entry is either a field name
+            (str) or a dict ``{'name': str, 'type': str, 'description': str,
+            'required': bool}`` where everything but ``name`` is optional. Names are
+            up to 50 characters and must be unique (case-insensitive). ``type`` is
+            one of ``'string'`` (the default), ``'number'``, ``'integer'``,
+            ``'boolean'``, ``'date'`` or ``'list'``. ``description`` is up to 200
+            characters and sharpens ambiguous fields. ``required`` is a hint to the
+            model; a required field the text does not state is still reported
+            missing, never guessed.
+        :type fields: list[str | dict]
+        :raises TypeError: If ``fields`` is None, a single string or a dict rather
+            than a list/tuple of fields.
+        :param context: Up to 500 characters describing what the document is or how
+            to read ambiguous fields (e.g. ``'A vendor invoice'``).
+        :type context: str
+        :rtype: dict
+        :return:
+            - data: ``{field name: value}`` map. Every requested field is present,
+              with ``None`` where the text did not state it. ``date`` values are
+              ``YYYY-MM-DD`` strings and ``list`` values are lists of strings.
+            - fields: One dict per requested field, in the order requested, with
+              ``name``, ``type``, ``value``, the verbatim ``evidence`` span the value
+              came from (``''`` when not found) and ``found``.
+            - missing: Names of the fields the text did not yield, in request order.
+              Finding nothing is a normal, successful response.
+        '''
+        # A bare string would silently be split into one-character field names,
+        # a dict would be reduced to its keys, and a non-iterable (None, an int)
+        # would raise an opaque "'int' object is not iterable" from list().
+        # Fail loudly with a message that names the right shape instead.
+        if (not isinstance(fields, Iterable)
+                or isinstance(fields, (str, bytes, dict))):
+            raise TypeError('fields must be a list of field names or '
+                            '{name, type, description, required} dicts')
+        url = self.url_endpoint + 'extract'
+        data = {
+            'key': self.api_key,
+            'text': text,
+            'fields': list(fields),
+        }
+        if context is not None:
+            data['context'] = context
+        return self._request(url, data)
+
     def tone(
         self,
         text,
@@ -682,43 +769,79 @@ class SaplingClient:
     def quality(
         self,
         text,
+        sentence_scores=None,
+        rubric=None,
     ):
         '''
         Computes a quality score for the provided text based on how "surprising"
         the text is to the model. Lower surprisal corresponds to higher scores.
+        Optionally also returns a per-sentence breakdown and an LLM-judged rubric.
 
-        :param text: Text to compute a quality score for.
+        :param text: Text to compute a quality score for. The base score is computed
+            on the leading ~4,000 characters; the rubric evaluates the whole text
+            (up to 20,000 characters).
         :type text: str
+        :param sentence_scores: If true, also return a 1-5 score for each sentence
+            under `sentences`.
+        :type sentence_scores: bool
+        :param rubric: If true, also return an LLM-judged rubric under `rubric`
+            (billed at the Tone rate).
+        :type rubric: bool
         :rtype: dict
         :return:
             - score: A score from 1 (low quality) to 5 (high quality).
+            - sentences: If sentence_scores is set, list of {start, end, text, score} in
+              document order; start/end are character offsets into the text.
+            - rubric: If rubric is set, {overall, dimensions: {clarity, coherence,
+              correctness, concision}, summary, issues: [{quote, dimension, note,
+              suggestion, start, end}]}; scores are integers 1-5.
         '''
         url = self.url_endpoint + 'quality'
         data = {
             'key': self.api_key,
             'text': text,
         }
+        if sentence_scores is not None:
+            data['sentence_scores'] = sentence_scores
+        if rubric is not None:
+            data['rubric'] = rubric
         return self._request(url, data)
 
     def langdetect(
         self,
         text,
+        top_k=None,
+        segments=None,
     ):
         '''
-        Identifies the language of the provided text.
+        Identifies the language of the provided text, with optional runner-up
+        candidates and a per-segment breakdown for mixed-language text.
 
-        :param text: Text to identify the language for.
+        :param text: Text to identify the language for (up to 20,000 characters).
         :type text: str
+        :param top_k: Number of language candidates to return, 1-10. Defaults to 3 server-side.
+        :type top_k: int
+        :param segments: If true, also detect the language of each line/sentence
+            of the text and return them under `segments`.
+        :type segments: bool
         :rtype: dict
         :return:
-            - lang: The detected language code.
+            - lang: The detected language code (mostly ISO 639-1).
+            - name: English name of the detected language.
             - conf: Confidence score for the detection result.
+            - candidates: List of {lang, name, conf} for the top languages, most likely first.
+            - segments: If segments is set, list of {start, end, text, lang, name, conf, candidates}
+              in document order; start/end are character offsets into the text.
         '''
         url = self.url_endpoint + 'langdetect'
         data = {
             'key': self.api_key,
             'text': text,
         }
+        if top_k is not None:
+            data['top_k'] = top_k
+        if segments is not None:
+            data['segments'] = segments
         return self._request(url, data)
 
     def profanity(
@@ -741,3 +864,229 @@ class SaplingClient:
             'text': text,
         }
         return self._request(url, data)
+
+    def safety(
+        self,
+        text,
+        threshold=None,
+    ):
+        '''
+        Scores the provided text on seven content-safety categories: toxicity,
+        profanity, harassment, hate_speech, self_harm, sexual, and violence.
+
+        :param text: Text to score, up to 20,000 characters.
+        :type text: str
+        :param threshold: Score at or above which a category is flagged.
+            Between 0 and 1 inclusive; the API defaults to 0.5.
+        :type threshold: float
+        :rtype: dict
+        :return:
+            - scores: A probability from 0 to 1 for each category.
+            - flagged: True if any category scored at or above the threshold.
+            - flagged_categories: Categories that scored at or above the threshold.
+            - threshold: The threshold that was applied.
+        '''
+        url = self.url_endpoint + 'safety'
+        data = {
+            'key': self.api_key,
+            'text': text,
+        }
+        if threshold is not None:
+            data['threshold'] = threshold
+        return self._request(url, data)
+
+    def pii(
+        self,
+        text,
+        types=None,
+        redact=None,
+    ):
+        '''
+        Detects personally identifiable information (PII) in the provided text and
+        optionally returns a redacted copy.
+
+        Detection is deterministic (pattern matching plus checksum validation, no ML)
+        and every entity comes with exact character offsets into ``text``, so pass
+        raw text (not HTML) and apply the spans to your own copy of the document.
+        Person names and street addresses are not detected.
+
+        :param text: Text to scan for PII.
+        :type text: str
+        :param types: Optional list of PII types to detect. Defaults to all types:
+            ``email``, ``phone``, ``ssn``, ``credit_card``, ``ip_address``, ``iban``,
+            ``us_bank_routing``.
+        :type types: list[str]
+        :param redact: If True, the response also includes ``redacted_text`` with every
+            detected entity replaced by a placeholder such as ``[EMAIL]``.
+        :type redact: bool
+        :rtype: dict
+        :return:
+            - entities: List of ``{type, text, start, end, replacement}`` dicts, sorted
+              by ``start``; spans never overlap.
+            - flagged: True if any PII was detected.
+            - types: Sorted list of the PII types found.
+            - redacted_text: Only present when ``redact`` is True.
+        '''
+        url = self.url_endpoint + 'pii'
+        data = {
+            'key': self.api_key,
+            'text': text,
+        }
+        if types is not None:
+            if (not isinstance(types, Iterable)
+                    or isinstance(types, (str, bytes, dict))):
+                raise TypeError('types must be a list of entity type names')
+            data['types'] = list(types)
+        if redact is not None:
+            data['redact'] = redact
+        return self._request(url, data)
+
+    def seo(
+        self,
+        text,
+        keywords=None,
+        suggestions=None,
+        lang=None,
+    ):
+        '''
+        Analyzes the provided page or article text for SEO: deterministic content
+        statistics and readability, target-keyword usage, the most frequent terms, and
+        (optionally) LLM-generated titles, meta descriptions, a URL slug, and focus
+        keywords.
+
+        :param text: Page or article body, plain text or HTML (block tags become line
+            breaks, inline tags are removed), up to 20,000 characters.
+        :type text: str
+        :param keywords: Optional list of up to 10 target keyword phrases, most
+            important first (the first is the primary keyword). Each 1-100 characters.
+            Measured in the text and steered into the suggestions.
+        :type keywords: list[str]
+        :param suggestions: If False, only the deterministic ``stats``, ``keywords`` and
+            ``top_terms`` are returned (free); no ``suggestions`` are generated. The API
+            defaults to True (billed at the Tone rate).
+        :type suggestions: bool
+        :param lang: ISO 639-1 language code of the text (a region subtag such as
+            ``pt-BR`` is allowed, or ``auto``). The API defaults to ``en``. Only selects
+            the readability formulas: ``flesch_reading_ease`` and
+            ``flesch_kincaid_grade`` are computed for ``en``, ``de``, ``es``, ``fr``,
+            ``it``, ``nl``, ``pl`` and ``ru`` and are None for any other language.
+        :type lang: str
+        :rtype: dict
+        :return:
+            - stats: ``{chars, words, sentences, paragraphs, reading_time_min,
+              flesch_reading_ease, flesch_kincaid_grade}``; the two readability fields
+              are None for languages without readability support.
+            - keywords: One ``{keyword, count, density, in_first_100_words}`` dict per
+              submitted target keyword, in the same order; empty when none were sent.
+            - top_terms: Up to 10 most frequent content unigrams/bigrams as
+              ``{term, count}`` dicts (lower-cased, English stopwords removed).
+            - suggestions: Only present when ``suggestions`` is not False:
+              ``{titles, meta_descriptions, slug, keywords}`` where ``titles`` and
+              ``meta_descriptions`` are lists of strings, ``slug`` is a kebab-case
+              string (or None when no ASCII slug could be derived, e.g. purely CJK
+              content) and ``keywords`` is a list of focus-keyword phrases.
+        '''
+        url = self.url_endpoint + 'seo'
+        data = {
+            'key': self.api_key,
+            'text': text,
+        }
+        if keywords is not None:
+            if (not isinstance(keywords, Iterable)
+                    or isinstance(keywords, (str, bytes, dict))):
+                raise TypeError('keywords must be a list of keyword strings')
+            data['keywords'] = list(keywords)
+        if suggestions is not None:
+            data['suggestions'] = suggestions
+        if lang is not None:
+            data['lang'] = lang
+        return self._request(url, data)
+
+    def classify(
+        self,
+        text,
+        labels,
+        multi_label=None,
+        threshold=None,
+        context=None,
+    ):
+        '''
+        Classifies the provided text into one (or several) of the labels you supply.
+        Zero-shot: no training data or setup is needed, just the label names and,
+        optionally, a short description per label.
+
+        Example::
+
+            client.classify(
+                'I was charged twice for my last invoice.',
+                labels=[
+                    'billing',
+                    {'name': 'technical issue', 'description': 'Bugs, crashes, errors'},
+                    'shipping',
+                    'other',
+                ],
+                context='Support tickets for a SaaS billing product',
+            )
+            # {'label': 'billing',
+            #  'labels': ['billing'],
+            #  'scores': [{'label': 'billing', 'score': 0.86},
+            #             {'label': 'technical issue', 'score': 0.07},
+            #             {'label': 'shipping', 'score': 0.04},
+            #             {'label': 'other', 'score': 0.03}],
+            #  'rationale': 'The customer reports being charged twice on one invoice.',
+            #  'multi_label': False}
+
+        :param text: Text to classify, plain text or HTML (tags are stripped), up to
+            10,000 characters.
+        :type text: str
+        :param labels: 2-20 candidate labels. Each entry is either a label name (str) or
+            a dict ``{'name': str, 'description': str}`` where ``description`` is
+            optional. Names are up to 50 characters and must be unique
+            (case-insensitive); descriptions are up to 200 characters and help the
+            model with borderline decisions.
+        :type labels: list[str | dict]
+        :raises TypeError: If ``labels`` is None, a single string or a dict rather
+            than a list/tuple of labels.
+        :param multi_label: If False (the API default), exactly one label applies and
+            the scores form a probability distribution over the labels. If True, zero,
+            one or several labels may apply and each score is an independent 0-1
+            probability.
+        :type multi_label: bool
+        :param threshold: Multi-label cut-off, 0-1: ``labels`` in the response contains
+            every label with ``score >= threshold``. The API defaults to 0.5. Ignored in
+            single-label mode.
+        :type threshold: float
+        :param context: Up to 500 characters describing what the texts are or how to
+            decide (e.g. ``'Support tickets for a SaaS billing product'``). Guidance
+            only; the model can still only answer with the labels you provide.
+        :type context: str
+        :rtype: dict
+        :return:
+            - label: Best-matching label name (always one of the input labels).
+            - labels: Single-label mode: ``[label]``. Multi-label mode: every label
+              with ``score >= threshold``, descending by score; may be empty when none
+              of the labels apply.
+            - scores: One ``{label, score}`` dict per input label, sorted descending
+              by score (0-1, rounded to 4 decimals).
+            - rationale: One sentence naming the evidence in the text (may be empty).
+            - multi_label: The mode that was used.
+        '''
+        # A bare string would silently be split into one-character labels and
+        # None would raise an opaque TypeError from list(); fail loudly instead.
+        if (not isinstance(labels, Iterable)
+                or isinstance(labels, (str, bytes, dict))):
+            raise TypeError('labels must be a list of label names or '
+                            '{name, description} dicts')
+        url = self.url_endpoint + 'classify'
+        data = {
+            'key': self.api_key,
+            'text': text,
+            'labels': list(labels),
+        }
+        if multi_label is not None:
+            data['multi_label'] = multi_label
+        if threshold is not None:
+            data['threshold'] = threshold
+        if context is not None:
+            data['context'] = context
+        return self._request(url, data)

sapling_py-4.2.0/sapling/version.py

@@ -0,0 +1 @@
+__version__ = '4.2.0'

{sapling_py-4.1.0 → sapling_py-4.2.0/sapling_py.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sapling-py
-Version: 4.1.0
+Version: 4.2.0
 Summary: Sapling Python Client
 Home-page: https://sapling.ai
 Author: Sapling Intelligence
@@ -40,7 +40,9 @@ Compare against leading grammar checking tools and APIs like Grammarly (Grammerl
 ## Overview
 
 Sapling is a toolkit for helping developers build language model-powered applications.
-The API provides spelling and grammar checking, autocomplete, tone detection, rephrasing, AI detection, and more.
+The API provides spelling and grammar checking, autocomplete, tone detection, rephrasing, AI detection,
+zero-shot text classification, structured data extraction, PII detection and redaction, content safety
+scoring, SEO analysis, and more.
 
 Key Features:
 - **60% More Corrections**: Outperforms [competing solutions](https://sapling.ai/comparison/api#sapling) at similar accuracy levels using state-of-the-art generative AI models.

{sapling_py-4.1.0 → sapling_py-4.2.0}/sapling_py.egg-info/SOURCES.txt

@@ -9,5 +9,9 @@ sapling_py.egg-info/SOURCES.txt
 sapling_py.egg-info/dependency_links.txt
 sapling_py.egg-info/requires.txt
 sapling_py.egg-info/top_level.txt
-test/__init__.py
-test/test_client.py
+test/test_classify.py
+test/test_client.py
+test/test_extract.py
+test/test_pii.py
+test/test_safety.py
+test/test_seo.py

sapling_py-4.2.0/test/test_classify.py

@@ -0,0 +1,200 @@
+import json
+
+import pytest
+import responses
+
+from sapling import SaplingClient, SaplingError
+
+API_KEY = 'a' * 32
+BASE = 'https://api.sapling.ai/api/v1/'
+
+LABELS = ['billing', 'technical issue', 'shipping', 'other']
+
+CLASSIFY_RESPONSE = {
+    'label': 'billing',
+    'labels': ['billing'],
+    'scores': [
+        {'label': 'billing', 'score': 0.86},
+        {'label': 'technical issue', 'score': 0.07},
+        {'label': 'shipping', 'score': 0.04},
+        {'label': 'other', 'score': 0.03},
+    ],
+    'rationale': 'The customer reports being charged twice on one invoice.',
+    'multi_label': False,
+}
+
+MULTI_LABEL_RESPONSE = {
+    'label': 'billing',
+    'labels': ['billing', 'technical issue'],
+    'scores': [
+        {'label': 'billing', 'score': 0.92},
+        {'label': 'technical issue', 'score': 0.81},
+        {'label': 'shipping', 'score': 0.03},
+        {'label': 'other', 'score': 0.02},
+    ],
+    'rationale': 'Mentions a duplicate charge and an app crash.',
+    'multi_label': True,
+}
+
+
+@pytest.fixture
+def client():
+    return SaplingClient(api_key=API_KEY)
+
+
+def _last_request_body():
+    return json.loads(responses.calls[-1].request.body)
+
+
+@responses.activate
+def test_classify_returns_json_and_sends_key(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    result = client.classify('I was charged twice for my last invoice.', LABELS)
+    assert result == CLASSIFY_RESPONSE
+    body = _last_request_body()
+    assert body == {'key': API_KEY, 'text': 'I was charged twice for my last invoice.',
+                    'labels': LABELS}
+
+
+@responses.activate
+def test_classify_posts_to_classify_endpoint(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    client.classify('some text', LABELS)
+    assert len(responses.calls) == 1
+    assert responses.calls[0].request.url == BASE + 'classify'
+    assert responses.calls[0].request.method == 'POST'
+
+
+@responses.activate
+def test_classify_label_dicts_passed_through(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    labels = [
+        'billing',
+        {'name': 'technical issue', 'description': 'Bugs, crashes, errors'},
+        {'name': 'shipping'},
+        'other',
+    ]
+    client.classify('some text', labels)
+    body = _last_request_body()
+    assert body['labels'] == labels
+
+
+@responses.activate
+def test_classify_labels_tuple_sent_as_list(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    client.classify('some text', ('billing', 'shipping'))
+    body = _last_request_body()
+    assert body['labels'] == ['billing', 'shipping']
+
+
+@responses.activate
+def test_classify_optional_params_omitted_by_default(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    client.classify('some text', LABELS)
+    body = _last_request_body()
+    assert 'multi_label' not in body
+    assert 'threshold' not in body
+    assert 'context' not in body
+
+
+@responses.activate
+def test_classify_optional_params_sent_when_provided(client):
+    responses.add(responses.POST, BASE + 'classify', json=MULTI_LABEL_RESPONSE, status=200)
+    result = client.classify('I was charged twice and the app crashes on launch', LABELS,
+                             multi_label=True, threshold=0.7,
+                             context='Support tickets for a SaaS billing product')
+    assert result == MULTI_LABEL_RESPONSE
+    assert result['labels'] == ['billing', 'technical issue']
+    body = _last_request_body()
+    assert body == {'key': API_KEY,
+                    'text': 'I was charged twice and the app crashes on launch',
+                    'labels': LABELS,
+                    'multi_label': True, 'threshold': 0.7,
+                    'context': 'Support tickets for a SaaS billing product'}
+
+
+@responses.activate
+def test_classify_multi_label_false_sent(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    client.classify('some text', LABELS, multi_label=False)
+    body = _last_request_body()
+    assert body['multi_label'] is False
+    assert 'threshold' not in body
+    assert 'context' not in body
+
+
+@responses.activate
+def test_classify_threshold_zero_sent(client):
+    responses.add(responses.POST, BASE + 'classify', json=MULTI_LABEL_RESPONSE, status=200)
+    client.classify('some text', LABELS, multi_label=True, threshold=0)
+    body = _last_request_body()
+    assert body['threshold'] == 0
+    assert body['multi_label'] is True
+
+
+@responses.activate
+def test_classify_context_sent_when_provided(client):
+    responses.add(responses.POST, BASE + 'classify', json=CLASSIFY_RESPONSE, status=200)
+    client.classify('some text', LABELS, context='Product reviews')
+    body = _last_request_body()
+    assert body['context'] == 'Product reviews'
+    assert 'multi_label' not in body
+    assert 'threshold' not in body
+
+
+@responses.activate
+def test_classify_multi_label_empty_labels_returned_verbatim(client):
+    # "None of these apply" is a valid multi-label answer.
+    payload = dict(MULTI_LABEL_RESPONSE, labels=[], rationale='')
+    responses.add(responses.POST, BASE + 'classify', json=payload, status=200)
+    result = client.classify('some text', LABELS, multi_label=True, threshold=0.95)
+    assert result['labels'] == []
+    assert result['rationale'] == ''
+    assert result['scores'] == MULTI_LABEL_RESPONSE['scores']
+
+
+@responses.activate
+def test_classify_error_raises_saplingerror_with_body(client):
+    responses.add(responses.POST, BASE + 'classify',
+                  json={'msg': 'Invalid labels: Needs between 2 and 20 labels.'}, status=400)
+    with pytest.raises(SaplingError) as exc_info:
+        client.classify('some text', ['only one'])
+    err = exc_info.value
+    assert err.status_code == 400
+    assert 'Invalid labels: Needs between 2 and 20 labels.' in str(err)
+
+
+@responses.activate
+def test_classify_upstream_error_raises_saplingerror(client):
+    responses.add(responses.POST, BASE + 'classify',
+                  json={'msg': 'Unexpected error classifying text.'}, status=502)
+    with pytest.raises(SaplingError) as exc_info:
+        client.classify('some text', LABELS)
+    err = exc_info.value
+    assert err.status_code == 502
+    assert 'Unexpected error classifying text.' in str(err)
+
+
+@responses.activate
+def test_classify_unauthorized_raises_saplingerror(client):
+    responses.add(responses.POST, BASE + 'classify', json={'msg': 'Invalid API key.'},
+                  status=401)
+    with pytest.raises(SaplingError) as exc_info:
+        client.classify('some text', LABELS)
+    assert exc_info.value.status_code == 401
+
+
+@responses.activate
+def test_classify_custom_hostname_and_pathname():
+    client = SaplingClient(api_key=API_KEY, hostname='https://sapling.example.com',
+                           pathname='/custom/v1/')
+    responses.add(responses.POST, 'https://sapling.example.com/custom/v1/classify',
+                  json=CLASSIFY_RESPONSE, status=200)
+    result = client.classify('some text', LABELS)
+    assert result == CLASSIFY_RESPONSE
+
+
+@pytest.mark.parametrize('bad_labels', [None, 'billing', b'billing', {'name': 'billing'}, 42, True])
+def test_classify_rejects_non_list_labels(client, bad_labels):
+    with pytest.raises(TypeError):
+        client.classify('I was charged twice.', bad_labels)

{sapling_py-4.1.0 → sapling_py-4.2.0}/test/test_client.py

@@ -139,6 +139,10 @@ def test_rephrase_sends_expected_params(client):
         ('quality', 'quality', {'score': 3.5}),
         ('langdetect', 'langdetect', {'lang': 'en', 'conf': 0.99}),
         ('profanity', 'profanity', {'toks': ['a'], 'labels': [0]}),
+        ('safety', 'safety', {
+            'scores': {'toxicity': 0.9}, 'flagged': True,
+            'flagged_categories': ['toxicity'], 'threshold': 0.5,
+        }),
     ],
 )
 @responses.activate
@@ -150,9 +154,42 @@ def test_single_text_endpoints(client, method, path, payload):
     assert body == {'key': API_KEY, 'text': 'some text'}
 
 
+@responses.activate
+def test_langdetect_options(client):
+    payload = {
+        'lang': 'en', 'name': 'English', 'conf': 0.6,
+        'candidates': [{'lang': 'en', 'name': 'English', 'conf': 0.6}],
+        'segments': [{'start': 0, 'end': 5, 'text': 'Hello', 'lang': 'en', 'name': 'English',
+                      'conf': 0.9, 'candidates': [{'lang': 'en', 'name': 'English', 'conf': 0.9}]}],
+    }
+    responses.add(responses.POST, BASE + 'langdetect', json=payload, status=200)
+    result = client.langdetect('Hello', top_k=1, segments=True)
+    assert result == payload
+    assert _last_request_body() == {'key': API_KEY, 'text': 'Hello', 'top_k': 1, 'segments': True}
+
+
 @responses.activate
 def test_hostname_and_pathname_override():
     client = SaplingClient(api_key=API_KEY, hostname='http://localhost:5000', pathname='/api/v1/')
     responses.add(responses.POST, 'http://localhost:5000/api/v1/edits', json={'edits': []}, status=200)
     client.edits('hi')
     assert responses.calls[-1].request.url == 'http://localhost:5000/api/v1/edits'
+
+@responses.activate
+def test_quality_options(client):
+    payload = {
+        'score': 3.4,
+        'sentences': [{'start': 0, 'end': 5, 'text': 'Hello', 'score': 4.1}],
+        'rubric': {
+            'overall': 3,
+            'dimensions': {'clarity': 4, 'coherence': 3, 'correctness': 3, 'concision': 2},
+            'summary': 'Fine.',
+            'issues': [{'quote': 'Hello', 'dimension': 'clarity', 'note': 'n',
+                        'suggestion': 'Hi', 'start': 0, 'end': 5}],
+        },
+    }
+    responses.add(responses.POST, BASE + 'quality', json=payload, status=200)
+    result = client.quality('Hello', sentence_scores=True, rubric=True)
+    assert result == payload
+    assert _last_request_body() == {'key': API_KEY, 'text': 'Hello',
+                                    'sentence_scores': True, 'rubric': True}

sapling_py-4.2.0/test/test_extract.py

@@ -0,0 +1,213 @@
+import json
+
+import pytest
+import responses
+
+from sapling import SaplingClient, SaplingError
+
+API_KEY = 'a' * 32
+BASE = 'https://api.sapling.ai/api/v1/'
+
+TEXT = 'Invoice INV-1042 for Acme Corp, total $1,299.00, due March 5, 2026.'
+
+FIELDS = [
+    'invoice_number',
+    {'name': 'total', 'type': 'number', 'description': 'Amount due', 'required': True},
+    {'name': 'due_date', 'type': 'date'},
+    'purchase_order',
+]
+
+EXTRACT_RESPONSE = {
+    'data': {
+        'invoice_number': 'INV-1042',
+        'total': 1299.0,
+        'due_date': '2026-03-05',
+        'purchase_order': None,
+    },
+    'fields': [
+        {'name': 'invoice_number', 'type': 'string', 'value': 'INV-1042',
+         'evidence': 'Invoice INV-1042', 'found': True},
+        {'name': 'total', 'type': 'number', 'value': 1299.0,
+         'evidence': 'total $1,299.00', 'found': True},
+        {'name': 'due_date', 'type': 'date', 'value': '2026-03-05',
+         'evidence': 'due March 5, 2026', 'found': True},
+        {'name': 'purchase_order', 'type': 'string', 'value': None,
+         'evidence': '', 'found': False},
+    ],
+    'missing': ['purchase_order'],
+}
+
+
+@pytest.fixture
+def client():
+    return SaplingClient(api_key=API_KEY)
+
+
+def _last_request_body():
+    return json.loads(responses.calls[-1].request.body)
+
+
+@responses.activate
+def test_extract_returns_json_and_sends_key(client):
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    result = client.extract(TEXT, FIELDS)
+    assert result == EXTRACT_RESPONSE
+    body = _last_request_body()
+    assert body == {'key': API_KEY, 'text': TEXT, 'fields': FIELDS}
+
+
+@responses.activate
+def test_extract_posts_to_extract_endpoint(client):
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    client.extract('some text', ['invoice_number'])
+    assert len(responses.calls) == 1
+    assert responses.calls[0].request.url == BASE + 'extract'
+    assert responses.calls[0].request.method == 'POST'
+
+
+@responses.activate
+def test_extract_field_dicts_passed_through(client):
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    fields = [
+        'invoice_number',
+        {'name': 'total', 'type': 'number', 'description': 'Amount due', 'required': True},
+        {'name': 'line_items', 'type': 'list'},
+        {'name': 'is_urgent', 'type': 'boolean'},
+    ]
+    client.extract('some text', fields)
+    body = _last_request_body()
+    assert body['fields'] == fields
+
+
+@responses.activate
+def test_extract_fields_tuple_sent_as_list(client):
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    client.extract('some text', ('invoice_number', 'total'))
+    body = _last_request_body()
+    assert body['fields'] == ['invoice_number', 'total']
+
+
+@responses.activate
+def test_extract_optional_params_omitted_by_default(client):
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    client.extract('some text', FIELDS)
+    body = _last_request_body()
+    assert 'context' not in body
+
+
+@responses.activate
+def test_extract_context_sent_when_provided(client):
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    result = client.extract(TEXT, FIELDS, context='A vendor invoice')
+    assert result == EXTRACT_RESPONSE
+    body = _last_request_body()
+    assert body == {'key': API_KEY, 'text': TEXT, 'fields': FIELDS,
+                    'context': 'A vendor invoice'}
+
+
+@responses.activate
+def test_extract_empty_context_sent(client):
+    # '' is not None, so it is forwarded rather than dropped.
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    client.extract('some text', FIELDS, context='')
+    body = _last_request_body()
+    assert body['context'] == ''
+
+
+@responses.activate
+def test_extract_nothing_found_returned_verbatim(client):
+    # Finding nothing is a normal 200, not an error.
+    payload = {
+        'data': {'invoice_number': None, 'total': None},
+        'fields': [
+            {'name': 'invoice_number', 'type': 'string', 'value': None,
+             'evidence': '', 'found': False},
+            {'name': 'total', 'type': 'number', 'value': None,
+             'evidence': '', 'found': False},
+        ],
+        'missing': ['invoice_number', 'total'],
+    }
+    responses.add(responses.POST, BASE + 'extract', json=payload, status=200)
+    result = client.extract('Nothing invoice-like here.', ['invoice_number', 'total'])
+    assert result == payload
+    assert result['missing'] == ['invoice_number', 'total']
+    assert all(value is None for value in result['data'].values())
+
+
+@responses.activate
+def test_extract_error_raises_saplingerror_with_body(client):
+    responses.add(responses.POST, BASE + 'extract',
+                  json={'msg': 'Invalid fields: Needs between 1 and 20 fields.'},
+                  status=400)
+    with pytest.raises(SaplingError) as exc_info:
+        client.extract('some text', [])
+    err = exc_info.value
+    assert err.status_code == 400
+    assert 'Invalid fields: Needs between 1 and 20 fields.' in str(err)
+
+
+@responses.activate
+def test_extract_upstream_error_raises_saplingerror(client):
+    responses.add(responses.POST, BASE + 'extract',
+                  json={'msg': 'Unexpected error extracting from text.'}, status=502)
+    with pytest.raises(SaplingError) as exc_info:
+        client.extract('some text', FIELDS)
+    err = exc_info.value
+    assert err.status_code == 502
+    assert 'Unexpected error extracting from text.' in str(err)
+
+
+@responses.activate
+def test_extract_unauthorized_raises_saplingerror(client):
+    responses.add(responses.POST, BASE + 'extract', json={'msg': 'Invalid API key.'},
+                  status=401)
+    with pytest.raises(SaplingError) as exc_info:
+        client.extract('some text', FIELDS)
+    assert exc_info.value.status_code == 401
+
+
+@responses.activate
+def test_extract_rate_limited_raises_saplingerror(client):
+    responses.add(responses.POST, BASE + 'extract',
+                  json={'msg': 'Too many requests.'}, status=429)
+    with pytest.raises(SaplingError) as exc_info:
+        client.extract('some text', FIELDS)
+    assert exc_info.value.status_code == 429
+
+
+@responses.activate
+def test_extract_custom_hostname_and_pathname():
+    client = SaplingClient(api_key=API_KEY, hostname='https://sapling.example.com',
+                           pathname='/custom/v1/')
+    responses.add(responses.POST, 'https://sapling.example.com/custom/v1/extract',
+                  json=EXTRACT_RESPONSE, status=200)
+    result = client.extract(TEXT, FIELDS)
+    assert result == EXTRACT_RESPONSE
+
+
+# None / an int / a bool are not iterable at all; a str, bytes or dict is
+# iterable but into the wrong thing (characters, bytes, keys).
+BAD_FIELDS = [None, 42, 3.5, True, 'invoice_number', b'invoice_number',
+              {'name': 'invoice_number'}]
+
+
+@pytest.mark.parametrize('bad_fields', BAD_FIELDS)
+def test_extract_rejects_non_list_fields(client, bad_fields):
+    with pytest.raises(TypeError):
+        client.extract(TEXT, bad_fields)
+
+
+@pytest.mark.parametrize('bad_fields', BAD_FIELDS)
+def test_extract_non_list_fields_message_is_helpful(client, bad_fields):
+    # Not the opaque "'int' object is not iterable" from list().
+    with pytest.raises(TypeError, match='fields must be a list'):
+        client.extract(TEXT, bad_fields)
+
+
+@responses.activate
+def test_extract_accepts_any_iterable_of_fields(client):
+    # list(fields) already handled tuples; a generator is iterable too and must
+    # not be rejected by the stricter guard.
+    responses.add(responses.POST, BASE + 'extract', json=EXTRACT_RESPONSE, status=200)
+    client.extract(TEXT, (name for name in ['invoice_number', 'total']))
+    assert _last_request_body()['fields'] == ['invoice_number', 'total']

sapling_py-4.2.0/test/test_pii.py

@@ -0,0 +1,66 @@
+import json
+
+import pytest
+import responses
+
+from sapling import SaplingClient
+
+API_KEY = 'a' * 32
+BASE = 'https://api.sapling.ai/api/v1/'
+
+PII_RESPONSE = {
+    'entities': [{
+        'type': 'email', 'text': 'jane@example.com', 'start': 6, 'end': 22,
+        'replacement': '[EMAIL]',
+    }],
+    'flagged': True,
+    'types': ['email'],
+}
+
+
+@pytest.fixture
+def client():
+    return SaplingClient(api_key=API_KEY)
+
+
+def _last_request_body():
+    return json.loads(responses.calls[-1].request.body)
+
+
+@responses.activate
+def test_pii_returns_json_and_sends_key(client):
+    responses.add(responses.POST, BASE + 'pii', json=PII_RESPONSE, status=200)
+    result = client.pii('Email jane@example.com')
+    assert result == PII_RESPONSE
+    body = _last_request_body()
+    assert body == {'key': API_KEY, 'text': 'Email jane@example.com'}
+
+
+@responses.activate
+def test_pii_optional_params_sent_when_provided(client):
+    payload = dict(PII_RESPONSE, redacted_text='Email [EMAIL]')
+    responses.add(responses.POST, BASE + 'pii', json=payload, status=200)
+    result = client.pii('Email jane@example.com', types=('email', 'phone'), redact=True)
+    assert result['redacted_text'] == 'Email [EMAIL]'
+    body = _last_request_body()
+    assert body['types'] == ['email', 'phone']
+    assert body['redact'] is True
+
+
+@responses.activate
+def test_pii_optional_params_omitted_by_default(client):
+    responses.add(responses.POST, BASE + 'pii', json=PII_RESPONSE, status=200)
+    client.pii('some text')
+    body = _last_request_body()
+    assert 'types' not in body
+    assert 'redact' not in body
+
+
+@responses.activate
+@pytest.mark.parametrize('bad_types', ['email', b'email', {'email': True}, 42, True])
+def test_pii_rejects_invalid_types(client, bad_types):
+    # A bare string would be split into characters and a dict reduced to its keys;
+    # non-iterables would raise an opaque TypeError from list().
+    with pytest.raises(TypeError):
+        client.pii('Email jane@example.com', types=bad_types)
+    assert len(responses.calls) == 0

sapling_py-4.2.0/test/test_safety.py

@@ -0,0 +1,30 @@
+import json
+
+import pytest
+import responses
+
+from sapling import SaplingClient
+
+API_KEY = 'a' * 32
+BASE = 'https://api.sapling.ai/api/v1/'
+
+
+@pytest.fixture
+def client():
+    return SaplingClient(api_key=API_KEY)
+
+
+@responses.activate
+def test_safety_threshold_sent_when_provided(client):
+    responses.add(responses.POST, BASE + 'safety', json={'flagged': False}, status=200)
+    client.safety('some text', threshold=0.8)
+    body = json.loads(responses.calls[-1].request.body)
+    assert body == {'key': API_KEY, 'text': 'some text', 'threshold': 0.8}
+
+
+@responses.activate
+def test_safety_threshold_omitted_by_default(client):
+    responses.add(responses.POST, BASE + 'safety', json={'flagged': False}, status=200)
+    client.safety('some text')
+    body = json.loads(responses.calls[-1].request.body)
+    assert 'threshold' not in body

sapling_py-4.2.0/test/test_seo.py

@@ -0,0 +1,116 @@
+import json
+
+import pytest
+import responses
+
+from sapling import SaplingClient, SaplingError
+
+API_KEY = 'a' * 32
+BASE = 'https://api.sapling.ai/api/v1/'
+
+SEO_STATS_RESPONSE = {
+    'stats': {
+        'chars': 372, 'words': 63, 'sentences': 6, 'paragraphs': 3,
+        'reading_time_min': 1, 'flesch_reading_ease': 66.4, 'flesch_kincaid_grade': 7.2,
+    },
+    'keywords': [],
+    'top_terms': [{'term': 'grammar', 'count': 6}, {'term': 'grammar checker', 'count': 5}],
+}
+
+SEO_RESPONSE = dict(
+    SEO_STATS_RESPONSE,
+    keywords=[{'keyword': 'grammar checker', 'count': 5, 'density': 7.94,
+               'in_first_100_words': True}],
+    suggestions={
+        'titles': ['Grammar Checker Guide: What Modern Tools Catch'],
+        'meta_descriptions': ['Learn what a modern grammar checker catches beyond typos.'],
+        'slug': 'grammar-checker-guide',
+        'keywords': ['grammar checker', 'grammar checker for teams'],
+    },
+)
+
+
+@pytest.fixture
+def client():
+    return SaplingClient(api_key=API_KEY)
+
+
+def _last_request_body():
+    return json.loads(responses.calls[-1].request.body)
+
+
+@responses.activate
+def test_seo_returns_json_and_sends_key(client):
+    responses.add(responses.POST, BASE + 'seo', json=SEO_RESPONSE, status=200)
+    result = client.seo('Grammar checkers catch more than typos.')
+    assert result == SEO_RESPONSE
+    body = _last_request_body()
+    assert body == {'key': API_KEY, 'text': 'Grammar checkers catch more than typos.'}
+
+
+@responses.activate
+def test_seo_optional_params_sent_when_provided(client):
+    responses.add(responses.POST, BASE + 'seo', json=SEO_RESPONSE, status=200)
+    result = client.seo('some text', keywords=('grammar checker', 'passive voice'),
+                        suggestions=True, lang='en')
+    assert result['suggestions']['slug'] == 'grammar-checker-guide'
+    body = _last_request_body()
+    assert body == {'key': API_KEY, 'text': 'some text',
+                    'keywords': ['grammar checker', 'passive voice'],
+                    'suggestions': True, 'lang': 'en'}
+
+
+@responses.activate
+def test_seo_suggestions_false_sent(client):
+    responses.add(responses.POST, BASE + 'seo', json=SEO_STATS_RESPONSE, status=200)
+    result = client.seo('some text', suggestions=False)
+    assert result == SEO_STATS_RESPONSE
+    assert 'suggestions' not in result
+    body = _last_request_body()
+    assert body['suggestions'] is False
+    assert 'keywords' not in body
+
+
+@responses.activate
+def test_seo_lang_sent_when_provided(client):
+    # Unsupported readability language: readability fields come back as null.
+    payload = dict(SEO_STATS_RESPONSE, stats=dict(
+        SEO_STATS_RESPONSE['stats'], flesch_reading_ease=None, flesch_kincaid_grade=None))
+    responses.add(responses.POST, BASE + 'seo', json=payload, status=200)
+    result = client.seo('some text', lang='pt-BR')
+    assert result['stats']['flesch_reading_ease'] is None
+    body = _last_request_body()
+    assert body['lang'] == 'pt-BR'
+    assert 'keywords' not in body
+    assert 'suggestions' not in body
+
+
+@responses.activate
+def test_seo_optional_params_omitted_by_default(client):
+    responses.add(responses.POST, BASE + 'seo', json=SEO_STATS_RESPONSE, status=200)
+    client.seo('some text')
+    body = _last_request_body()
+    assert 'keywords' not in body
+    assert 'suggestions' not in body
+    assert 'lang' not in body
+
+
+@responses.activate
+def test_seo_error_raises_saplingerror_with_body(client):
+    responses.add(responses.POST, BASE + 'seo',
+                  json={'msg': 'Unexpected error generating SEO suggestions.'}, status=502)
+    with pytest.raises(SaplingError) as exc_info:
+        client.seo('some text')
+    err = exc_info.value
+    assert err.status_code == 502
+    assert 'Unexpected error generating SEO suggestions.' in str(err)
+
+
+@responses.activate
+@pytest.mark.parametrize('bad_keywords', ['grammar', b'grammar', {'grammar': True}, 42, True])
+def test_seo_rejects_invalid_keywords(client, bad_keywords):
+    # A bare string would be split into characters and a dict reduced to its keys;
+    # non-iterables would raise an opaque TypeError from list().
+    with pytest.raises(TypeError):
+        client.seo('some text', keywords=bad_keywords)
+    assert len(responses.calls) == 0

sapling_py-4.1.0/sapling/version.py

@@ -1 +0,0 @@
-__version__ = '4.1.0'