tasksmind 0.1.0__tar.gz

tasksmind-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+supabase/.env
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.env
+.env.local
+# Python
+__pycache__/
+*.pyc
+.modal.toml

tasksmind-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: tasksmind
+Version: 0.1.0
+Summary: TasksMind Python SDK — The AI Engineer for Developers on Call.
+Project-URL: Homepage, https://tasksmind.com
+Project-URL: Documentation, https://docs.tasksmind.com
+Project-URL: Repository, https://github.com/tasksmind/tasksmind-python
+Project-URL: Bug Tracker, https://github.com/tasksmind/tasksmind-python/issues
+Author-email: TasksMind <support@tasksmind.com>
+License: MIT
+Keywords: ai,automation,devops,oncall,tasksmind
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# TasksMind Python SDK
+
+The official Python client for the [TasksMind API](https://tasksmind.com) — The AI Engineer for Developers on Call.
+
+## Installation
+
+```bash
+pip install tasksmind
+```
+
+## Quick Start
+
+```python
+import os
+from tasksmind import TasksMind
+
+client = TasksMind(api_key=os.environ["TASKSMIND_API_KEY"])
+
+# Kick off a PR review
+run = client.runs.create(
+    repo_url="https://github.com/my-org/my-repo",
+    repo_ref="main",
+    payload={
+        "intent": "review_pr",
+        "target": {"pr_number": 42},
+    },
+)
+print(f"Run started: {run.id}")
+
+# Poll until complete (up to 10 minutes)
+result = client.runs.wait(run.id, timeout_s=600)
+if result.is_success():
+    print(result.output)
+else:
+    print(f"Run failed with status: {result.status}")
+```
+
+## Configuration
+
+| Parameter | Env variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `TASKSMIND_API_KEY` | — (required) |
+| `base_url` | `TASKSMIND_API_BASE_URL` | `https://api.tasksmind.com` |
+| `timeout` | — | `60` seconds |
+
+## Available Resources
+
+### `client.runs`
+
+| Method | Description |
+|--------|-------------|
+| `runs.create(repo_url, repo_ref, payload)` | Create a new run |
+| `runs.get(run_id)` | Fetch a run by ID |
+| `runs.list(limit, offset, status)` | List runs |
+| `runs.wait(run_id, timeout_s, poll_s, terminal_statuses)` | Poll until terminal status |
+
+### `Run` object
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `.id` | `str` | Run UUID |
+| `.status` | `str` | Current status (`running`, `completed`, `failed`, etc.) |
+| `.output` | `str` | Output text from the run |
+| `.summary` | `str \| None` | Short summary |
+| `.pr_url` | `str \| None` | Pull request URL if one was created |
+| `.pr_number` | `int \| None` | Pull request number |
+| `.is_success()` | `bool` | `True` when status is `completed` or `succeeded` |
+
+## Error Handling
+
+```python
+from tasksmind.exceptions import AuthError, NotFoundError, APIError, TimeoutError
+
+try:
+    result = client.runs.wait(run_id, timeout_s=120)
+except TimeoutError:
+    print("Run did not finish in time")
+except AuthError:
+    print("Invalid API key")
+except APIError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Context Manager
+
+```python
+with TasksMind() as client:
+    run = client.runs.create(repo_url="https://github.com/org/repo")
+```
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.24`
+
+## Links
+
+- [Website](https://tasksmind.com)
+- [Documentation](https://docs.tasksmind.com)
+- [GitHub](https://github.com/tasksmind/tasksmind-python)

tasksmind-0.1.0/README.md

@@ -0,0 +1,100 @@
+# TasksMind Python SDK
+
+The official Python client for the [TasksMind API](https://tasksmind.com) — The AI Engineer for Developers on Call.
+
+## Installation
+
+```bash
+pip install tasksmind
+```
+
+## Quick Start
+
+```python
+import os
+from tasksmind import TasksMind
+
+client = TasksMind(api_key=os.environ["TASKSMIND_API_KEY"])
+
+# Kick off a PR review
+run = client.runs.create(
+    repo_url="https://github.com/my-org/my-repo",
+    repo_ref="main",
+    payload={
+        "intent": "review_pr",
+        "target": {"pr_number": 42},
+    },
+)
+print(f"Run started: {run.id}")
+
+# Poll until complete (up to 10 minutes)
+result = client.runs.wait(run.id, timeout_s=600)
+if result.is_success():
+    print(result.output)
+else:
+    print(f"Run failed with status: {result.status}")
+```
+
+## Configuration
+
+| Parameter | Env variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `TASKSMIND_API_KEY` | — (required) |
+| `base_url` | `TASKSMIND_API_BASE_URL` | `https://api.tasksmind.com` |
+| `timeout` | — | `60` seconds |
+
+## Available Resources
+
+### `client.runs`
+
+| Method | Description |
+|--------|-------------|
+| `runs.create(repo_url, repo_ref, payload)` | Create a new run |
+| `runs.get(run_id)` | Fetch a run by ID |
+| `runs.list(limit, offset, status)` | List runs |
+| `runs.wait(run_id, timeout_s, poll_s, terminal_statuses)` | Poll until terminal status |
+
+### `Run` object
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `.id` | `str` | Run UUID |
+| `.status` | `str` | Current status (`running`, `completed`, `failed`, etc.) |
+| `.output` | `str` | Output text from the run |
+| `.summary` | `str \| None` | Short summary |
+| `.pr_url` | `str \| None` | Pull request URL if one was created |
+| `.pr_number` | `int \| None` | Pull request number |
+| `.is_success()` | `bool` | `True` when status is `completed` or `succeeded` |
+
+## Error Handling
+
+```python
+from tasksmind.exceptions import AuthError, NotFoundError, APIError, TimeoutError
+
+try:
+    result = client.runs.wait(run_id, timeout_s=120)
+except TimeoutError:
+    print("Run did not finish in time")
+except AuthError:
+    print("Invalid API key")
+except APIError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Context Manager
+
+```python
+with TasksMind() as client:
+    run = client.runs.create(repo_url="https://github.com/org/repo")
+```
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.24`
+
+## Links
+
+- [Website](https://tasksmind.com)
+- [Documentation](https://docs.tasksmind.com)
+- [GitHub](https://github.com/tasksmind/tasksmind-python)

tasksmind-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tasksmind"
+version = "0.1.0"
+description = "TasksMind Python SDK — The AI Engineer for Developers on Call."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "TasksMind", email = "support@tasksmind.com" }]
+keywords = ["tasksmind", "ai", "devops", "oncall", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://tasksmind.com"
+Documentation = "https://docs.tasksmind.com"
+Repository = "https://github.com/tasksmind/tasksmind-python"
+"Bug Tracker" = "https://github.com/tasksmind/tasksmind-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tasksmind"]

tasksmind-0.1.0/tasksmind/__init__.py

@@ -0,0 +1,96 @@
+"""
+TasksMind Python SDK
+====================
+
+The AI Engineer for Developers on Call.
+
+Quick start::
+
+    import os
+    from tasksmind import TasksMind
+
+    client = TasksMind(api_key=os.environ["TASKSMIND_API_KEY"])
+
+    # Create a run
+    run = client.runs.create(
+        repo_url="https://github.com/my-org/my-repo",
+        repo_ref="main",
+        payload={"intent": "review_pr", "target": {"pr_number": 42}},
+    )
+
+    # Wait for it to finish
+    result = client.runs.wait(run.id, timeout_s=600)
+    if result.is_success():
+        print(result.output)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._http import HTTPClient, _DEFAULT_BASE_URL, _DEFAULT_TIMEOUT
+from .exceptions import APIError, AuthError, NotFoundError, RateLimitError, TasksMindError, TimeoutError
+from .resources import Run, RunsResource
+
+__version__ = "0.1.0"
+__all__ = [
+    "TasksMind",
+    "Run",
+    # Exceptions
+    "TasksMindError",
+    "AuthError",
+    "NotFoundError",
+    "APIError",
+    "RateLimitError",
+    "TimeoutError",
+]
+
+
+class TasksMind:
+    """
+    TasksMind API client.
+
+    Args:
+        api_key: Your TasksMind API key. Falls back to the ``TASKSMIND_API_KEY``
+            environment variable when not provided.
+        base_url: Override the API base URL. Defaults to ``https://api.tasksmind.com``.
+            Can also be set via the ``TASKSMIND_API_BASE_URL`` environment variable.
+        timeout: HTTP request timeout in seconds (default: 60).
+
+    Raises:
+        :exc:`ValueError`: If no API key is provided and ``TASKSMIND_API_KEY`` is not set.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("TASKSMIND_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= or set the TASKSMIND_API_KEY environment variable."
+            )
+        resolved_base = (
+            base_url
+            or os.environ.get("TASKSMIND_API_BASE_URL", "")
+            or _DEFAULT_BASE_URL
+        )
+        self._http = HTTPClient(api_key=resolved_key, base_url=resolved_base, timeout=timeout)
+        self.runs = RunsResource(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "TasksMind":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"TasksMind(base_url={self._http._base_url!r})"

tasksmind-0.1.0/tasksmind/_http.py

@@ -0,0 +1,62 @@
+"""Internal HTTP client for the TasksMind SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .exceptions import APIError, AuthError, NotFoundError, RateLimitError
+
+_DEFAULT_BASE_URL = "https://api.tasksmind.com"
+_DEFAULT_TIMEOUT = 60.0
+
+
+class HTTPClient:
+    """Thin wrapper around ``httpx.Client`` that handles auth and error mapping."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        if resp.is_success:
+            return
+        body = resp.text[:2000]
+        code = resp.status_code
+        if code in (401, 403):
+            raise AuthError(f"Authentication failed (HTTP {code})", status_code=code, body=body)
+        if code == 404:
+            raise NotFoundError(f"Resource not found (HTTP 404)", status_code=code, body=body)
+        if code == 429:
+            raise RateLimitError(f"Rate limit exceeded (HTTP 429)", status_code=code, body=body)
+        raise APIError(f"API error (HTTP {code}): {body}", status_code=code, body=body)
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        url = self._base_url + path
+        resp = self._client.get(url, headers=self._headers(), params=params)
+        self._raise_for_status(resp)
+        return resp.json() if resp.text else {}
+
+    def post(self, path: str, body: Any = None) -> Any:
+        url = self._base_url + path
+        resp = self._client.post(url, headers=self._headers(), json=body)
+        self._raise_for_status(resp)
+        return resp.json() if resp.text else {}
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HTTPClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

tasksmind-0.1.0/tasksmind/exceptions.py

@@ -0,0 +1,35 @@
+"""TasksMind SDK exceptions."""
+
+from __future__ import annotations
+
+
+class TasksMindError(Exception):
+    """Base exception for all TasksMind SDK errors."""
+
+    def __init__(self, message: str, status_code: int = 0, body: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self!s}, status_code={self.status_code})"
+
+
+class AuthError(TasksMindError):
+    """Raised when the API key is missing, invalid, or expired (HTTP 401/403)."""
+
+
+class NotFoundError(TasksMindError):
+    """Raised when the requested resource does not exist (HTTP 404)."""
+
+
+class RateLimitError(TasksMindError):
+    """Raised when the API rate limit is exceeded (HTTP 429)."""
+
+
+class APIError(TasksMindError):
+    """Raised for all other API-level errors (HTTP 4xx/5xx)."""
+
+
+class TimeoutError(TasksMindError):
+    """Raised when a polling call (e.g. runs.wait) exceeds its timeout."""

tasksmind-0.1.0/tasksmind/resources/__init__.py

@@ -0,0 +1,3 @@
+from .runs import Run, RunsResource
+
+__all__ = ["Run", "RunsResource"]

tasksmind-0.1.0/tasksmind/resources/runs.py

@@ -0,0 +1,171 @@
+"""TasksMind runs resource."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from .._http import HTTPClient
+
+
+class Run:
+    """Represents a TasksMind run."""
+
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        return self._data.get("id", "")
+
+    @property
+    def status(self) -> str:
+        return self._data.get("status", "unknown")
+
+    @property
+    def output(self) -> str:
+        return self._data.get("output") or ""
+
+    @property
+    def pr_url(self) -> Optional[str]:
+        return self._data.get("pr_url")
+
+    @property
+    def pr_number(self) -> Optional[int]:
+        return self._data.get("pr_number")
+
+    @property
+    def summary(self) -> Optional[str]:
+        return self._data.get("summary")
+
+    @property
+    def error(self) -> Optional[str]:
+        return self._data.get("error")
+
+    def is_success(self) -> bool:
+        return self.status in ("completed", "succeeded")
+
+    def __repr__(self) -> str:
+        return f"Run(id={self.id!r}, status={self.status!r})"
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+
+class RunsResource:
+    """CRUD and polling for TasksMind runs."""
+
+    def __init__(self, http: "HTTPClient") -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        repo_url: str,
+        repo_ref: str = "main",
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Run:
+        """
+        Create a new run.
+
+        Args:
+            repo_url: Full GitHub repository URL (e.g. ``https://github.com/org/repo``).
+            repo_ref: Branch, tag, or commit SHA to target (default: ``"main"``).
+            payload: Arbitrary key/value context forwarded to the run (intent, target, etc.).
+
+        Returns:
+            A :class:`Run` object with at minimum an ``id`` attribute.
+        """
+        body: Dict[str, Any] = {
+            "repo_url": repo_url,
+            "repo_ref": repo_ref,
+        }
+        if payload:
+            body["payload"] = payload
+        data = self._http.post("/v1/runs", body)
+        return Run(data)
+
+    def get(self, run_id: str) -> Run:
+        """
+        Fetch an existing run by its ID.
+
+        Args:
+            run_id: The UUID of the run.
+
+        Returns:
+            A :class:`Run` object.
+
+        Raises:
+            :exc:`~tasksmind.exceptions.NotFoundError`: If the run does not exist.
+        """
+        data = self._http.get(f"/v1/runs/{run_id}")
+        return Run(data)
+
+    def list(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        status: Optional[str] = None,
+    ) -> List[Run]:
+        """
+        List runs for the authenticated account.
+
+        Args:
+            limit: Maximum number of runs to return (default: 20).
+            offset: Pagination offset (default: 0).
+            status: Optional status filter (e.g. ``"completed"``, ``"running"``).
+
+        Returns:
+            A list of :class:`Run` objects.
+        """
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        data = self._http.get("/v1/runs", params=params)
+        return [Run(r) for r in (data.get("runs") or data if isinstance(data, list) else [])]
+
+    def wait(
+        self,
+        run_id: str,
+        *,
+        timeout_s: float = 600.0,
+        poll_s: float = 2.0,
+        terminal_statuses: Optional[List[str]] = None,
+    ) -> Run:
+        """
+        Poll a run until it reaches a terminal status or the timeout expires.
+
+        Args:
+            run_id: The UUID of the run to poll.
+            timeout_s: Maximum seconds to wait before raising :exc:`~tasksmind.exceptions.TimeoutError`.
+            poll_s: Seconds between each poll request (default: 2).
+            terminal_statuses: Status strings that stop polling. Defaults to
+                ``["completed", "succeeded", "failed", "error", "cancelled"]``.
+
+        Returns:
+            The final :class:`Run` object.
+
+        Raises:
+            :exc:`~tasksmind.exceptions.TimeoutError`: If the run does not finish within ``timeout_s``.
+        """
+        from ..exceptions import TimeoutError as TasksMindTimeoutError
+
+        if terminal_statuses is None:
+            terminal_statuses = ["completed", "succeeded", "failed", "error", "cancelled"]
+
+        deadline = time.monotonic() + timeout_s
+        while True:
+            run = self.get(run_id)
+            if run.status in terminal_statuses:
+                return run
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TasksMindTimeoutError(
+                    f"Run {run_id!r} did not complete within {timeout_s}s (last status: {run.status!r})"
+                )
+            time.sleep(min(poll_s, remaining))