uprelic 0.1.0__tar.gz

uprelic-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.env
+.venv/
+node_modules/
+dist/
+.DS_Store
+supabase/.temp/

uprelic-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: uprelic
+Version: 0.1.0
+Summary: Python client for the Uprelic API
+Project-URL: Documentation, https://api.uprelic.com/v1/docs
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# Uprelic Python SDK
+
+```sh
+pip install uprelic
+```
+
+Set `UPRELIC_API_KEY` (create a key at https://platform.uprelic.com), or pass `api_key=` to the client.
+
+```python
+from uprelic import Uprelic, Noul, Choice, Score
+
+client = Uprelic()
+response = client.system_one(
+    model="strom-1.0.7",
+    state="I was charged twice for my subscription. Please fix this today.",
+    questions={
+        "billing": Noul("Is this message about billing?"),
+        "tone": Choice("What is the tone?", criteria={"angry": "Upset or hostile", "calm": "Neutral or polite"}),
+        "urgency": Score("How urgent is this?", criteria=["Can wait", "This week", "Today"]),
+    },
+)
+
+response.nouls["billing"].noul        # 0.98
+response.choices["tone"].choice       # "angry"
+response.scores["urgency"].score      # 1.8
+response.usage.input_tokens
+```
+
+Images go in `images=` as http(s) or `data:image/...` URLs. `client.models()` lists the available models.
+
+## Async
+
+```python
+from uprelic import AsyncUprelic
+
+async with AsyncUprelic() as client:
+    response = await client.system_one(model="strom-1.0.7", state="...", questions={...})
+```
+
+## Errors and retries
+
+Failed requests raise `uprelic.APIError` subclasses: `AuthenticationError` (401), `InsufficientBalanceError` (402),
+`InvalidRequestError` (400, 422), `RateLimitError` (429) and `ServerError` (5xx). Each has `status_code` and `detail`.
+
+Rate limits (429), 502/503/504 responses and connection failures are retried twice with backoff. Change this with
+`Uprelic(max_retries=...)`.
+
+API reference: https://api.uprelic.com/v1/docs

uprelic-0.1.0/README.md

@@ -0,0 +1,48 @@
+# Uprelic Python SDK
+
+```sh
+pip install uprelic
+```
+
+Set `UPRELIC_API_KEY` (create a key at https://platform.uprelic.com), or pass `api_key=` to the client.
+
+```python
+from uprelic import Uprelic, Noul, Choice, Score
+
+client = Uprelic()
+response = client.system_one(
+    model="strom-1.0.7",
+    state="I was charged twice for my subscription. Please fix this today.",
+    questions={
+        "billing": Noul("Is this message about billing?"),
+        "tone": Choice("What is the tone?", criteria={"angry": "Upset or hostile", "calm": "Neutral or polite"}),
+        "urgency": Score("How urgent is this?", criteria=["Can wait", "This week", "Today"]),
+    },
+)
+
+response.nouls["billing"].noul        # 0.98
+response.choices["tone"].choice       # "angry"
+response.scores["urgency"].score      # 1.8
+response.usage.input_tokens
+```
+
+Images go in `images=` as http(s) or `data:image/...` URLs. `client.models()` lists the available models.
+
+## Async
+
+```python
+from uprelic import AsyncUprelic
+
+async with AsyncUprelic() as client:
+    response = await client.system_one(model="strom-1.0.7", state="...", questions={...})
+```
+
+## Errors and retries
+
+Failed requests raise `uprelic.APIError` subclasses: `AuthenticationError` (401), `InsufficientBalanceError` (402),
+`InvalidRequestError` (400, 422), `RateLimitError` (429) and `ServerError` (5xx). Each has `status_code` and `detail`.
+
+Rate limits (429), 502/503/504 responses and connection failures are retried twice with backoff. Change this with
+`Uprelic(max_retries=...)`.
+
+API reference: https://api.uprelic.com/v1/docs

uprelic-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uprelic"
+dynamic = ["version"]
+description = "Python client for the Uprelic API"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27", "pydantic>=2"]
+
+[project.urls]
+Documentation = "https://api.uprelic.com/v1/docs"
+
+[tool.hatch.version]
+path = "src/uprelic/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md"]

uprelic-0.1.0/src/uprelic/__init__.py

@@ -0,0 +1,12 @@
+__version__ = "0.1.0"
+
+from .client import AsyncUprelic, Uprelic
+from .errors import (
+    APIError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    RateLimitError,
+    ServerError,
+)
+from .types import Choice, ChoiceAnswer, Model, Noul, NoulAnswer, Score, ScoreAnswer, SystemOneResponse, Usage

uprelic-0.1.0/src/uprelic/client.py

@@ -0,0 +1,132 @@
+import asyncio
+import os
+import time
+
+import httpx
+
+from . import __version__
+from .errors import error_for
+from .types import Model, ModelList, Question, SystemOneResponse, question_dict
+
+BASE_URL = "https://api.uprelic.com/v1"
+TIMEOUT = 150
+RETRY_STATUSES = {429, 502, 503, 504}
+
+
+class _Base:
+    def __init__(self, api_key, base_url, timeout, max_retries):
+        api_key = api_key or os.environ.get("UPRELIC_API_KEY")
+        self.base_url = (base_url or os.environ.get("UPRELIC_BASE_URL") or BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.headers = {"User-Agent": f"uprelic-python/{__version__}"}
+        if api_key:
+            self.headers["Authorization"] = f"Bearer {api_key}"
+
+    def _retry_delay(self, attempt, response):
+        if attempt >= self.max_retries:
+            return None
+        if response is None or response.status_code in RETRY_STATUSES:
+            retry_after = response is not None and response.headers.get("Retry-After")
+            return min(float(retry_after), 30) if retry_after else 0.5 * 2 ** attempt
+        return None
+
+
+def _body(model, state, questions, images):
+    body = {"model": model, "state": state,
+            "questions": {name: question_dict(question) for name, question in questions.items()}}
+    if images:
+        body["media"] = [{"type": "image", "url": url} for url in images]
+    return body
+
+
+def _parse(response):
+    if response.is_success:
+        return response.json()
+    try:
+        detail = response.json().get("detail")
+    except (ValueError, AttributeError):
+        detail = response.text
+    raise error_for(response.status_code, detail)
+
+
+class Uprelic(_Base):
+    def __init__(self, api_key=None, *, base_url=None, timeout=TIMEOUT, max_retries=2, http_client=None):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client()
+
+    def system_one(self, *, model: str, state, questions: dict[str, Question],
+                   images: list[str] | None = None) -> SystemOneResponse:
+        body = _body(model, state, questions, images)
+        return SystemOneResponse.model_validate(self._request("POST", "/systemone", body))
+
+    def models(self) -> list[Model]:
+        return ModelList.model_validate(self._request("GET", "/models")).models
+
+    def _request(self, method, path, body=None):
+        attempt = 0
+        while True:
+            response = None
+            try:
+                response = self._http.request(method, self.base_url + path, json=body, headers=self.headers,
+                                              timeout=self.timeout)
+            except httpx.ConnectError:
+                if self._retry_delay(attempt, None) is None:
+                    raise
+            delay = self._retry_delay(attempt, response)
+            if response is not None and delay is None:
+                return _parse(response)
+            time.sleep(delay)
+            attempt += 1
+
+    def close(self):
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class AsyncUprelic(_Base):
+    def __init__(self, api_key=None, *, base_url=None, timeout=TIMEOUT, max_retries=2, http_client=None):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient()
+
+    async def system_one(self, *, model: str, state, questions: dict[str, Question],
+                         images: list[str] | None = None) -> SystemOneResponse:
+        body = _body(model, state, questions, images)
+        return SystemOneResponse.model_validate(await self._request("POST", "/systemone", body))
+
+    async def models(self) -> list[Model]:
+        return ModelList.model_validate(await self._request("GET", "/models")).models
+
+    async def _request(self, method, path, body=None):
+        attempt = 0
+        while True:
+            response = None
+            try:
+                response = await self._http.request(method, self.base_url + path, json=body, headers=self.headers,
+                                                    timeout=self.timeout)
+            except httpx.ConnectError:
+                if self._retry_delay(attempt, None) is None:
+                    raise
+            delay = self._retry_delay(attempt, response)
+            if response is not None and delay is None:
+                return _parse(response)
+            await asyncio.sleep(delay)
+            attempt += 1
+
+    async def close(self):
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()

uprelic-0.1.0/src/uprelic/errors.py

@@ -0,0 +1,42 @@
+class APIError(Exception):
+    def __init__(self, status_code, detail):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {_message(detail)}")
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class InsufficientBalanceError(APIError):
+    pass
+
+
+class InvalidRequestError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class ServerError(APIError):
+    pass
+
+
+ERRORS = {400: InvalidRequestError, 401: AuthenticationError, 402: InsufficientBalanceError,
+          422: InvalidRequestError, 429: RateLimitError}
+
+
+def error_for(status_code, detail):
+    cls = ERRORS.get(status_code, ServerError if status_code >= 500 else APIError)
+    return cls(status_code, detail)
+
+
+# A 422's detail is a list of {loc, msg}; show each as "questions.tone.criteria: msg".
+def _message(detail):
+    if isinstance(detail, list):
+        return "; ".join(".".join(str(part) for part in error.get("loc", [])[1:]) + ": " + error.get("msg", "")
+                         for error in detail if isinstance(error, dict))
+    return str(detail)

uprelic-0.1.0/src/uprelic/types.py

@@ -0,0 +1,92 @@
+from dataclasses import asdict, dataclass, field
+from typing import Annotated, Any, ClassVar, Literal, Union
+
+from pydantic import BaseModel, Field
+
+Json = Union[str, dict[str, Any], list[Any], None]
+
+
+@dataclass
+class Noul:
+    instructions: Json = None
+    criteria: dict[str, Json] | None = None  # {"true": ..., "false": ...}
+    type: ClassVar[str] = "noul"
+
+
+@dataclass
+class Choice:
+    instructions: Json = None
+    criteria: dict[str, Json] = field(kw_only=True)
+    type: ClassVar[str] = "choice"
+
+
+@dataclass
+class Score:
+    instructions: Json = None
+    criteria: list[Json] = field(kw_only=True)
+    type: ClassVar[str] = "score"
+
+
+Question = Union[Noul, Choice, Score, dict[str, Any]]
+
+
+def question_dict(question):
+    if isinstance(question, dict):
+        return question
+    return {"type": question.type, **{k: v for k, v in asdict(question).items() if v is not None}}
+
+
+class NoulAnswer(BaseModel):
+    type: Literal["noul"]
+    noul: float
+
+
+class ChoiceAnswer(BaseModel):
+    type: Literal["choice"]
+    choice: str
+    confidence: float
+    probabilities: dict[str, float]
+
+
+class ScoreAnswer(BaseModel):
+    type: Literal["score"]
+    score: float
+    confidence: float
+    legend: dict[str, Json]
+    probabilities: dict[str, float]
+
+
+Answer = Annotated[Union[NoulAnswer, ChoiceAnswer, ScoreAnswer], Field(discriminator="type")]
+
+
+class Usage(BaseModel):
+    input_tokens: int
+    output_tokens: int
+
+
+class SystemOneResponse(BaseModel):
+    model: str
+    answers: dict[str, Answer]
+    usage: Usage
+
+    @property
+    def nouls(self) -> dict[str, NoulAnswer]:
+        return {name: a for name, a in self.answers.items() if isinstance(a, NoulAnswer)}
+
+    @property
+    def choices(self) -> dict[str, ChoiceAnswer]:
+        return {name: a for name, a in self.answers.items() if isinstance(a, ChoiceAnswer)}
+
+    @property
+    def scores(self) -> dict[str, ScoreAnswer]:
+        return {name: a for name, a in self.answers.items() if isinstance(a, ScoreAnswer)}
+
+
+class Model(BaseModel):
+    name: str
+    description: str
+    release_date: str
+
+
+class ModelList(BaseModel):
+    models: list[Model]

uprelic-0.1.0/tests/test_client.py

@@ -0,0 +1,94 @@
+import asyncio
+import json
+
+import httpx
+import pytest
+
+import uprelic
+from uprelic import AsyncUprelic, Choice, Noul, Score, Uprelic
+
+RESPONSE = {
+    "model": "strom-1.0.7",
+    "answers": {
+        "billing": {"type": "noul", "noul": 0.98},
+        "tone": {"type": "choice", "choice": "angry", "confidence": 0.9,
+                 "probabilities": {"angry": 0.9, "calm": 0.1}},
+        "urgency": {"type": "score", "score": 1.7, "confidence": 0.8, "legend": {"0": "Later", "1": "Soon", "2": "Now"},
+                    "probabilities": {"0": 0.1, "1": 0.1, "2": 0.8}},
+    },
+    "usage": {"input_tokens": 120, "output_tokens": 3},
+}
+QUESTIONS = {
+    "billing": Noul("Is this about billing?"),
+    "tone": Choice("What is the tone?", criteria={"angry": "Upset", "calm": None}),
+    "urgency": Score(criteria=["Later", "Soon", "Now"]),
+}
+
+
+def client(handler, **kwargs):
+    return Uprelic("key", http_client=httpx.Client(transport=httpx.MockTransport(handler)), **kwargs)
+
+
+def test_system_one():
+    requests = []
+
+    def handler(request):
+        requests.append(request)
+        return httpx.Response(200, json=RESPONSE)
+
+    response = client(handler).system_one(model="strom-1.0.7", state="I was charged twice.", questions=QUESTIONS,
+                                          images=["https://example.com/a.jpg"])
+
+    request = requests[0]
+    assert request.url == "https://api.uprelic.com/v1/systemone"
+    assert request.headers["Authorization"] == "Bearer key"
+    assert json.loads(request.content) == {
+        "model": "strom-1.0.7",
+        "state": "I was charged twice.",
+        "questions": {
+            "billing": {"type": "noul", "instructions": "Is this about billing?"},
+            "tone": {"type": "choice", "instructions": "What is the tone?", "criteria": {"angry": "Upset", "calm": None}},
+            "urgency": {"type": "score", "criteria": ["Later", "Soon", "Now"]},
+        },
+        "media": [{"type": "image", "url": "https://example.com/a.jpg"}],
+    }
+    assert response.nouls["billing"].noul == 0.98
+    assert response.choices["tone"].choice == "angry"
+    assert response.scores["urgency"].score == 1.7
+    assert response.usage.input_tokens == 120
+
+
+def test_models():
+    body = {"models": [{"name": "strom-1.0.7", "description": "General.", "release_date": "2026-09-15"}]}
+    models = client(lambda request: httpx.Response(200, json=body)).models()
+    assert models[0].name == "strom-1.0.7"
+
+
+def test_errors():
+    detail = [{"loc": ["body", "questions", "tone", "criteria"], "msg": "Provide at least one choice.",
+               "type": "value_error"}]
+    with pytest.raises(uprelic.InvalidRequestError, match="questions.tone.criteria: Provide at least one choice."):
+        client(lambda request: httpx.Response(422, json={"detail": detail})).models()
+    with pytest.raises(uprelic.InsufficientBalanceError) as error:
+        client(lambda request: httpx.Response(402, json={"detail": "Balance too low."})).models()
+    assert error.value.status_code == 402
+
+
+def test_retries():
+    responses = iter([httpx.Response(429, headers={"Retry-After": "0"}, json={"detail": "Slow down."}),
+                      httpx.Response(503, text="Unavailable"),
+                      httpx.Response(200, json={"models": []})])
+    assert client(lambda request: next(responses), max_retries=2).models() == []
+
+    with pytest.raises(uprelic.RateLimitError):
+        client(lambda request: httpx.Response(429, headers={"Retry-After": "0"}, json={"detail": "Slow down."}),
+               max_retries=1).models()
+
+
+def test_async():
+    async def run():
+        transport = httpx.MockTransport(lambda request: httpx.Response(200, json=RESPONSE))
+        async with AsyncUprelic("key", http_client=httpx.AsyncClient(transport=transport)) as client:
+            return await client.system_one(model="strom-1.0.7", state="Hi", questions=QUESTIONS)
+
+    assert asyncio.run(run()).nouls["billing"].noul == 0.98