qubac 1.0.0__tar.gz

qubac-1.0.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: qubac
+Version: 1.0.0
+Summary: The official Python SDK for SAM by Qubac
+Project-URL: Homepage, https://qubac.com
+Project-URL: Documentation, https://docs.qubac.com
+Project-URL: Repository, https://github.com/qubac/qubac-python
+Author-email: Qubac <sdk@qubac.com>
+License: MIT
+Keywords: agent,ai,autonomous,qubac,sam
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: anyio>=3.0.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Qubac Python SDK
+
+The official Python library for SAM by Qubac.
+
+```python
+import qubac
+
+client = qubac.Client(api_key="sk-...")
+response = client.tasks.create(
+    model="sam-1",
+    task="what is the speed of light"
+)
+print(response.output)
+```
+
+## Installation
+
+```bash
+pip install qubac
+```
+
+## Docs
+
+https://docs.qubac.com

qubac-1.0.0/README.md

@@ -0,0 +1,24 @@
+# Qubac Python SDK
+
+The official Python library for SAM by Qubac.
+
+```python
+import qubac
+
+client = qubac.Client(api_key="sk-...")
+response = client.tasks.create(
+    model="sam-1",
+    task="what is the speed of light"
+)
+print(response.output)
+```
+
+## Installation
+
+```bash
+pip install qubac
+```
+
+## Docs
+
+https://docs.qubac.com

qubac-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qubac"
+version = "1.0.0"
+description = "The official Python SDK for SAM by Qubac"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Qubac", email = "sdk@qubac.com" }]
+keywords = ["qubac", "sam", "ai", "agent", "autonomous"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.25.0",
+    "anyio>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+    "black",
+    "mypy",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://qubac.com"
+Documentation = "https://docs.qubac.com"
+Repository = "https://github.com/qubac/qubac-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qubac"]
+
+[tool.mypy]
+strict = true
+python_version = "3.9"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

qubac-1.0.0/qubac/__init__.py

@@ -0,0 +1,32 @@
+"""
+Qubac SDK — Python client for SAM
+
+Install:    pip install qubac
+Docs:       https://docs.qubac.com
+
+Quick start:
+    import qubac
+    client = qubac.Client(api_key="sk-...")
+    result = client.tasks.create(model="sam-1", task="what is 2+2")
+    print(result.output)
+"""
+from __future__ import annotations
+from ._client import AsyncClient, Client
+from ._exceptions import (
+    APIConnectionError, APIError, APITimeoutError, ApprovalRequiredError,
+    AuthenticationError, InternalServerError, NotFoundError,
+    PermissionDeniedError, QubacError, RateLimitError,
+    TaskFailedError, TaskTimeoutError,
+)
+from .types import Model, StreamEvent, TaskAsyncResponse, TaskResponse
+
+__version__ = "1.0.0"
+__all__ = [
+    "Client", "AsyncClient",
+    "TaskResponse", "TaskAsyncResponse", "StreamEvent", "Model",
+    "QubacError", "APIError", "APIConnectionError", "APITimeoutError",
+    "AuthenticationError", "PermissionDeniedError", "NotFoundError",
+    "RateLimitError", "InternalServerError",
+    "TaskTimeoutError", "TaskFailedError", "ApprovalRequiredError",
+    "__version__",
+]

