adola 0.1.0__tar.gz

adola-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Adola
+
+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.
+

adola-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: adola
+Version: 0.1.0
+Summary: Python SDK for the Adola compression API
+Author: Adola
+License: MIT
+Project-URL: Homepage, https://adola.app
+Project-URL: Documentation, https://adola.app/docs
+Project-URL: Repository, https://github.com/JBunga/adola-python
+Keywords: adola,compression,tokens,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Dynamic: license-file
+
+# adola
+
+Python SDK for the Adola compression API.
+
+```bash
+pip install adola
+```
+
+```python
+from adola import Adola
+
+client = Adola(api_key="adola_...")
+result = client.compress(
+    input="Adola compresses long prompts before they reach your model.",
+    query="What does Adola do?",
+    compression={"target_ratio": 0.4},
+)
+
+print(result["output"])
+print(result["receipt"]["tokens_saved"])
+```
+
+The client defaults to `https://api.adola.app`. Set `ADOLA_API_KEY` for auth and `ADOLA_BASE_URL` for local testing.
+
+The package contains only the SDK client and does not include the Adola application codebase.

adola-0.1.0/README.md

@@ -0,0 +1,25 @@
+# adola
+
+Python SDK for the Adola compression API.
+
+```bash
+pip install adola
+```
+
+```python
+from adola import Adola
+
+client = Adola(api_key="adola_...")
+result = client.compress(
+    input="Adola compresses long prompts before they reach your model.",
+    query="What does Adola do?",
+    compression={"target_ratio": 0.4},
+)
+
+print(result["output"])
+print(result["receipt"]["tokens_saved"])
+```
+
+The client defaults to `https://api.adola.app`. Set `ADOLA_API_KEY` for auth and `ADOLA_BASE_URL` for local testing.
+
+The package contains only the SDK client and does not include the Adola application codebase.

adola-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adola"
+version = "0.1.0"
+description = "Python SDK for the Adola compression API"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27.0"
+]
+license = { text = "MIT" }
+authors = [
+  { name = "Adola" }
+]
+keywords = ["adola", "compression", "tokens", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed"
+]
+
+[project.urls]
+Homepage = "https://adola.app"
+Documentation = "https://adola.app/docs"
+Repository = "https://github.com/JBunga/adola-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+adola = ["py.typed"]

adola-0.1.0/setup.cfg

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

adola-0.1.0/src/adola/__init__.py

@@ -0,0 +1,5 @@
+from adola._client import Adola, AsyncAdola
+from adola._errors import AdolaAPIError
+
+__all__ = ["Adola", "AdolaAPIError", "AsyncAdola"]
+

