promtexpress 0.1.0__tar.gz

promtexpress-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: promtexpress
+Version: 0.1.0
+Summary: Official Python client for the PromtExpress API
+Author: Webitro
+License-Expression: MIT
+Project-URL: Homepage, https://promtexpress.com
+Project-URL: Source, https://github.com/WebitroHQ/promtexpress-oss
+Project-URL: Issues, https://github.com/WebitroHQ/promtexpress-oss/issues
+Keywords: promtexpress,prompt,prompt-engineering,llm,ai,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# promtexpress
+
+Official Python client for the [PromtExpress](https://promtexpress.com) API. Standard library only, Python 3.9+.
+
+```bash
+pip install promtexpress
+```
+
+## Usage
+
+```python
+from promtexpress import PromtExpress
+
+client = PromtExpress()  # reads PROMTEXPRESS_API_KEY
+
+result = client.generate(
+    "product launch email for a note-taking app, friendly tone",
+    "text",  # text | code | image | video | audio | music
+)
+print(result["output"])
+print(result["creditsRemaining"], "credits left")
+```
+
+### Clarifying questions and iteration
+
+```python
+if result.get("chipQuestions"):
+    better = client.generate(
+        "product launch email for a note-taking app",
+        "text",
+        answers=[{"question": result["chipQuestions"][0]["label"], "answer": "developers"}],
+    )
+
+refined = client.generate(
+    "product launch email for a note-taking app",
+    "text",
+    iteration={"ofPromptId": result["promptId"], "feedback": "shorter, mention the free tier"},
+)
+```
+
+### Templates and history
+
+```python
+templates = client.list_templates(modality="image")
+
+page = client.list_history(page=0, limit=50)
+
+for entry in client.iter_history(modality="video"):
+    print(entry["date"], entry["title"])
+```
+
+## Errors
+
+All errors inherit from `PromtExpressError`: `InvalidRequestError` (400), `AuthenticationError` (401), `InsufficientCreditsError` (402, with `remaining` and `required`), `RateLimitError` (429, with `retry_after`), `ServerError` (5xx) and `APIConnectionError` (network or timeout).
+
+Time-based rate limits are retried automatically (`max_retries`, default 2).
+
+## License
+
+MIT

promtexpress-0.1.0/README.md

@@ -0,0 +1,60 @@
+# promtexpress
+
+Official Python client for the [PromtExpress](https://promtexpress.com) API. Standard library only, Python 3.9+.
+
+```bash
+pip install promtexpress
+```
+
+## Usage
+
+```python
+from promtexpress import PromtExpress
+
+client = PromtExpress()  # reads PROMTEXPRESS_API_KEY
+
+result = client.generate(
+    "product launch email for a note-taking app, friendly tone",
+    "text",  # text | code | image | video | audio | music
+)
+print(result["output"])
+print(result["creditsRemaining"], "credits left")
+```
+
+### Clarifying questions and iteration
+
+```python
+if result.get("chipQuestions"):
+    better = client.generate(
+        "product launch email for a note-taking app",
+        "text",
+        answers=[{"question": result["chipQuestions"][0]["label"], "answer": "developers"}],
+    )
+
+refined = client.generate(
+    "product launch email for a note-taking app",
+    "text",
+    iteration={"ofPromptId": result["promptId"], "feedback": "shorter, mention the free tier"},
+)
+```
+
+### Templates and history
+
+```python
+templates = client.list_templates(modality="image")
+
+page = client.list_history(page=0, limit=50)
+
+for entry in client.iter_history(modality="video"):
+    print(entry["date"], entry["title"])
+```
+
+## Errors
+
+All errors inherit from `PromtExpressError`: `InvalidRequestError` (400), `AuthenticationError` (401), `InsufficientCreditsError` (402, with `remaining` and `required`), `RateLimitError` (429, with `retry_after`), `ServerError` (5xx) and `APIConnectionError` (network or timeout).
+
+Time-based rate limits are retried automatically (`max_retries`, default 2).
+
+## License
+
+MIT

promtexpress-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "promtexpress"
+version = "0.1.0"
+description = "Official Python client for the PromtExpress API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Webitro" }]
+keywords = ["promtexpress", "prompt", "prompt-engineering", "llm", "ai", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://promtexpress.com"
+Source = "https://github.com/WebitroHQ/promtexpress-oss"
+Issues = "https://github.com/WebitroHQ/promtexpress-oss/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+promtexpress = ["py.typed"]

promtexpress-0.1.0/setup.cfg

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

promtexpress-0.1.0/src/promtexpress/__init__.py

@@ -0,0 +1,29 @@
+"""Official Python client for the PromtExpress API."""
+
+from ._client import DEFAULT_BASE_URL, MODALITIES, PromtExpress
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    PromtExpressError,
+    RateLimitError,
+    ServerError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "MODALITIES",
+    "PromtExpress",
+    "PromtExpressError",
+    "APIError",
+    "APIConnectionError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "ServerError",
+]