qubac-1.0.0/qubac/_client.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+import os
+from typing import Any, Optional
+from ._exceptions import AuthenticationError
+from ._http import AsyncHttpClient, SyncHttpClient
+from .resources.tasks import AsyncTasks, Tasks
+
+__all__ = ["Client", "AsyncClient"]
+
+_DEFAULT_BASE_URL = "https://api.qubac.com"
+_DEFAULT_TIMEOUT = 130.0
+_DEFAULT_MAX_RETRIES = 2
+
+class Client:
+    """
+    Synchronous Qubac client.
+
+    Usage:
+        import qubac
+        client = qubac.Client(api_key="sk-...")
+        result = client.tasks.create(model="sam-1", task="what is 2+2")
+        print(result.output)
+    """
+    tasks: Tasks
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = _DEFAULT_BASE_URL,
+                 timeout: float = _DEFAULT_TIMEOUT, max_retries: int = _DEFAULT_MAX_RETRIES) -> None:
+        resolved = api_key or os.environ.get("QUBAC_API_KEY", "")
+        if not resolved:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key= or set QUBAC_API_KEY.\n"
+                "Get your key at https://console.qubac.com/configure"
+            )
+        self._http = SyncHttpClient(base_url=base_url, api_key=resolved,
+                                    timeout=timeout, max_retries=max_retries)
+        self.tasks = Tasks(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"qubac.Client(base_url={self._http._base_url!r})"
+
+    def with_options(self, *, api_key: Optional[str] = None, base_url: Optional[str] = None,
+                     timeout: Optional[float] = None, max_retries: Optional[int] = None) -> "Client":
+        """Return a new Client with overridden options."""
+        return Client(
+            api_key=api_key or self._http._api_key,
+            base_url=base_url or self._http._base_url,
+            timeout=timeout if timeout is not None else self._http._timeout,
+            max_retries=max_retries if max_retries is not None else self._http._max_retries,
+        )
+
+class AsyncClient:
+    """
+    Asynchronous Qubac client.
+
+    Usage:
+        import asyncio, qubac
+        async def main():
+            async with qubac.AsyncClient(api_key="sk-...") as client:
+                result = await client.tasks.create(model="sam-1", task="what is 2+2")
+                print(result.output)
+        asyncio.run(main())
+    """
+    tasks: AsyncTasks
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = _DEFAULT_BASE_URL,
+                 timeout: float = _DEFAULT_TIMEOUT, max_retries: int = _DEFAULT_MAX_RETRIES) -> None:
+        resolved = api_key or os.environ.get("QUBAC_API_KEY", "")
+        if not resolved:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key= or set QUBAC_API_KEY.\n"
+                "Get your key at https://console.qubac.com/configure"
+            )
+        self._http = AsyncHttpClient(base_url=base_url, api_key=resolved,
+                                     timeout=timeout, max_retries=max_retries)
+        self.tasks = AsyncTasks(self._http)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"qubac.AsyncClient(base_url={self._http._base_url!r})"
+
+    def with_options(self, *, api_key: Optional[str] = None, base_url: Optional[str] = None,
+                     timeout: Optional[float] = None, max_retries: Optional[int] = None) -> "AsyncClient":
+        """Return a new AsyncClient with overridden options."""
+        return AsyncClient(
+            api_key=api_key or self._http._api_key,
+            base_url=base_url or self._http._base_url,
+            timeout=timeout if timeout is not None else self._http._timeout,
+            max_retries=max_retries if max_retries is not None else self._http._max_retries,
+        )

