tldrapi 0.1.0__tar.gz

tldrapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnityCubed / TLDRapi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tldrapi-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: tldrapi
+Version: 0.1.0
+Summary: Official Python SDK for the TLDRapi summarization API. Summarize text at 5 quality tiers with 20+ built-in voice styles.
+Author-email: Ehren Biglari <unitycubedapps@gmail.com>
+License: MIT
+Project-URL: Homepage, https://unitycubed.com/tldrapi
+Project-URL: Documentation, https://unitycubed.com/tldrapi/docs
+Project-URL: Repository, https://github.com/unitycubedapps/tldrapi-python
+Project-URL: Issues, https://github.com/unitycubedapps/tldrapi-python/issues
+Keywords: tldrapi,summarize,summarizer,summary,tldr,abstract,llm,ai,nlp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+Dynamic: license-file
+
+> ### ⚠️ Service notice
+>
+> **The RapidAPI listing that backs this SDK is temporarily unavailable while we work through a launch-day issue. Please check back in a few days.**
+# tldrapi — Python SDK for TLDRapi
+
+Official Python client for [TLDRapi](https://tldrapi.com) — summarize any
+content, in one API call. 5 quality tiers, 20+ built-in voice styles,
+custom voices for paid tiers. Thin (one runtime dep: `httpx`), sync +
+async, typed exceptions per error class.
+
+**TLDRapi is distributed through the RapidAPI marketplace at launch.**
+Subscribe to the TLDRapi listing on RapidAPI, get your `X-RapidAPI-Key`
+from the RapidAPI dashboard, and pass it to the client.
+
+```bash
+pip install tldrapi
+```
+
+## Get your app's RapidAPI key
+
+1. Sign in at [rapidapi.com](https://rapidapi.com)
+2. Subscribe to the [TLDRapi Summarizer](https://rapidapi.com/thunderAPIs256/api/tldrapi-summarizer) listing (start with **BASIC** — free)
+3. Go to **Console** (top nav) → **Applications** → **Add App** (or open an existing one)
+4. In the App → **Authorizations** tab → click the copy icon next to your Authorization Key
+
+That's the app's `X-RapidAPI-Key`. Pass it to the SDK constructor.
+
+*Legacy path (deprecated): upper-right (?) → Legacy Developer Dashboard → Add New App → Authorization tab. The new Console path above is simpler.*
+
+The Authorization Key field is the same value in both places — RapidAPI just labels it differently depending on which interface you use:
+
+**New Console:**
+
+![RapidAPI Console — Authorization Method labeled "RAPIDAPI"](https://raw.githubusercontent.com/unitycubed/tldrapi-docs/main/img/rapidapi-key-label-console.png)
+
+**Legacy Developer Dashboard:**
+
+![RapidAPI Legacy Developer Dashboard — Authorization Method labeled "API key"](https://raw.githubusercontent.com/unitycubed/tldrapi-docs/main/img/rapidapi-key-label-legacy.png)
+
+
+
+## Quick start
+
+```python
+from tldrapi import TLDRapi
+
+client = TLDRapi(rapidapi_key="YOUR_RAPIDAPI_KEY")
+result = client.summarize("Long text here...", tier="standard")
+print(result.summary)
+print(f"Credits remaining: {result.credits.get('remaining')}")
+```
+
+## Async
+
+```python
+import asyncio
+from tldrapi import AsyncTLDRapi
+
+async def main():
+    async with AsyncTLDRapi(rapidapi_key="YOUR_RAPIDAPI_KEY") as client:
+        r = await client.summarize("Long text here...", tier="deep")
+        print(r.summary)
+
+asyncio.run(main())
+```
+
+## Quality tiers
+
+Pass `tier="quick" | "standard" | "deep" | "premium" | "ultra"` per
+call. Higher tier → higher quality, more credits, larger allowed input.
+
+| Tier      | Credits/call | Max input tokens | Best for                          |
+|-----------|-------------:|-----------------:|-----------------------------------|
+| quick     |            1 |            4,000 | Short texts, previews             |
+| standard  |            5 |           16,000 | Default                           |
+| deep      |           30 |           32,000 | Longer content, deeper reasoning  |
+| premium   |          110 |           64,000 | Substantial documents             |
+| ultra     |          400 |          100,000 | Long-form / research-grade        |
+
+Live rates: `client.rates()`.
+
+## Session pinning
+
+If you're processing a batch and want the same underlying model for
+every call, pass `session_id` from the previous result:
+
+```python
+r1 = client.summarize("Doc 1")
+r2 = client.summarize("Doc 2", session_id=r1.session_id)
+r3 = client.summarize("Doc 3", session_id=r1.session_id)
+```
+
+## Error handling
+
+All SDK exceptions inherit from `TLDRapiError`. Catch specifically:
+
+```python
+from tldrapi import (
+    TLDRapi,
+    InsufficientCreditsError,
+    RateLimitError,
+    LanguageNotSupportedError,
+    QualitySelectionRequiresPaidPlanError,
+    ServerError,
+    TimeoutError,
+)
+
+client = TLDRapi(rapidapi_key="YOUR_RAPIDAPI_KEY")
+
+try:
+    r = client.summarize(user_text, tier="deep")
+except InsufficientCreditsError as e:
+    top_up_url = e.response_body.get("options", {}).get("top_up", {}).get("url")
+    # …present top-up flow to your user…
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    # …retry once the plan window resets…
+except LanguageNotSupportedError as e:
+    lang = e.response_body.get("detected_language_name")
+    # …English-only at launch; cross-lingual is a Month 2-3 feature…
+except QualitySelectionRequiresPaidPlanError:
+    # Free plan can't select tiers; retry without tier=
+    r = client.summarize(user_text)
+except TimeoutError:
+    # Long inputs on deep+ can legitimately need >60s. Retry with a bigger timeout.
+    r = client.summarize(user_text, tier="deep", timeout=120)
+```
+
+Every error carries `.status_code`, `.request_id` (X-Request-ID from
+the response — attach when reporting issues), and `.response_body`
+(the full parsed JSON error body).
+
+## Configuration
+
+```python
+client = TLDRapi(
+    rapidapi_key="YOUR_RAPIDAPI_KEY",
+    rapidapi_host="tldrapi-summarizer.p.rapidapi.com",   # override to point at a staging listing
+    base_url=None,                           # default = https://{rapidapi_host}
+    timeout=60.0,                            # default 60s per request
+    retries=3,                               # 5xx + network retries, exponential backoff
+)
+```
+
+## Retries
+
+The client automatically retries **5xx** responses and transient
+network failures with exponential backoff + jitter (default 3
+attempts).
+
+**Not retried**:
+- **4xx responses** — permanent failures; retrying an
+  `insufficient_credits` would waste more of the same failing call.
+- **429 rate-limit** — honor the server's `Retry-After` header. The
+  SDK exposes it on `RateLimitError.retry_after_seconds`.
+
+## Usage & rates
+
+```python
+u = client.usage()           # this month's calls, credits charged/remaining
+r = client.rates()           # current credits/call per tier
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest -q                    # 20 tests, all HTTP mocked via respx
+```
+
+## License
+
+Released under the MIT License — see [LICENSE](LICENSE).
+
+Copyright (c) 2026 Ehren Biglari / Unity Cubed.

tldrapi-0.1.0/README.md

@@ -0,0 +1,175 @@
+> ### ⚠️ Service notice
+>
+> **The RapidAPI listing that backs this SDK is temporarily unavailable while we work through a launch-day issue. Please check back in a few days.**
+# tldrapi — Python SDK for TLDRapi
+
+Official Python client for [TLDRapi](https://tldrapi.com) — summarize any
+content, in one API call. 5 quality tiers, 20+ built-in voice styles,
+custom voices for paid tiers. Thin (one runtime dep: `httpx`), sync +
+async, typed exceptions per error class.
+
+**TLDRapi is distributed through the RapidAPI marketplace at launch.**
+Subscribe to the TLDRapi listing on RapidAPI, get your `X-RapidAPI-Key`
+from the RapidAPI dashboard, and pass it to the client.
+
+```bash
+pip install tldrapi
+```
+
+## Get your app's RapidAPI key
+
+1. Sign in at [rapidapi.com](https://rapidapi.com)
+2. Subscribe to the [TLDRapi Summarizer](https://rapidapi.com/thunderAPIs256/api/tldrapi-summarizer) listing (start with **BASIC** — free)
+3. Go to **Console** (top nav) → **Applications** → **Add App** (or open an existing one)
+4. In the App → **Authorizations** tab → click the copy icon next to your Authorization Key
+
+That's the app's `X-RapidAPI-Key`. Pass it to the SDK constructor.
+
+*Legacy path (deprecated): upper-right (?) → Legacy Developer Dashboard → Add New App → Authorization tab. The new Console path above is simpler.*
+
+The Authorization Key field is the same value in both places — RapidAPI just labels it differently depending on which interface you use:
+
+**New Console:**
+
+![RapidAPI Console — Authorization Method labeled "RAPIDAPI"](https://raw.githubusercontent.com/unitycubed/tldrapi-docs/main/img/rapidapi-key-label-console.png)
+
+**Legacy Developer Dashboard:**
+
+![RapidAPI Legacy Developer Dashboard — Authorization Method labeled "API key"](https://raw.githubusercontent.com/unitycubed/tldrapi-docs/main/img/rapidapi-key-label-legacy.png)
+
+
+
+## Quick start
+
+```python
+from tldrapi import TLDRapi
+
+client = TLDRapi(rapidapi_key="YOUR_RAPIDAPI_KEY")
+result = client.summarize("Long text here...", tier="standard")
+print(result.summary)
+print(f"Credits remaining: {result.credits.get('remaining')}")
+```
+
+## Async
+
+```python
+import asyncio
+from tldrapi import AsyncTLDRapi
+
+async def main():
+    async with AsyncTLDRapi(rapidapi_key="YOUR_RAPIDAPI_KEY") as client:
+        r = await client.summarize("Long text here...", tier="deep")
+        print(r.summary)
+
+asyncio.run(main())
+```
+
+## Quality tiers
+
+Pass `tier="quick" | "standard" | "deep" | "premium" | "ultra"` per
+call. Higher tier → higher quality, more credits, larger allowed input.
+
+| Tier      | Credits/call | Max input tokens | Best for                          |
+|-----------|-------------:|-----------------:|-----------------------------------|
+| quick     |            1 |            4,000 | Short texts, previews             |
+| standard  |            5 |           16,000 | Default                           |
+| deep      |           30 |           32,000 | Longer content, deeper reasoning  |
+| premium   |          110 |           64,000 | Substantial documents             |
+| ultra     |          400 |          100,000 | Long-form / research-grade        |
+
+Live rates: `client.rates()`.
+
+## Session pinning
+
+If you're processing a batch and want the same underlying model for
+every call, pass `session_id` from the previous result:
+
+```python
+r1 = client.summarize("Doc 1")
+r2 = client.summarize("Doc 2", session_id=r1.session_id)
+r3 = client.summarize("Doc 3", session_id=r1.session_id)
+```
+
+## Error handling
+
+All SDK exceptions inherit from `TLDRapiError`. Catch specifically:
+
+```python
+from tldrapi import (
+    TLDRapi,
+    InsufficientCreditsError,
+    RateLimitError,
+    LanguageNotSupportedError,
+    QualitySelectionRequiresPaidPlanError,
+    ServerError,
+    TimeoutError,
+)
+
+client = TLDRapi(rapidapi_key="YOUR_RAPIDAPI_KEY")
+
+try:
+    r = client.summarize(user_text, tier="deep")
+except InsufficientCreditsError as e:
+    top_up_url = e.response_body.get("options", {}).get("top_up", {}).get("url")
+    # …present top-up flow to your user…
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    # …retry once the plan window resets…
+except LanguageNotSupportedError as e:
+    lang = e.response_body.get("detected_language_name")
+    # …English-only at launch; cross-lingual is a Month 2-3 feature…
+except QualitySelectionRequiresPaidPlanError:
+    # Free plan can't select tiers; retry without tier=
+    r = client.summarize(user_text)
+except TimeoutError:
+    # Long inputs on deep+ can legitimately need >60s. Retry with a bigger timeout.
+    r = client.summarize(user_text, tier="deep", timeout=120)
+```
+
+Every error carries `.status_code`, `.request_id` (X-Request-ID from
+the response — attach when reporting issues), and `.response_body`
+(the full parsed JSON error body).
+
+## Configuration
+
+```python
+client = TLDRapi(
+    rapidapi_key="YOUR_RAPIDAPI_KEY",
+    rapidapi_host="tldrapi-summarizer.p.rapidapi.com",   # override to point at a staging listing
+    base_url=None,                           # default = https://{rapidapi_host}
+    timeout=60.0,                            # default 60s per request
+    retries=3,                               # 5xx + network retries, exponential backoff
+)
+```
+
+## Retries
+
+The client automatically retries **5xx** responses and transient
+network failures with exponential backoff + jitter (default 3
+attempts).
+
+**Not retried**:
+- **4xx responses** — permanent failures; retrying an
+  `insufficient_credits` would waste more of the same failing call.
+- **429 rate-limit** — honor the server's `Retry-After` header. The
+  SDK exposes it on `RateLimitError.retry_after_seconds`.
+
+## Usage & rates
+
+```python
+u = client.usage()           # this month's calls, credits charged/remaining
+r = client.rates()           # current credits/call per tier
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest -q                    # 20 tests, all HTTP mocked via respx
+```
+
+## License
+
+Released under the MIT License — see [LICENSE](LICENSE).
+
+Copyright (c) 2026 Ehren Biglari / Unity Cubed.

tldrapi-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tldrapi"
+version = "0.1.0"
+description = "Official Python SDK for the TLDRapi summarization API. Summarize text at 5 quality tiers with 20+ built-in voice styles."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Ehren Biglari", email = "unitycubedapps@gmail.com" }]
+keywords = ["tldrapi", "summarize", "summarizer", "summary", "tldr", "abstract", "llm", "ai", "nlp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Linguistic",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+]
+
+[project.urls]
+Homepage = "https://unitycubed.com/tldrapi"
+Documentation = "https://unitycubed.com/tldrapi/docs"
+Repository = "https://github.com/unitycubedapps/tldrapi-python"
+Issues = "https://github.com/unitycubedapps/tldrapi-python/issues"
+
+[tool.setuptools.packages.find]
+include = ["tldrapi*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

tldrapi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+