promtexpress-0.1.0/src/promtexpress/_client.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import os
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence
+
+from ._errors import APIConnectionError, PromtExpressError, RateLimitError, error_from_response
+from ._types import Answer, GenerateResult, HistoryPage, HistoryRow, Iteration, Template
+
+DEFAULT_BASE_URL = "https://promtexpress.com/api/v1"
+MODALITIES = ("text", "code", "image", "video", "audio", "music")
+
+_USER_AGENT = "promtexpress-python/0.1.0"
+
+
+class PromtExpress:
+    """Client for the PromtExpress API.
+
+    >>> client = PromtExpress()  # reads PROMTEXPRESS_API_KEY
+    >>> result = client.generate("launch email for my CRM", "text")
+    >>> print(result["output"])
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+    ) -> None:
+        api_key = api_key or os.environ.get("PROMTEXPRESS_API_KEY")
+        if not api_key:
+            raise PromtExpressError(
+                "Missing API key: pass api_key or set PROMTEXPRESS_API_KEY. "
+                "Keys are created in the PromtExpress dashboard under API Keys."
+            )
+        self.base_url = (base_url or os.environ.get("PROMTEXPRESS_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    def generate(
+        self,
+        intent: str,
+        modality: str,
+        *,
+        target_engine_id: Optional[str] = None,
+        answers: Optional[Sequence[Answer]] = None,
+        iteration: Optional[Iteration] = None,
+    ) -> GenerateResult:
+        """Compile a plain-language intent into a production-ready prompt. Consumes credits."""
+        if not isinstance(intent, str) or not 3 <= len(intent) <= 4000:
+            raise PromtExpressError("intent must be a string of 3 to 4000 characters")
+        if modality not in MODALITIES:
+            raise PromtExpressError(f"modality must be one of: {', '.join(MODALITIES)}")
+        if answers is not None and len(answers) > 10:
+            raise PromtExpressError("answers accepts at most 10 items")
+
+        body: Dict[str, Any] = {"intent": intent, "modality": modality}
+        if target_engine_id is not None:
+            body["targetEngineId"] = target_engine_id
+        if answers:
+            body["answers"] = list(answers)
+        if iteration:
+            body["iteration"] = dict(iteration)
+        return self._request("POST", "/generate", body=body)
+
+    def list_templates(self, modality: Optional[str] = None) -> List[Template]:
+        """List published prompt templates."""
+        return self._request("GET", "/templates", query={"modality": modality})["templates"]
+
+    def list_history(self, *, page: int = 0, limit: int = 20, modality: Optional[str] = None) -> HistoryPage:
+        """Fetch one page of your generation history, newest first."""
+        return self._request("GET", "/history", query={"page": page, "limit": limit, "modality": modality})
+
+    def iter_history(self, *, limit: int = 100, modality: Optional[str] = None) -> Iterator[HistoryRow]:
+        """Walk your whole generation history, requesting pages as needed."""
+        page = 0
+        while True:
+            result = self.list_history(page=page, limit=limit, modality=modality)
+            yield from result["rows"]
+            if not result["rows"] or (page + 1) * result["pageSize"] >= result["total"]:
+                return
+            page += 1
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        url = self.base_url + path
+        params = {key: value for key, value in (query or {}).items() if value is not None}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                    return _parse(response.read())
+            except urllib.error.HTTPError as exc:
+                error = error_from_response(exc.code, _parse(exc.read()), exc.headers)
+                # The API rejects rate-limited calls before charging credits, so retrying is safe even for generate.
+                if isinstance(error, RateLimitError) and error.retry_after is not None and attempt < self._max_retries:
+                    attempt += 1
+                    time.sleep(error.retry_after)
+                    continue
+                raise error from None
+            except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError) as exc:
+                reason = getattr(exc, "reason", exc)
+                raise APIConnectionError(f"Could not reach {self.base_url}: {reason}") from exc
+
+
+def _parse(raw: bytes) -> Any:
+    if not raw:
+        return None
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text

promtexpress-0.1.0/src/promtexpress/_errors.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class PromtExpressError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class APIError(PromtExpressError):
+    """The API responded with a non-2xx status."""
+
+    def __init__(self, status: int, message: str, body: Any) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+class InvalidRequestError(APIError):
+    """400: the request body failed server-side validation."""
+
+
+class AuthenticationError(APIError):
+    """401: the API key is missing, invalid, expired or revoked."""
+
+
+class InsufficientCreditsError(APIError):
+    """402: not enough credits left for this generation."""
+
+    def __init__(self, status: int, message: str, body: Any) -> None:
+        super().__init__(status, message, body)
+        self.remaining = _number_field(body, "remaining")
+        self.required = _number_field(body, "required")
+
+
+class RateLimitError(APIError):
+    """429: rate limited, or the iteration limit for a prompt was reached."""
+
+    def __init__(self, status: int, message: str, body: Any, retry_after: Optional[float]) -> None:
+        super().__init__(status, message, body)
+        #: Seconds to wait before retrying; None when the limit is not time-based.
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    """5xx: the generation pipeline or an upstream engine failed."""
+
+
+class APIConnectionError(PromtExpressError):
+    """The request never got a response: network failure or timeout."""
+
+
+def error_from_response(status: int, body: Any, headers: Mapping[str, str]) -> APIError:
+    message = _describe(status, body)
+    if status == 400:
+        return InvalidRequestError(status, message, body)
+    if status == 401:
+        return AuthenticationError(status, message, body)
+    if status == 402:
+        return InsufficientCreditsError(status, message, body)
+    if status == 429:
+        retry_after = _number_field(body, "retryAfterSec")
+        if retry_after is None:
+            retry_after = _parse_retry_after(headers.get("Retry-After"))
+        return RateLimitError(status, message, body, retry_after)
+    if status >= 500:
+        return ServerError(status, message, body)
+    return APIError(status, message, body)
+
+
+def _describe(status: int, body: Any) -> str:
+    error = _string_field(body, "error")
+    detail = _string_field(body, "message")
+    if error and detail:
+        return f"{error}: {detail}"
+    return error or detail or f"HTTP {status}"
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        return None
+    return seconds if seconds >= 0 else None
+
+
+def _number_field(body: Any, key: str) -> Optional[float]:
+    value = body.get(key) if isinstance(body, dict) else None
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+
+def _string_field(body: Any, key: str) -> Optional[str]:
+    value = body.get(key) if isinstance(body, dict) else None
+    return value if isinstance(value, str) and value else None

promtexpress-0.1.0/src/promtexpress/_types.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import List, Literal, Optional, TypedDict
+
+
+class Answer(TypedDict):
+    question: str
+    answer: str
+
+
+class Iteration(TypedDict):
+    ofPromptId: str
+    feedback: str
+
+
+class ChipQuestion(TypedDict):
+    label: str
+    options: List[str]
+
+
+class Assumption(TypedDict):
+    key: str
+    value: str
+    label_tr: str
+
+
+class RecentEntry(TypedDict):
+    id: str
+    mod: str
+    title: str
+    userInput: str
+    date: str
+
+
+class _GenerateResultOptional(TypedDict, total=False):
+    chipQuestions: List[ChipQuestion]
+    ambiguityClarifications: List[str]
+
+
+class GenerateResult(_GenerateResultOptional):
+    promptId: str
+    output: str
+    creditsUsed: int
+    creditsRemaining: int
+    latencyMs: int
+    validationScore: Optional[float]
+    validationIssues: List[str]
+    assumptions: List[Assumption]
+    traceId: str
+    scenario: Literal["A", "B", "C"]
+    recentEntry: RecentEntry
+
+
+class Template(TypedDict):
+    id: str
+    title: str
+    description: Optional[str]
+    category: str
+    modality: str
+    engine: Optional[str]
+    variables: object
+    version: str
+
+
+class HistoryRow(TypedDict):
+    id: str
+    title: str
+    modality: str
+    engine: str
+    credits: int
+    date: str
+    status: Literal["Done", "Failed"]
+    userInput: str
+    result: Optional[str]
+
+
+class HistoryPage(TypedDict):
+    rows: List[HistoryRow]
+    total: int
+    page: int
+    pageSize: int

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

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: promtexpress
+Version: 0.1.0
+Summary: Official Python client for the PromtExpress API
+Author: Webitro
+License-Expression: MIT
+Project-URL: Homepage, https://promtexpress.com
+Project-URL: Source, https://github.com/WebitroHQ/promtexpress-oss
+Project-URL: Issues, https://github.com/WebitroHQ/promtexpress-oss/issues
+Keywords: promtexpress,prompt,prompt-engineering,llm,ai,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# promtexpress
+
+Official Python client for the [PromtExpress](https://promtexpress.com) API. Standard library only, Python 3.9+.
+
+```bash
+pip install promtexpress
+```
+
+## Usage
+
+```python
+from promtexpress import PromtExpress
+
+client = PromtExpress()  # reads PROMTEXPRESS_API_KEY
+
+result = client.generate(
+    "product launch email for a note-taking app, friendly tone",
+    "text",  # text | code | image | video | audio | music
+)
+print(result["output"])
+print(result["creditsRemaining"], "credits left")
+```
+
+### Clarifying questions and iteration
+
+```python
+if result.get("chipQuestions"):
+    better = client.generate(
+        "product launch email for a note-taking app",
+        "text",
+        answers=[{"question": result["chipQuestions"][0]["label"], "answer": "developers"}],
+    )
+
+refined = client.generate(
+    "product launch email for a note-taking app",
+    "text",
+    iteration={"ofPromptId": result["promptId"], "feedback": "shorter, mention the free tier"},
+)
+```
+
+### Templates and history
+
+```python
+templates = client.list_templates(modality="image")
+
+page = client.list_history(page=0, limit=50)
+
+for entry in client.iter_history(modality="video"):
+    print(entry["date"], entry["title"])
+```
+
+## Errors
+
+All errors inherit from `PromtExpressError`: `InvalidRequestError` (400), `AuthenticationError` (401), `InsufficientCreditsError` (402, with `remaining` and `required`), `RateLimitError` (429, with `retry_after`), `ServerError` (5xx) and `APIConnectionError` (network or timeout).
+
+Time-based rate limits are retried automatically (`max_retries`, default 2).
+
+## License
+
+MIT

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/promtexpress/__init__.py
+src/promtexpress/_client.py
+src/promtexpress/_errors.py
+src/promtexpress/_types.py
+src/promtexpress/py.typed
+src/promtexpress.egg-info/PKG-INFO
+src/promtexpress.egg-info/SOURCES.txt
+src/promtexpress.egg-info/dependency_links.txt
+src/promtexpress.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+promtexpress

promtexpress-0.1.0/tests/test_client.py

@@ -0,0 +1,183 @@
+import json
+import os
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from promtexpress import (
+    APIConnectionError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    PromtExpress,
+    PromtExpressError,
+    RateLimitError,
+    ServerError,
+)
+
+RESULT = {
+    "promptId": "p_1",
+    "output": "You are a senior copywriter...",
+    "creditsUsed": 2,
+    "creditsRemaining": 98,
+    "latencyMs": 1200,
+    "validationScore": 0.92,
+    "validationIssues": [],
+    "assumptions": [],
+    "traceId": "t_1",
+    "scenario": "A",
+    "recentEntry": {"id": "p_1", "mod": "text", "title": "t", "userInput": "u", "date": "d"},
+}
+
+
+class MockApi:
+    """A real HTTP server that replays scripted responses and records requests."""
+
+    def __init__(self):
+        self.responses = []
+        self.requests = []
+        api = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def _reply(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                raw = self.rfile.read(length) if length else b""
+                api.requests.append(
+                    {
+                        "method": self.command,
+                        "url": urlparse(self.path),
+                        "headers": dict(self.headers),
+                        "body": json.loads(raw) if raw else None,
+                    }
+                )
+                status, body, headers = api.responses.pop(0)
+                payload = json.dumps(body).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(payload)))
+                for key, value in headers.items():
+                    self.send_header(key, value)
+                self.end_headers()
+                self.wfile.write(payload)
+
+            do_GET = _reply
+            do_POST = _reply
+
+            def log_message(self, *args):
+                pass
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.base_url = f"http://127.0.0.1:{self.server.server_address[1]}/api/v1"
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+
+    def reply(self, status, body, headers=None):
+        self.responses.append((status, body, headers or {}))
+
+    def close(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+
+class ClientTest(unittest.TestCase):
+    def setUp(self):
+        os.environ.pop("PROMTEXPRESS_API_KEY", None)
+        os.environ.pop("PROMTEXPRESS_BASE_URL", None)
+        self.api = MockApi()
+        self.client = PromtExpress("pe_test_py", base_url=self.api.base_url + "/")
+
+    def tearDown(self):
+        self.api.close()
+
+    def test_generate_sends_authenticated_json(self):
+        self.api.reply(200, RESULT)
+
+        result = self.client.generate("launch email for a CRM", "text", target_engine_id="eng_1")
+
+        self.assertEqual(result["output"], RESULT["output"])
+        request = self.api.requests[0]
+        self.assertEqual(request["method"], "POST")
+        self.assertEqual(request["url"].path, "/api/v1/generate")
+        self.assertEqual(request["headers"]["Authorization"], "Bearer pe_test_py")
+        self.assertEqual(
+            request["body"],
+            {"intent": "launch email for a CRM", "modality": "text", "targetEngineId": "eng_1"},
+        )
+
+    def test_reads_api_key_from_environment(self):
+        os.environ["PROMTEXPRESS_API_KEY"] = "pe_test_env"
+        self.api.reply(200, {"templates": []})
+
+        PromtExpress(base_url=self.api.base_url).list_templates()
+
+        self.assertEqual(self.api.requests[0]["headers"]["Authorization"], "Bearer pe_test_env")
+
+    def test_missing_api_key(self):
+        with self.assertRaises(PromtExpressError):
+            PromtExpress()
+
+    def test_validates_before_calling_api(self):
+        with self.assertRaisesRegex(PromtExpressError, "3 to 4000"):
+            self.client.generate("hi", "text")
+        with self.assertRaisesRegex(PromtExpressError, "modality"):
+            self.client.generate("hello there", "poem")
+        self.assertEqual(self.api.requests, [])
+
+    def test_authentication_error(self):
+        self.api.reply(401, {"error": "Invalid or inactive API key"})
+
+        with self.assertRaises(AuthenticationError) as ctx:
+            self.client.list_templates()
+        self.assertEqual(ctx.exception.status, 401)
+        self.assertEqual(str(ctx.exception), "Invalid or inactive API key")
+
+    def test_insufficient_credits(self):
+        self.api.reply(402, {"error": "Insufficient credits", "remaining": 1, "required": 4})
+
+        with self.assertRaises(InsufficientCreditsError) as ctx:
+            self.client.generate("a product video", "video")
+        self.assertEqual((ctx.exception.remaining, ctx.exception.required), (1, 4))
+
+    def test_retries_time_based_rate_limit(self):
+        self.api.reply(429, {"error": "Rate limit exceeded", "retryAfterSec": 0}, {"Retry-After": "0"})
+        self.api.reply(200, RESULT)
+
+        self.assertEqual(self.client.generate("launch email", "text")["promptId"], "p_1")
+        self.assertEqual(len(self.api.requests), 2)
+
+    def test_does_not_retry_iteration_limit(self):
+        self.api.reply(429, {"error": "Iteration limit reached"})
+
+        with self.assertRaises(RateLimitError) as ctx:
+            self.client.generate("launch email", "text")
+        self.assertIsNone(ctx.exception.retry_after)
+        self.assertEqual(len(self.api.requests), 1)
+
+    def test_server_error_includes_pipeline_message(self):
+        self.api.reply(503, {"error": "Pipeline error at layer 4", "message": "synth timeout"})
+
+        with self.assertRaises(ServerError) as ctx:
+            self.client.generate("launch email", "text")
+        self.assertEqual(str(ctx.exception), "Pipeline error at layer 4: synth timeout")
+
+    def test_connection_error(self):
+        client = PromtExpress("k", base_url="http://127.0.0.1:9/api/v1", timeout=2)
+        with self.assertRaises(APIConnectionError):
+            client.list_history()
+
+    def test_iter_history_walks_all_pages(self):
+        def row(i):
+            return {"id": i, "title": i, "modality": "Text", "engine": "e", "credits": 1, "date": "d", "status": "Done", "userInput": i, "result": "r"}
+
+        self.api.reply(200, {"rows": [row("a"), row("b")], "total": 3, "page": 0, "pageSize": 2})
+        self.api.reply(200, {"rows": [row("c")], "total": 3, "page": 1, "pageSize": 2})
+
+        ids = [entry["id"] for entry in self.client.iter_history(limit=2, modality="text")]
+
+        self.assertEqual(ids, ["a", "b", "c"])
+        queries = [parse_qs(r["url"].query) for r in self.api.requests]
+        self.assertEqual([q["page"] for q in queries], [["0"], ["1"]])
+        self.assertEqual(queries[0]["modality"], ["text"])
+
+
+if __name__ == "__main__":
+    unittest.main()