qubac-1.0.0/qubac/_exceptions.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from typing import Any, Dict, Optional
+
+__all__ = [
+    "QubacError", "APIError", "APIConnectionError", "APITimeoutError",
+    "AuthenticationError", "PermissionDeniedError", "NotFoundError",
+    "RateLimitError", "InternalServerError",
+    "TaskTimeoutError", "TaskFailedError", "ApprovalRequiredError",
+]
+
+class QubacError(Exception):
+    def __init__(self, message: str, *, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+class APIError(QubacError): pass
+
+class AuthenticationError(APIError):
+    def __init__(self, message: str = "Authentication failed. Check your API key.") -> None:
+        super().__init__(message, status_code=401)
+
+class PermissionDeniedError(APIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status_code=403)
+
+class NotFoundError(APIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status_code=404)
+
+class RateLimitError(APIError):
+    def __init__(self, message: str, *, reset_at: Optional[str] = None, retry_after: Optional[int] = None) -> None:
+        super().__init__(message, status_code=429)
+        self.reset_at = reset_at
+        self.retry_after = retry_after
+
+class InternalServerError(APIError):
+    def __init__(self, message: str, *, status_code: int = 500) -> None:
+        super().__init__(message, status_code=status_code)
+
+class APIConnectionError(QubacError):
+    def __init__(self, message: str = "Could not connect to the Qubac API.") -> None:
+        super().__init__(message)
+
+class APITimeoutError(QubacError):
+    def __init__(self, timeout: float) -> None:
+        super().__init__(f"Request timed out after {timeout}s.")
+        self.timeout = timeout
+
+class TaskTimeoutError(QubacError):
+    def __init__(self, task_id: str, timeout: int) -> None:
+        super().__init__(
+            f"Task '{task_id}' did not complete within {timeout}s. "
+            f"Use client.tasks.get('{task_id}') to poll for the result."
+        )
+        self.task_id = task_id
+        self.timeout = timeout
+
+class TaskFailedError(QubacError):
+    def __init__(self, task_id: str, reason: Optional[str] = None) -> None:
+        super().__init__(reason or f"Task '{task_id}' failed during execution.")
+        self.task_id = task_id
+        self.reason = reason
+
+class ApprovalRequiredError(QubacError):
+    def __init__(self, task_id: str, detail: Optional[str] = None) -> None:
+        super().__init__(
+            detail or f"Task '{task_id}' requires approval. "
+            "Review it at https://console.qubac.com/approvals"
+        )
+        self.task_id = task_id

qubac-1.0.0/qubac/_http.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+import asyncio, json, logging, random, time
+from typing import Any, AsyncGenerator, Dict, Generator, Optional
+import httpx
+from ._exceptions import (
+    APIConnectionError, APIError, APITimeoutError, AuthenticationError,
+    InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError,
+)
+
+log = logging.getLogger("qubac")
+_SDK_VERSION = "1.0.0"
+_RETRYABLE = {429, 500, 502, 503, 504}
+_BACKOFF_BASE = 0.5
+_BACKOFF_MAX = 8.0
+
+def _user_agent() -> str:
+    import platform
+    return f"qubac-python/{_SDK_VERSION} Python/{platform.python_version()}"
+
+def _headers(api_key: str) -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": _user_agent(),
+        "X-Qubac-SDK-Version": _SDK_VERSION,
+    }
+
+def _backoff(attempt: int) -> float:
+    delay = min(_BACKOFF_BASE * (2 ** attempt), _BACKOFF_MAX)
+    return delay * (0.5 + random.random() * 0.5)
+
+def _raise(status: int, body: Dict[str, Any]) -> None:
+    detail = str(body.get("detail") or body.get("message") or "Unknown error")
+    if status == 401: raise AuthenticationError(f"Authentication failed: {detail}")
+    if status == 403: raise PermissionDeniedError(f"Permission denied: {detail}")
+    if status == 404: raise NotFoundError(f"Not found: {detail}")
+    if status in (429, 402):
+        raise RateLimitError(f"Rate limit: {detail}", reset_at=body.get("reset_at"))
+    if 500 <= status < 600:
+        raise InternalServerError(f"Server error {status}: {detail}", status_code=status)
+    raise APIError(f"API error {status}: {detail}", status_code=status)
+
+class SyncHttpClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float, max_retries: int) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=_headers(api_key),
+            timeout=httpx.Timeout(timeout),
+            follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "SyncHttpClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, *, json_body: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None) -> Dict[str, Any]:
+        kwargs: Dict[str, Any] = {"json": json_body}
+        if timeout is not None:
+            kwargs["timeout"] = httpx.Timeout(timeout)
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+                if resp.status_code in _RETRYABLE and attempt < self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                try: body = resp.json()
+                except Exception: body = {}
+                if not resp.is_success:
+                    _raise(resp.status_code, body)
+                return body
+            except httpx.TimeoutException as exc:
+                if attempt < self._max_retries: time.sleep(_backoff(attempt)); continue
+                raise APITimeoutError(timeout or self._timeout) from exc
+            except httpx.NetworkError as exc:
+                if attempt < self._max_retries: time.sleep(_backoff(attempt)); continue
+                raise APIConnectionError(f"Network error: {exc}") from exc
+        raise APIConnectionError("Request failed after retries")
+
+    def stream_sse(self, path: str, *, timeout: Optional[float] = None) -> Generator[Dict[str, Any], None, None]:
+        hdrs = {**_headers(self._api_key), "Accept": "text/event-stream"}
+        t = httpx.Timeout(timeout or self._timeout)
+        with self._client.stream("GET", path, headers=hdrs, timeout=t) as resp:
+            if not resp.is_success:
+                try: body = resp.json()
+                except Exception: body = {}
+                _raise(resp.status_code, body)
+            buf = ""
+            for chunk in resp.iter_text():
+                buf += chunk
+                while "\n" in buf:
+                    line, buf = buf.split("\n", 1)
+                    if line.strip().startswith("data:"):
+                        raw = line.strip()[5:].strip()
+                        if raw:
+                            try: yield json.loads(raw)
+                            except json.JSONDecodeError: pass
+
+class AsyncHttpClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float, max_retries: int) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=_headers(api_key),
+            timeout=httpx.Timeout(timeout),
+            follow_redirects=True,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def request(self, method: str, path: str, *, json_body: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None) -> Dict[str, Any]:
+        kwargs: Dict[str, Any] = {"json": json_body}
+        if timeout is not None:
+            kwargs["timeout"] = httpx.Timeout(timeout)
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = await self._client.request(method, path, **kwargs)
+                if resp.status_code in _RETRYABLE and attempt < self._max_retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    continue
+                try: body = resp.json()
+                except Exception: body = {}
+                if not resp.is_success:
+                    _raise(resp.status_code, body)
+                return body
+            except httpx.TimeoutException as exc:
+                if attempt < self._max_retries: await asyncio.sleep(_backoff(attempt)); continue
+                raise APITimeoutError(timeout or self._timeout) from exc
+            except httpx.NetworkError as exc:
+                if attempt < self._max_retries: await asyncio.sleep(_backoff(attempt)); continue
+                raise APIConnectionError(f"Network error: {exc}") from exc
+        raise APIConnectionError("Request failed after retries")
+
+    async def stream_sse(self, path: str, *, timeout: Optional[float] = None) -> AsyncGenerator[Dict[str, Any], None]:
+        hdrs = {**_headers(self._api_key), "Accept": "text/event-stream"}
+        t = httpx.Timeout(timeout or self._timeout)
+        async with self._client.stream("GET", path, headers=hdrs, timeout=t) as resp:
+            if not resp.is_success:
+                try: body = resp.json()
+                except Exception: body = {}
+                _raise(resp.status_code, body)
+            buf = ""
+            async for chunk in resp.aiter_text():
+                buf += chunk
+                while "\n" in buf:
+                    line, buf = buf.split("\n", 1)
+                    if line.strip().startswith("data:"):
+                        raw = line.strip()[5:].strip()
+                        if raw:
+                            try: yield json.loads(raw)
+                            except json.JSONDecodeError: pass