adola-0.1.0/src/adola/_client.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from typing import Any
+
+import httpx
+
+from adola._errors import AdolaAPIError
+from adola.types import (
+    CompressRequest,
+    CompressResponse,
+    CompressionOptions,
+    Model,
+    ProtectedOptions,
+    Span,
+)
+
+DEFAULT_BASE_URL = "https://api.adola.app"
+USER_AGENT = "adola-python/0.1.0"
+
+
+class Adola:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("ADOLA_API_KEY")
+        if not self.api_key:
+            raise ValueError("api_key or ADOLA_API_KEY is required")
+        self.base_url = _normalize_base_url(base_url or os.getenv("ADOLA_BASE_URL") or DEFAULT_BASE_URL)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "Adola":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def models(self) -> list[Model]:
+        return self._request("GET", "/v1/models")
+
+    def compress(
+        self,
+        input: str | None = None,
+        *,
+        query: str | None = None,
+        spans: Sequence[Span] | None = None,
+        model: str = "rose-1",
+        compression: CompressionOptions | None = None,
+        protected: ProtectedOptions | None = None,
+        include_spans: bool = True,
+    ) -> CompressResponse:
+        payload = _compress_payload(
+            input=input,
+            query=query,
+            spans=spans,
+            model=model,
+            compression=compression,
+            protected=protected,
+            include_spans=include_spans,
+        )
+        return self._request("POST", "/v1/compress", json=payload)
+
+    def batch_compress(self, requests: Sequence[CompressRequest]) -> list[CompressResponse]:
+        if not requests:
+            raise ValueError("requests must not be empty")
+        return self._request("POST", "/v1/batch/compress", json={"requests": list(requests)})
+
+    def _request(self, method: str, path: str, *, json: Any | None = None) -> Any:
+        try:
+            response = self._client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=_headers(self.api_key),
+                json=json,
+            )
+        except httpx.RequestError as exc:
+            raise AdolaAPIError(f"Request failed: {exc}") from exc
+        return _decode_response(response)
+
+
+class AsyncAdola:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("ADOLA_API_KEY")
+        if not self.api_key:
+            raise ValueError("api_key or ADOLA_API_KEY is required")
+        self.base_url = _normalize_base_url(base_url or os.getenv("ADOLA_BASE_URL") or DEFAULT_BASE_URL)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def __aenter__(self) -> "AsyncAdola":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def models(self) -> list[Model]:
+        return await self._request("GET", "/v1/models")
+
+    async def compress(
+        self,
+        input: str | None = None,
+        *,
+        query: str | None = None,
+        spans: Sequence[Span] | None = None,
+        model: str = "rose-1",
+        compression: CompressionOptions | None = None,
+        protected: ProtectedOptions | None = None,
+        include_spans: bool = True,
+    ) -> CompressResponse:
+        payload = _compress_payload(
+            input=input,
+            query=query,
+            spans=spans,
+            model=model,
+            compression=compression,
+            protected=protected,
+            include_spans=include_spans,
+        )
+        return await self._request("POST", "/v1/compress", json=payload)
+
+    async def batch_compress(self, requests: Sequence[CompressRequest]) -> list[CompressResponse]:
+        if not requests:
+            raise ValueError("requests must not be empty")
+        return await self._request("POST", "/v1/batch/compress", json={"requests": list(requests)})
+
+    async def _request(self, method: str, path: str, *, json: Any | None = None) -> Any:
+        try:
+            response = await self._client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=_headers(self.api_key),
+                json=json,
+            )
+        except httpx.RequestError as exc:
+            raise AdolaAPIError(f"Request failed: {exc}") from exc
+        return _decode_response(response)
+
+
+def _compress_payload(
+    *,
+    input: str | None,
+    query: str | None,
+    spans: Sequence[Span] | None,
+    model: str,
+    compression: CompressionOptions | None,
+    protected: ProtectedOptions | None,
+    include_spans: bool,
+) -> CompressRequest:
+    if not input and not spans:
+        raise ValueError("input or spans is required")
+    payload: CompressRequest = {
+        "model": model,  # type: ignore[typeddict-item]
+        "include_spans": include_spans,
+    }
+    if input is not None:
+        payload["input"] = input
+    if query is not None:
+        payload["query"] = query
+    if spans is not None:
+        payload["spans"] = list(spans)
+    if compression is not None:
+        payload["compression"] = compression
+    if protected is not None:
+        payload["protected"] = protected
+    return payload
+
+
+def _decode_response(response: httpx.Response) -> Any:
+    if response.is_success:
+        return response.json()
+    message = _error_message(response)
+    raise AdolaAPIError(
+        message,
+        status_code=response.status_code,
+        request_id=response.headers.get("x-request-id"),
+        response=response,
+    )
+
+
+def _error_message(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text or response.reason_phrase
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(detail, str):
+        return detail
+    if isinstance(detail, list):
+        messages = [
+            item.get("msg")
+            for item in detail
+            if isinstance(item, dict) and isinstance(item.get("msg"), str)
+        ]
+        if messages:
+            return "; ".join(messages)
+    return response.reason_phrase
+
+
+def _headers(api_key: str) -> dict[str, str]:
+    return {
+        "Accept": "application/json",
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+

adola-0.1.0/src/adola/_errors.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AdolaAPIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        response: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.response = response
+

adola-0.1.0/src/adola/py.typed

@@ -0,0 +1 @@
+

adola-0.1.0/src/adola/types.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+
+class CompressionOptions(TypedDict, total=False):
+    target_ratio: float
+    max_output_tokens: int | None
+    keep: int | None
+    preserve_order: bool
+
+
+class ProtectedOptions(TypedDict, total=False):
+    xml_tags: list[str]
+    patterns: list[str]
+
+
+class Span(TypedDict, total=False):
+    id: str
+    text: str
+    protected: bool
+    metadata: dict[str, str]
+
+
+class CompressRequest(TypedDict, total=False):
+    model: Literal["rose-1"]
+    query: str | None
+    input: str | None
+    spans: list[Span] | None
+    compression: CompressionOptions
+    protected: ProtectedOptions
+    include_spans: bool
+
+
+class Risk(TypedDict):
+    level: str
+    flags: list[str]
+
+
+class Receipt(TypedDict):
+    original_tokens: int
+    output_tokens: int
+    tokens_saved: int
+    compression_ratio: float
+    selected_count: int
+    total_spans: int
+    protected_tokens: int
+    latency_ms: float
+    risk: Risk
+
+
+class SelectedSpan(TypedDict):
+    id: str
+    index: int
+    text: str
+    tokens: int
+    protected: bool
+
+
+class CompressResponse(TypedDict):
+    model: Literal["rose-1"]
+    output: str
+    receipt: Receipt
+    selected_spans: list[SelectedSpan]
+
+
+class Model(TypedDict):
+    id: Literal["rose-1"]
+    name: str
+    mode: Literal["context-compression"]
+    target: Literal["production-llm-systems"]
+
+
+class BatchCompressRequest(TypedDict):
+    requests: list[CompressRequest]

adola-0.1.0/src/adola.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: adola
+Version: 0.1.0
+Summary: Python SDK for the Adola compression API
+Author: Adola
+License: MIT
+Project-URL: Homepage, https://adola.app
+Project-URL: Documentation, https://adola.app/docs
+Project-URL: Repository, https://github.com/JBunga/adola-python
+Keywords: adola,compression,tokens,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Dynamic: license-file
+
+# adola
+
+Python SDK for the Adola compression API.
+
+```bash
+pip install adola
+```
+
+```python
+from adola import Adola
+
+client = Adola(api_key="adola_...")
+result = client.compress(
+    input="Adola compresses long prompts before they reach your model.",
+    query="What does Adola do?",
+    compression={"target_ratio": 0.4},
+)
+
+print(result["output"])
+print(result["receipt"]["tokens_saved"])
+```
+
+The client defaults to `https://api.adola.app`. Set `ADOLA_API_KEY` for auth and `ADOLA_BASE_URL` for local testing.
+
+The package contains only the SDK client and does not include the Adola application codebase.

adola-0.1.0/src/adola.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/adola/__init__.py
+src/adola/_client.py
+src/adola/_errors.py
+src/adola/py.typed
+src/adola/types.py
+src/adola.egg-info/PKG-INFO
+src/adola.egg-info/SOURCES.txt
+src/adola.egg-info/dependency_links.txt
+src/adola.egg-info/requires.txt
+src/adola.egg-info/top_level.txt
+tests/test_client.py

adola-0.1.0/src/adola.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

adola-0.1.0/src/adola.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27.0

adola-0.1.0/src/adola.egg-info/top_level.txt

@@ -0,0 +1 @@
+adola

adola-0.1.0/tests/test_client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+
+from adola import Adola, AdolaAPIError, AsyncAdola
+
+FIXTURES = Path(__file__).resolve().parents[2] / "fixtures"
+
+
+def load_fixture(name: str) -> object:
+    return json.loads((FIXTURES / name).read_text())
+
+
+def test_models_sends_auth_and_parses_response() -> None:
+    calls: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return httpx.Response(200, json=load_fixture("models-response.json"))
+
+    client = Adola(
+        api_key="test-key",
+        base_url="https://unit.test/",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    models = client.models()
+
+    assert models[0]["id"] == "rose-1"
+    assert calls[0].url == "https://unit.test/v1/models"
+    assert calls[0].headers["authorization"] == "Bearer test-key"
+    assert calls[0].headers["user-agent"] == "adola-python/0.1.0"
+
+
+def test_compress_sends_schema_payload() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["payload"] = json.loads(request.content)
+        return httpx.Response(200, json=load_fixture("compress-response.json"))
+
+    client = Adola(
+        api_key="test-key",
+        base_url="https://unit.test",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    response = client.compress(
+        input="source text",
+        query="needle",
+        compression={"target_ratio": 0.5, "preserve_order": False},
+        protected={"xml_tags": ["safe"], "patterns": ["SECRET"]},
+        include_spans=False,
+    )
+
+    assert response["receipt"]["tokens_saved"] == 6
+    assert seen["payload"] == {
+        "model": "rose-1",
+        "input": "source text",
+        "query": "needle",
+        "compression": {"target_ratio": 0.5, "preserve_order": False},
+        "protected": {"xml_tags": ["safe"], "patterns": ["SECRET"]},
+        "include_spans": False,
+    }
+
+
+def test_compress_accepts_spans_without_input() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert json.loads(request.content)["spans"] == [{"id": "a", "text": "span text"}]
+        return httpx.Response(200, json=load_fixture("compress-response.json"))
+
+    client = Adola(
+        api_key="test-key",
+        base_url="https://unit.test",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    assert client.compress(spans=[{"id": "a", "text": "span text"}])["model"] == "rose-1"
+
+
+def test_compress_requires_input_or_spans() -> None:
+    client = Adola(
+        api_key="test-key",
+        http_client=httpx.Client(transport=httpx.MockTransport(lambda _: httpx.Response(500))),
+    )
+
+    with pytest.raises(ValueError, match="input or spans"):
+        client.compress()
+
+
+def test_batch_compress_posts_requests_array() -> None:
+    request_fixture = load_fixture("compress-request.json")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert json.loads(request.content) == {"requests": [request_fixture]}
+        return httpx.Response(200, json=[load_fixture("compress-response.json")])
+
+    client = Adola(
+        api_key="test-key",
+        base_url="https://unit.test",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    response = client.batch_compress([request_fixture])  # type: ignore[list-item]
+
+    assert response[0]["output"].startswith("Adola removes")
+
+
+def test_api_error_includes_status_and_request_id() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            422,
+            headers={"x-request-id": "req_123"},
+            json={"detail": [{"msg": "input or spans is required"}]},
+        )
+
+    client = Adola(
+        api_key="test-key",
+        base_url="https://unit.test",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    with pytest.raises(AdolaAPIError) as exc_info:
+        client.models()
+
+    assert exc_info.value.status_code == 422
+    assert exc_info.value.request_id == "req_123"
+    assert str(exc_info.value) == "input or spans is required"
+
+
+def test_request_error_is_wrapped() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("no route")
+
+    client = Adola(
+        api_key="test-key",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    with pytest.raises(AdolaAPIError, match="Request failed"):
+        client.models()
+
+
+def test_env_base_url_and_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ADOLA_API_KEY", "env-key")
+    monkeypatch.setenv("ADOLA_BASE_URL", "https://env.test/")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url == "https://env.test/v1/models"
+        assert request.headers["authorization"] == "Bearer env-key"
+        return httpx.Response(200, json=load_fixture("models-response.json"))
+
+    client = Adola(http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+    assert client.models()[0]["name"] == "Rose 1"
+
+
+def test_async_client() -> None:
+    async def run() -> None:
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.headers["authorization"] == "Bearer async-key"
+            return httpx.Response(200, json=load_fixture("compress-response.json"))
+
+        async with AsyncAdola(
+            api_key="async-key",
+            base_url="https://unit.test",
+            http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+        ) as client:
+            response = await client.compress(input="source")
+
+        assert response["receipt"]["tokens_saved"] == 6
+
+    asyncio.run(run())
+
+
+@pytest.mark.skipif(not os.getenv("ADOLA_API_KEY"), reason="ADOLA_API_KEY is required")
+def test_live_models_and_compress() -> None:
+    with Adola() as client:
+        assert client.models()[0]["id"] == "rose-1"
+        response = client.compress(
+            input="Adola trims prompt context before the request reaches a model.",
+            query="What does Adola trim?",
+            compression={"target_ratio": 0.5},
+        )
+    assert response["receipt"]["tokens_saved"] >= 0
+