promtexpress 0.1.0__py3-none-any.whl

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/_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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+promtexpress/__init__.py,sha256=FOrrVaNArtbfOWmJUiFWqj8O-2UQ_koVuzbLT4utsgY,617
+promtexpress/_client.py,sha256=kp7ZsgdqGUPMnbI3tDEMM6xq10U3viR6p6nDoeiqAYU,5626
+promtexpress/_errors.py,sha256=s96Q3FdX5ZAy2kEphoR5gG0_-3aZG5Eheak363oI6WY,3219
+promtexpress/_types.py,sha256=ieny8LI8Z0foH_guoExTq5U4psHJ9H2KXuWvn4B34JQ,1441
+promtexpress/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+promtexpress-0.1.0.dist-info/METADATA,sha256=jR6qdJHTqQnluSa7RjlaCQ1glXkn80PQU38zM8Lr4WY,2197
+promtexpress-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+promtexpress-0.1.0.dist-info/top_level.txt,sha256=Pop3ojYVe7qQNy0LwZ9fOatlYZ_-jV3g7geIqHGjV68,13
+promtexpress-0.1.0.dist-info/RECORD,,

promtexpress-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

promtexpress-0.1.0.dist-info/top_level.txt

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