qubac-1.0.0/qubac/resources/__init__.py

@@ -0,0 +1,2 @@
+from .tasks import Tasks, AsyncTasks, SyncStreamContext, AsyncStreamContext
+__all__ = ["Tasks", "AsyncTasks", "SyncStreamContext", "AsyncStreamContext"]

qubac-1.0.0/qubac/resources/tasks.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+from typing import Any, AsyncGenerator, Dict, Iterator, List, Optional
+from .._exceptions import TaskFailedError, TaskTimeoutError
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..types import Model, StreamEvent, TaskAsyncResponse, TaskResponse
+
+__all__ = ["Tasks", "AsyncTasks", "SyncStreamContext", "AsyncStreamContext"]
+
+_DEFAULT_MODEL = "sam-1"
+_DEFAULT_TIMEOUT = 120
+_DEFAULT_PRIORITY = "normal"
+
+def _parse(data: Dict[str, Any]) -> TaskResponse:
+    return TaskResponse(
+        id=data["id"], model=data.get("model", _DEFAULT_MODEL),
+        status=data.get("status", "unknown"),
+        output=data.get("output"), nodes_used=data.get("nodes_used", 0),
+        execution_ms=data.get("execution_ms"), created_at=data.get("created_at", ""),
+        metadata=data.get("metadata"), error=data.get("error"),
+    )
+
+def _parse_event(data: Dict[str, Any], task_id: str) -> StreamEvent:
+    return StreamEvent(
+        type=data.get("type", "task.update"), task_id=data.get("task_id", task_id),
+        summary=data.get("summary", ""), timestamp=data.get("timestamp"),
+        node=data.get("node"), output=data.get("output"),
+        nodes_used=data.get("nodes_used"), error=data.get("error"), raw=data,
+    )
+
+def _create_body(task: str, model: str, priority: str, max_nodes: Optional[int], timeout: int, metadata: Optional[Dict]) -> Dict[str, Any]:
+    b: Dict[str, Any] = {"task": task, "model": model, "priority": priority, "timeout": timeout}
+    if max_nodes is not None: b["max_nodes"] = max_nodes
+    if metadata is not None: b["metadata"] = metadata
+    return b
+
+def _submit_body(task: str, model: str, priority: str, max_nodes: Optional[int], metadata: Optional[Dict]) -> Dict[str, Any]:
+    b: Dict[str, Any] = {"task": task, "model": model, "priority": priority}
+    if max_nodes is not None: b["max_nodes"] = max_nodes
+    if metadata is not None: b["metadata"] = metadata
+    return b
+
+class SyncStreamContext:
+    def __init__(self, http: SyncHttpClient, task_id: str, timeout: Optional[float] = None) -> None:
+        self._http = http
+        self._task_id = task_id
+        self._timeout = timeout
+        self._final: Optional[TaskResponse] = None
+
+    def __enter__(self) -> "SyncStreamContext":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        pass
+
+    def __iter__(self) -> Iterator[StreamEvent]:
+        for data in self._http.stream_sse(f"/v1/sam/tasks/{self._task_id}/stream", timeout=self._timeout):
+            evt = _parse_event(data, self._task_id)
+            if evt.type == "stream.end": break
+            yield evt
+            if evt.type == "task.completed":
+                self._final = TaskResponse(id=evt.task_id, model=_DEFAULT_MODEL, status="completed",
+                    output=evt.output, nodes_used=evt.nodes_used or 0,
+                    execution_ms=None, created_at=evt.timestamp or "")
+                break
+            if evt.type == "task.failed":
+                self._final = TaskResponse(id=evt.task_id, model=_DEFAULT_MODEL, status="failed",
+                    output=None, nodes_used=0, execution_ms=None,
+                    created_at=evt.timestamp or "", error=evt.error)
+                break
+
+    @property
+    def final_response(self) -> Optional[TaskResponse]:
+        return self._final
+
+class AsyncStreamContext:
+    def __init__(self, http: AsyncHttpClient, task_id: str, timeout: Optional[float] = None) -> None:
+        self._http = http
+        self._task_id = task_id
+        self._timeout = timeout
+        self._final: Optional[TaskResponse] = None
+
+    async def __aenter__(self) -> "AsyncStreamContext":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        pass
+
+    async def __aiter__(self):
+        async for data in self._http.stream_sse(f"/v1/sam/tasks/{self._task_id}/stream", timeout=self._timeout):
+            evt = _parse_event(data, self._task_id)
+            if evt.type == "stream.end": break
+            yield evt
+            if evt.type == "task.completed":
+                self._final = TaskResponse(id=evt.task_id, model=_DEFAULT_MODEL, status="completed",
+                    output=evt.output, nodes_used=evt.nodes_used or 0,
+                    execution_ms=None, created_at=evt.timestamp or "")
+                break
+            if evt.type == "task.failed":
+                self._final = TaskResponse(id=evt.task_id, model=_DEFAULT_MODEL, status="failed",
+                    output=None, nodes_used=0, execution_ms=None,
+                    created_at=evt.timestamp or "", error=evt.error)
+                break
+
+    @property
+    def final_response(self) -> Optional[TaskResponse]:
+        return self._final
+
+class Tasks:
+    """Sync tasks resource. Access via client.tasks."""
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(self, task: str, *, model: str = _DEFAULT_MODEL, priority: str = _DEFAULT_PRIORITY,
+               max_nodes: Optional[int] = None, timeout: int = _DEFAULT_TIMEOUT,
+               metadata: Optional[Dict[str, Any]] = None, request_timeout: Optional[float] = None) -> TaskResponse:
+        """Create and execute a SAM task synchronously. Waits for completion."""
+        data = self._http.request("POST", "/v1/sam/tasks",
+            json_body=_create_body(task, model, priority, max_nodes, timeout, metadata),
+            timeout=request_timeout)
+        resp = _parse(data)
+        if resp.status == "running": raise TaskTimeoutError(resp.id, timeout)
+        if resp.status == "failed": raise TaskFailedError(resp.id, resp.error)
+        return resp
+
+    def submit(self, task: str, *, model: str = _DEFAULT_MODEL, priority: str = _DEFAULT_PRIORITY,
+               max_nodes: Optional[int] = None, metadata: Optional[Dict[str, Any]] = None,
+               request_timeout: Optional[float] = None) -> TaskAsyncResponse:
+        """Submit a SAM task and return immediately. Use get() or stream() for results."""
+        data = self._http.request("POST", "/v1/sam/tasks/async",
+            json_body=_submit_body(task, model, priority, max_nodes, metadata),
+            timeout=request_timeout)
+        return TaskAsyncResponse(id=data["id"], model=data.get("model", model),
+            status="running", created_at=data.get("created_at", ""))
+
+    def get(self, task_id: str, *, request_timeout: Optional[float] = None) -> TaskResponse:
+        """Poll a task for its current status and result."""
+        return _parse(self._http.request("GET", f"/v1/sam/tasks/{task_id}", timeout=request_timeout))
+
+    def stream(self, task_id: str, *, timeout: Optional[float] = None) -> SyncStreamContext:
+        """Stream execution events for a task. Returns a context manager."""
+        return SyncStreamContext(self._http, task_id, timeout=timeout)
+
+    def list_models(self) -> List[Model]:
+        """List all available SAM models."""
+        data = self._http.request("GET", "/v1/sam/models")
+        return [Model(id=m["id"], name=m["name"], description=m["description"],
+                      max_nodes=m.get("max_nodes", 10)) for m in data.get("models", [])]
+
+class AsyncTasks:
+    """Async tasks resource. Access via async_client.tasks."""
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, task: str, *, model: str = _DEFAULT_MODEL, priority: str = _DEFAULT_PRIORITY,
+                     max_nodes: Optional[int] = None, timeout: int = _DEFAULT_TIMEOUT,
+                     metadata: Optional[Dict[str, Any]] = None, request_timeout: Optional[float] = None) -> TaskResponse:
+        """Async version of Tasks.create()."""
+        data = await self._http.request("POST", "/v1/sam/tasks",
+            json_body=_create_body(task, model, priority, max_nodes, timeout, metadata),
+            timeout=request_timeout)
+        resp = _parse(data)
+        if resp.status == "running": raise TaskTimeoutError(resp.id, timeout)
+        if resp.status == "failed": raise TaskFailedError(resp.id, resp.error)
+        return resp
+
+    async def submit(self, task: str, *, model: str = _DEFAULT_MODEL, priority: str = _DEFAULT_PRIORITY,
+                     max_nodes: Optional[int] = None, metadata: Optional[Dict[str, Any]] = None,
+                     request_timeout: Optional[float] = None) -> TaskAsyncResponse:
+        """Async version of Tasks.submit()."""
+        data = await self._http.request("POST", "/v1/sam/tasks/async",
+            json_body=_submit_body(task, model, priority, max_nodes, metadata),
+            timeout=request_timeout)
+        return TaskAsyncResponse(id=data["id"], model=data.get("model", model),
+            status="running", created_at=data.get("created_at", ""))
+
+    async def get(self, task_id: str, *, request_timeout: Optional[float] = None) -> TaskResponse:
+        """Async version of Tasks.get()."""
+        return _parse(await self._http.request("GET", f"/v1/sam/tasks/{task_id}", timeout=request_timeout))
+
+    def stream(self, task_id: str, *, timeout: Optional[float] = None) -> AsyncStreamContext:
+        """Async version of Tasks.stream()."""
+        return AsyncStreamContext(self._http, task_id, timeout=timeout)
+
+    async def list_models(self) -> List[Model]:
+        """List all available SAM models."""
+        data = await self._http.request("GET", "/v1/sam/models")
+        return [Model(id=m["id"], name=m["name"], description=m["description"],
+                      max_nodes=m.get("max_nodes", 10)) for m in data.get("models", [])]

