tacet 0.1.0__tar.gz

tacet-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+
+# Node / JS
+node_modules/
+*.tgz
+.turbo/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Secrets - never commit
+.env
+*.key

tacet-0.1.0/LICENSE

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

tacet-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: tacet
+Version: 0.1.0
+Summary: Official Python client for the Tacet API
+Project-URL: Homepage, https://tacet.codepawl.com
+Project-URL: Documentation, https://tacet.codepawl.com/docs
+Author-email: CodePawl <hello@codepawl.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,classification,llm,tacet,typed decisions
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Description-Content-Type: text/markdown
+
+# tacet
+
+Official Python client for the [Tacet API](https://tacet.codepawl.com/docs).
+
+## Install
+
+```bash
+pip install tacet
+# or
+uv add tacet
+```
+
+## Quickstart
+
+```python
+from tacet import Tacet, choice, score, noul
+
+client = Tacet(api_key="tacet_sk_...")  # or set TACET_API_KEY
+
+result = client.decide(
+    state="Customer says their export has been stuck at 'processing' for two days.",
+    questions={
+        "routing_team": choice(
+            "Which team should own this ticket?",
+            {"billing": "Payment or invoicing issues", "support": "Product or account issues"},
+        ),
+        "urgency": score(
+            "How urgent is this ticket?",
+            ["low", "medium", "high", "critical"],
+        ),
+        "needs_human": noul("Does this ticket need a human to step in?"),
+    },
+)
+
+print(result.answers["routing_team"].choice)
+print(result.answers["urgency"].score)
+print(result.answers["needs_human"].noul)
+print(result.usage.input_tokens)
+```
+
+An `AsyncTacet` client with the same methods, `await`ed, is available for
+async code.
+
+## Question types
+
+- **choice**: pick one option out of a named set. `criteria` maps option
+  names to descriptions. The answer carries `choice`, `probabilities` (one
+  per option), and `confidence`.
+- **score**: an expected level over an ordered list of levels. `criteria`
+  is that list. The answer carries `score`, `probabilities` (one per level
+  index), and `confidence`.
+- **noul**: yes or no. `noul` is the probability of yes, from 0 to 1, and
+  an optional `criteria` object says what "true" and "false" mean. The answer
+  carries `noul` and `confidence`, no probabilities.
+
+The `choice`, `score`, and `noul` helpers build the question dict for you;
+you can also pass the dict shape directly.
+
+## Errors and retries
+
+Every non-2xx response raises a subclass of `TacetError`, which carries
+`status`, `code`, `error_type`, `param`, `request_id`, and `message`:
+
+- `AuthenticationError`: 401 (missing, invalid, or revoked API key)
+- `InsufficientCreditError`: 402 (out of credit)
+- `RateLimitError`: 429, also carries `retry_after` seconds
+- `InvalidRequestError`: 400/404/413 (bad request, unknown model, state too large, etc.)
+- `APIError`: 5xx
+- `APIConnectionError`: the request failed before a response came back
+
+The client retries 429s (honoring the `Retry-After` header) and 500/502/503/504
+responses and connection failures, with exponential backoff and jitter, up to
+`max_retries` times (default 2). Other 4xx errors fail immediately and are
+never retried.
+
+## Idle starts
+
+If the API hasn't been called in a while, the first request after that idle
+period can take tens of seconds while it starts back up. The default timeout
+(90 seconds) accounts for this; don't lower it unless you know your traffic
+is steady.
+
+## Pricing
+
+$0.042 per 1M input tokens, and output is free. Details are in the
+[API docs](https://tacet.codepawl.com/docs).

tacet-0.1.0/README.md

@@ -0,0 +1,86 @@
+# tacet
+
+Official Python client for the [Tacet API](https://tacet.codepawl.com/docs).
+
+## Install
+
+```bash
+pip install tacet
+# or
+uv add tacet
+```
+
+## Quickstart
+
+```python
+from tacet import Tacet, choice, score, noul
+
+client = Tacet(api_key="tacet_sk_...")  # or set TACET_API_KEY
+
+result = client.decide(
+    state="Customer says their export has been stuck at 'processing' for two days.",
+    questions={
+        "routing_team": choice(
+            "Which team should own this ticket?",
+            {"billing": "Payment or invoicing issues", "support": "Product or account issues"},
+        ),
+        "urgency": score(
+            "How urgent is this ticket?",
+            ["low", "medium", "high", "critical"],
+        ),
+        "needs_human": noul("Does this ticket need a human to step in?"),
+    },
+)
+
+print(result.answers["routing_team"].choice)
+print(result.answers["urgency"].score)
+print(result.answers["needs_human"].noul)
+print(result.usage.input_tokens)
+```
+
+An `AsyncTacet` client with the same methods, `await`ed, is available for
+async code.
+
+## Question types
+
+- **choice**: pick one option out of a named set. `criteria` maps option
+  names to descriptions. The answer carries `choice`, `probabilities` (one
+  per option), and `confidence`.
+- **score**: an expected level over an ordered list of levels. `criteria`
+  is that list. The answer carries `score`, `probabilities` (one per level
+  index), and `confidence`.
+- **noul**: yes or no. `noul` is the probability of yes, from 0 to 1, and
+  an optional `criteria` object says what "true" and "false" mean. The answer
+  carries `noul` and `confidence`, no probabilities.
+
+The `choice`, `score`, and `noul` helpers build the question dict for you;
+you can also pass the dict shape directly.
+
+## Errors and retries
+
+Every non-2xx response raises a subclass of `TacetError`, which carries
+`status`, `code`, `error_type`, `param`, `request_id`, and `message`:
+
+- `AuthenticationError`: 401 (missing, invalid, or revoked API key)
+- `InsufficientCreditError`: 402 (out of credit)
+- `RateLimitError`: 429, also carries `retry_after` seconds
+- `InvalidRequestError`: 400/404/413 (bad request, unknown model, state too large, etc.)
+- `APIError`: 5xx
+- `APIConnectionError`: the request failed before a response came back
+
+The client retries 429s (honoring the `Retry-After` header) and 500/502/503/504
+responses and connection failures, with exponential backoff and jitter, up to
+`max_retries` times (default 2). Other 4xx errors fail immediately and are
+never retried.
+
+## Idle starts
+
+If the API hasn't been called in a while, the first request after that idle
+period can take tens of seconds while it starts back up. The default timeout
+(90 seconds) accounts for this; don't lower it unless you know your traffic
+is steady.
+
+## Pricing
+
+$0.042 per 1M input tokens, and output is free. Details are in the
+[API docs](https://tacet.codepawl.com/docs).

tacet-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tacet"
+version = "0.1.0"
+description = "Official Python client for the Tacet API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "CodePawl", email = "hello@codepawl.com" }]
+keywords = ["tacet", "typed decisions", "classification", "api client", "llm"]
+dependencies = ["httpx>=0.23"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "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",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://tacet.codepawl.com"
+Documentation = "https://tacet.codepawl.com/docs"
+
+[dependency-groups]
+dev = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tacet"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

tacet-0.1.0/src/tacet/__init__.py

@@ -0,0 +1,57 @@
+"""Official Python client for the Tacet API."""
+
+from ._async_client import AsyncTacet
+from ._client import Tacet
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    InsufficientCreditError,
+    InvalidRequestError,
+    RateLimitError,
+    TacetError,
+)
+from ._models import (
+    Answer,
+    ChoiceAnswer,
+    DecideResult,
+    HealthStatus,
+    Model,
+    ModelList,
+    ModelPricing,
+    NoulAnswer,
+    ScoreAnswer,
+    Usage,
+)
+from ._questions import Question, choice, noul, score
+from ._version import __version__
+
+__all__ = [
+    "Tacet",
+    "AsyncTacet",
+    "__version__",
+    # question builders
+    "choice",
+    "score",
+    "noul",
+    "Question",
+    # result types
+    "DecideResult",
+    "Answer",
+    "ChoiceAnswer",
+    "ScoreAnswer",
+    "NoulAnswer",
+    "Usage",
+    "Model",
+    "ModelList",
+    "ModelPricing",
+    "HealthStatus",
+    # errors
+    "TacetError",
+    "AuthenticationError",
+    "InsufficientCreditError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "APIError",
+    "APIConnectionError",
+]

tacet-0.1.0/src/tacet/_async_client.py

@@ -0,0 +1,121 @@
+"""Asynchronous Tacet client."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+import httpx
+
+from ._base_client import (
+    DEFAULT_BASE_URL,
+    build_decide_payload,
+    build_headers,
+    compute_backoff_seconds,
+    error_from_response,
+    should_retry_status,
+)
+from ._errors import APIConnectionError
+from ._models import (
+    DecideResult,
+    HealthStatus,
+    ModelList,
+    decode_decide_response,
+    decode_health,
+    decode_model_list,
+)
+from ._questions import Question
+from ._version import __version__
+
+
+class AsyncTacet:
+    """Asynchronous client for the Tacet API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 90.0,
+        max_retries: int = 2,
+        *,
+        http_client: Optional[httpx.AsyncClient] = None,
+        sleep_function: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        resolved_api_key = api_key or os.environ.get("TACET_API_KEY")
+        if not resolved_api_key:
+            raise ValueError(
+                "No Tacet API key provided. Pass api_key=... to AsyncTacet(), or set the "
+                "TACET_API_KEY environment variable."
+            )
+
+        self.api_key = resolved_api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._sleep_function = sleep_function
+        self._http_client = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def close(self) -> None:
+        await self._http_client.aclose()
+
+    async def __aenter__(self) -> "AsyncTacet":
+        return self
+
+    async def __aexit__(self, *exception_info: object) -> None:
+        await self.close()
+
+    async def decide(
+        self,
+        state: Any,
+        questions: Dict[str, Question],
+        model: Optional[str] = "tacet-1",
+    ) -> DecideResult:
+        """Ask the model to answer ``questions`` about ``state``."""
+        payload = build_decide_payload(state, questions, model)
+        response = await self._request("POST", "/systemone", json_body=payload)
+        return decode_decide_response(response.json())
+
+    async def models(self) -> ModelList:
+        """List the models available through the API."""
+        response = await self._request("GET", "/models")
+        return decode_model_list(response.json())
+
+    async def health(self) -> HealthStatus:
+        """Check API health."""
+        response = await self._request("GET", "/health")
+        return decode_health(response.json())
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> httpx.Response:
+        headers = build_headers(self.api_key, f"tacet-python/{__version__}")
+        url = f"{self.base_url}{path}"
+
+        attempt_number = 0
+        while True:
+            try:
+                response = await self._http_client.request(method, url, headers=headers, json=json_body)
+            except httpx.HTTPError as network_error:
+                if attempt_number >= self.max_retries:
+                    raise APIConnectionError(
+                        f"Connection to Tacet API failed: {network_error}"
+                    ) from network_error
+                await self._sleep_function(compute_backoff_seconds(attempt_number, None))
+                attempt_number += 1
+                continue
+
+            if response.status_code < 400:
+                return response
+
+            error = error_from_response(response)
+
+            if attempt_number < self.max_retries and should_retry_status(response.status_code):
+                retry_after_seconds = getattr(error, "retry_after", None)
+                await self._sleep_function(compute_backoff_seconds(attempt_number, retry_after_seconds))
+                attempt_number += 1
+                continue
+
+            raise error

tacet-0.1.0/src/tacet/_base_client.py

@@ -0,0 +1,148 @@
+"""Request/response plumbing shared by the sync and async Tacet clients.
+
+Kept free of any actual HTTP I/O so both ``Tacet`` and ``AsyncTacet`` can
+reuse it without duplicating the header, payload, error-decoding, and
+retry-timing logic.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    InsufficientCreditError,
+    InvalidRequestError,
+    RateLimitError,
+    TacetError,
+)
+
+DEFAULT_BASE_URL = "https://tacet.codepawl.com/v1"
+
+_RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+_DEFAULT_RETRY_AFTER_SECONDS = 1.0
+_MAX_BACKOFF_SECONDS = 30.0
+_JITTER_FRACTION = 0.1
+
+
+def build_headers(api_key: str, user_agent: str) -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "User-Agent": user_agent,
+    }
+
+
+def build_decide_payload(
+    state: Any,
+    questions: Dict[str, Any],
+    model: Optional[str],
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {"state": state, "questions": questions}
+    if model is not None:
+        payload["model"] = model
+    return payload
+
+
+def should_retry_status(status_code: int) -> bool:
+    return status_code in _RETRYABLE_STATUS_CODES
+
+
+def parse_retry_after_seconds(header_value: Optional[str]) -> float:
+    if header_value is None:
+        return _DEFAULT_RETRY_AFTER_SECONDS
+    try:
+        return float(header_value)
+    except ValueError:
+        return _DEFAULT_RETRY_AFTER_SECONDS
+
+
+def compute_backoff_seconds(attempt_number: int, retry_after_seconds: Optional[float]) -> float:
+    """Delay before the next attempt.
+
+    Honours the server's ``Retry-After`` when given; otherwise exponential
+    backoff with jitter, capped at ``_MAX_BACKOFF_SECONDS``.
+    """
+    if retry_after_seconds is not None:
+        return retry_after_seconds
+
+    base_delay_seconds = min(2**attempt_number, _MAX_BACKOFF_SECONDS)
+    jitter_seconds = random.uniform(0, base_delay_seconds * _JITTER_FRACTION)
+    return base_delay_seconds + jitter_seconds
+
+
+def error_from_response(response: httpx.Response) -> TacetError:
+    """Build the right ``TacetError`` subclass from a non-2xx response."""
+    status_code = response.status_code
+    request_id = response.headers.get("X-Request-Id")
+
+    message = f"Tacet API request failed with status {status_code}"
+    code: Optional[str] = None
+    error_type: Optional[str] = None
+    param: Optional[str] = None
+
+    try:
+        error_envelope = response.json().get("error", {})
+    except ValueError:
+        error_envelope = {}
+
+    message = error_envelope.get("message", message)
+    code = error_envelope.get("code")
+    error_type = error_envelope.get("type")
+    param = error_envelope.get("param")
+
+    if status_code == 401:
+        return AuthenticationError(
+            message,
+            status=status_code,
+            code=code,
+            error_type=error_type,
+            param=param,
+            request_id=request_id,
+        )
+
+    if status_code == 402:
+        return InsufficientCreditError(
+            message,
+            status=status_code,
+            code=code,
+            error_type=error_type,
+            param=param,
+            request_id=request_id,
+        )
+
+    if status_code == 429:
+        retry_after_seconds = parse_retry_after_seconds(response.headers.get("Retry-After"))
+        return RateLimitError(
+            message,
+            retry_after=retry_after_seconds,
+            status=status_code,
+            code=code,
+            error_type=error_type,
+            param=param,
+            request_id=request_id,
+        )
+
+    if status_code in (400, 404, 413):
+        return InvalidRequestError(
+            message,
+            status=status_code,
+            code=code,
+            error_type=error_type,
+            param=param,
+            request_id=request_id,
+        )
+
+    return APIError(
+        message,
+        status=status_code,
+        code=code,
+        error_type=error_type,
+        param=param,
+        request_id=request_id,
+    )