qubac-1.0.0/qubac/types/__init__.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Optional
+
+__all__ = ["TaskResponse", "TaskAsyncResponse", "StreamEvent", "Model"]
+
+TaskStatus = Literal["completed", "failed", "running", "cancelled"]
+StreamEventType = Literal[
+    "task.created", "task.planned", "node.started", "node.completed",
+    "node.failed", "task.completed", "task.failed", "task.update", "stream.end",
+]
+
+@dataclass(frozen=True)
+class TaskResponse:
+    """Response from client.tasks.create() or client.tasks.get()."""
+    id: str
+    model: str
+    status: TaskStatus
+    output: Optional[str]
+    nodes_used: int
+    execution_ms: Optional[int]
+    created_at: str
+    metadata: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+    def __repr__(self) -> str:
+        preview = (self.output or "")[:60]
+        if len(self.output or "") > 60:
+            preview += "..."
+        return f"TaskResponse(id={self.id!r}, status={self.status!r}, output={preview!r})"
+
+@dataclass(frozen=True)
+class TaskAsyncResponse:
+    """Response from client.tasks.submit() — task accepted, not yet complete."""
+    id: str
+    model: str
+    status: TaskStatus
+    created_at: str
+
+@dataclass(frozen=True)
+class StreamEvent:
+    """A single event from a streaming task execution."""
+    type: StreamEventType
+    task_id: str
+    summary: str = ""
+    timestamp: Optional[str] = None
+    node: Optional[str] = None
+    output: Optional[str] = None
+    nodes_used: Optional[int] = None
+    error: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        if self.type == "task.completed":
+            return f"StreamEvent(type='task.completed', output={str(self.output or '')[:50]!r})"
+        if self.type in ("node.started", "node.completed", "node.failed"):
+            return f"StreamEvent(type={self.type!r}, node={self.node!r})"
+        return f"StreamEvent(type={self.type!r}, summary={self.summary[:40]!r})"
+
+@dataclass(frozen=True)
+class Model:
+    """A SAM model available for task execution."""
+    id: str
+    name: str
+    description: str
+    max_nodes: int
+
+    def __repr__(self) -> str:
+        return f"Model(id={self.id!r}, name={self.name!r})"

qubac-1.0.0/tests/test_client.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+import json, pytest, respx, httpx
+from typing import Any, Dict
+import qubac
+from qubac import (
+    Client, AsyncClient, TaskResponse, TaskAsyncResponse, StreamEvent,
+    AuthenticationError, RateLimitError, TaskTimeoutError, TaskFailedError, NotFoundError,
+)
+
+BASE = "https://api.qubac.com"
+KEY  = "sk-test"
+
+DONE: Dict[str, Any] = {
+    "id": "tsk_abc123def456789012345678901234",
+    "model": "sam-1", "status": "completed",
+    "output": "The speed of light is 299,792,458 m/s.",
+    "nodes_used": 1, "execution_ms": 3200,
+    "created_at": "2026-04-29T00:00:00Z", "metadata": None, "error": None,
+}
+FAIL: Dict[str, Any] = {**DONE, "status": "failed", "output": None, "error": "Task failed."}
+RUN:  Dict[str, Any] = {**DONE, "status": "running", "output": None, "execution_ms": None}
+ASYNC_R: Dict[str, Any] = {"id": "tsk_asyncid123456789012345678", "model": "sam-1",
+                            "status": "running", "created_at": "2026-04-29T00:00:00Z"}
+MODELS: Dict[str, Any] = {"models": [
+    {"id": "sam-1", "name": "SAM 1", "description": "Default", "max_nodes": 10},
+    {"id": "sam-1-fast", "name": "SAM 1 Fast", "description": "Fast", "max_nodes": 5},
+    {"id": "sam-1-pro",  "name": "SAM 1 Pro",  "description": "Pro",  "max_nodes": 20},
+], "default": "sam-1"}
+
+class TestClient:
+    def test_requires_api_key(self):
+        with pytest.raises(AuthenticationError): Client()
+
+    def test_env_variable(self, monkeypatch):
+        monkeypatch.setenv("QUBAC_API_KEY", "sk-env")
+        c = Client(); assert c._http._api_key == "sk-env"; c.close()
+
+    def test_repr(self):
+        c = Client(api_key=KEY, base_url=BASE)
+        assert "qubac.Client" in repr(c); c.close()
+
+    def test_context_manager(self):
+        with Client(api_key=KEY, base_url=BASE) as c:
+            assert c._http is not None
+
+    @respx.mock
+    def test_create_success(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json=DONE))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            r = c.tasks.create(model="sam-1", task="test")
+        assert isinstance(r, TaskResponse)
+        assert r.status == "completed"
+        assert r.output == "The speed of light is 299,792,458 m/s."
+        assert r.nodes_used == 1
+
+    @respx.mock
+    def test_create_raises_failed(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json=FAIL))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            with pytest.raises(TaskFailedError) as e:
+                c.tasks.create(model="sam-1", task="test")
+        assert e.value.task_id == FAIL["id"]
+
+    @respx.mock
+    def test_create_raises_timeout(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json=RUN))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            with pytest.raises(TaskTimeoutError) as e:
+                c.tasks.create(model="sam-1", task="test", timeout=30)
+        assert e.value.timeout == 30
+
+    @respx.mock
+    def test_submit(self):
+        respx.post(f"{BASE}/v1/sam/tasks/async").mock(return_value=httpx.Response(200, json=ASYNC_R))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            r = c.tasks.submit(model="sam-1", task="test")
+        assert isinstance(r, TaskAsyncResponse)
+        assert r.status == "running"
+
+    @respx.mock
+    def test_get(self):
+        respx.get(f"{BASE}/v1/sam/tasks/{DONE['id']}").mock(return_value=httpx.Response(200, json=DONE))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            r = c.tasks.get(DONE["id"])
+        assert r.status == "completed"
+
+    @respx.mock
+    def test_list_models(self):
+        respx.get(f"{BASE}/v1/sam/models").mock(return_value=httpx.Response(200, json=MODELS))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            models = c.tasks.list_models()
+        assert len(models) == 3
+        assert models[0].id == "sam-1"
+
+    @respx.mock
+    def test_with_options(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json=DONE))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            r = c.with_options(timeout=60).tasks.create(model="sam-1", task="test")
+        assert r.status == "completed"
+
+class TestErrors:
+    @respx.mock
+    def test_auth_error(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(401, json={"detail": "Invalid key"}))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            with pytest.raises(AuthenticationError) as e: c.tasks.create(model="sam-1", task="test")
+        assert e.value.status_code == 401
+
+    @respx.mock
+    def test_rate_limit(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(
+            return_value=httpx.Response(429, json={"detail": "Exhausted", "reset_at": "2026-04-30T00:00:00Z"}))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            with pytest.raises(RateLimitError) as e: c.tasks.create(model="sam-1", task="test")
+        assert e.value.reset_at == "2026-04-30T00:00:00Z"
+
+    @respx.mock
+    def test_retries_on_500(self):
+        calls = 0
+        def handler(req):
+            nonlocal calls; calls += 1
+            return httpx.Response(200, json=DONE) if calls >= 3 else httpx.Response(500, json={"detail": "err"})
+        respx.post(f"{BASE}/v1/sam/tasks").mock(side_effect=handler)
+        with Client(api_key=KEY, base_url=BASE, max_retries=2) as c:
+            r = c.tasks.create(model="sam-1", task="test")
+        assert r.status == "completed"
+        assert calls == 3
+
+    @respx.mock
+    def test_metadata_passthrough(self):
+        meta = {"user_id": "u1", "source": "test"}
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json={**DONE, "metadata": meta}))
+        with Client(api_key=KEY, base_url=BASE) as c:
+            r = c.tasks.create(model="sam-1", task="test", metadata=meta)
+        assert r.metadata == meta
+
+class TestAsync:
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_create(self):
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json=DONE))
+        async with AsyncClient(api_key=KEY, base_url=BASE) as c:
+            r = await c.tasks.create(model="sam-1", task="test")
+        assert r.status == "completed"
+
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_parallel(self):
+        import asyncio
+        respx.post(f"{BASE}/v1/sam/tasks").mock(return_value=httpx.Response(200, json=DONE))
+        async with AsyncClient(api_key=KEY, base_url=BASE) as c:
+            results = await asyncio.gather(
+                c.tasks.create(model="sam-1", task="t1"),
+                c.tasks.create(model="sam-1", task="t2"),
+                c.tasks.create(model="sam-1", task="t3"),
+            )
+        assert all(r.status == "completed" for r in results)
+
+class TestStreaming:
+    @respx.mock
+    def test_stream(self):
+        task_id = "tsk_streamtest1234567890123456"
+        evts = [
+            {"type": "task.created",   "task_id": task_id, "summary": "Received"},
+            {"type": "task.planned",   "task_id": task_id, "summary": "Planned"},
+            {"type": "node.started",   "task_id": task_id, "summary": "", "node": "Direct response"},
+            {"type": "node.completed", "task_id": task_id, "summary": "", "node": "Direct response"},
+            {"type": "task.completed", "task_id": task_id, "summary": "", "output": "42", "nodes_used": 1},
+            {"type": "stream.end",     "task_id": task_id, "summary": ""},
+        ]
+        body = "\n".join(f"data: {json.dumps(e)}\n" for e in evts)
+        respx.get(f"{BASE}/v1/sam/tasks/{task_id}/stream").mock(
+            return_value=httpx.Response(200, text=body, headers={"content-type": "text/event-stream"}))
+        with qubac.Client(api_key=KEY, base_url=BASE) as c:
+            received = []
+            with c.tasks.stream(task_id) as s:
+                for e in s: received.append(e)
+            assert received[-1].type == "task.completed"
+            assert received[-1].output == "42"
+            assert s.final_response is not None
+            assert s.final_response.status == "completed"
+
+class TestTypes:
+    def test_frozen(self):
+        r = TaskResponse(id="tsk_x", model="sam-1", status="completed",
+                         output="hi", nodes_used=1, execution_ms=100, created_at="")
+        with pytest.raises(Exception): r.output = "changed"  # type: ignore
+
+    def test_repr(self):
+        r = TaskResponse(id="tsk_x", model="sam-1", status="completed",
+                         output="hello world", nodes_used=1, execution_ms=100, created_at="")
+        assert "TaskResponse" in repr(r) and "completed" in repr(r)
+
+    def test_version(self):
+        assert qubac.__version__ == "1.0.0"