mytutor-sdk 0.1.0__py3-none-any.whl

mytutor/__init__.py

@@ -0,0 +1,26 @@
+from .client import MyTutor
+from .errors import MyTutorError, TutorAskError
+from .types import (
+    Session,
+    Subject,
+    TeachingMode,
+    Topic,
+    TutorAskResult,
+    TutorMessage,
+    TutorResponse,
+    Whiteboard,
+)
+
+__all__ = [
+    "MyTutor",
+    "MyTutorError",
+    "Session",
+    "Subject",
+    "TeachingMode",
+    "Topic",
+    "TutorAskError",
+    "TutorAskResult",
+    "TutorMessage",
+    "TutorResponse",
+    "Whiteboard",
+]

mytutor/client.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlsplit
+from urllib.request import Request, urlopen
+
+from .errors import MyTutorError, TutorAskError
+from .types import (
+    Session,
+    Subject,
+    TeachingMode,
+    TutorAskResult,
+    TutorResponse,
+)
+
+DEFAULT_BASE_URL = "https://api.mytutor.site"
+DEFAULT_TIMEOUT = 120.0
+TEACHING_MODES = {"guided", "explain", "practice", "check_my_work"}
+
+
+def _validate_text(value: str, name: str, maximum: int | None = None) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty string.")
+    if maximum is not None and len(value) > maximum:
+        raise ValueError(f"{name} must be {maximum} characters or fewer.")
+
+
+def _normalize_base_url(value: str) -> str:
+    try:
+        parsed = urlsplit(value)
+        hostname = parsed.hostname
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("base_url must be an absolute HTTP(S) API origin.") from exc
+
+    is_loopback = hostname in {"localhost", "127.0.0.1", "::1"}
+    if (
+        parsed.scheme not in {"https", "http"}
+        or not hostname
+        or (parsed.scheme == "http" and not is_loopback)
+        or parsed.username
+        or parsed.password
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            "base_url must be an HTTPS API origin without credentials, path, query, or fragment."
+        )
+
+    netloc = hostname if port is None else f"{hostname}:{port}"
+    if ":" in hostname and not hostname.startswith("["):
+        netloc = f"[{hostname}]" if port is None else f"[{hostname}]:{port}"
+    return f"{parsed.scheme}://{netloc}"
+
+
+def _api_error(status: int, payload: Any) -> MyTutorError:
+    envelope = payload if isinstance(payload, dict) else {}
+    error = envelope.get("error")
+    if not isinstance(error, dict):
+        error = {}
+    message = error.get("message")
+    code = error.get("code")
+    correlation_id = envelope.get("correlation_id")
+    return MyTutorError(
+        message if isinstance(message, str) else f"The My Tutor API request failed ({status}).",
+        status=status,
+        code=code if isinstance(code, str) else "http_error",
+        details=error.get("details"),
+        correlation_id=correlation_id if isinstance(correlation_id, str) else None,
+    )
+
+
+def _decode_response(status: int, raw: bytes) -> Any:
+    payload: Any = None
+    if raw:
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            if 200 <= status < 300 and status != 204:
+                raise MyTutorError(
+                    "The My Tutor API returned an invalid JSON response.",
+                    status=status,
+                    code="invalid_response",
+                ) from exc
+
+    if not 200 <= status < 300:
+        raise _api_error(status, payload)
+    if status == 204:
+        return None
+    if not raw:
+        raise MyTutorError(
+            "The My Tutor API returned an empty response.",
+            status=status,
+            code="invalid_response",
+        )
+    return payload
+
+
+class _Subjects:
+    def __init__(self, client: MyTutor) -> None:
+        self._client = client
+
+    def list(self) -> list[Subject]:
+        return self._client._request("GET", "/subjects")
+
+
+class _Tutor:
+    def __init__(self, client: MyTutor) -> None:
+        self._client = client
+
+    def create_session(
+        self,
+        *,
+        subject_slug: str,
+        topic: str = "",
+        teaching_mode: TeachingMode | None = None,
+        title: str | None = None,
+        assignment_question_id: str | None = None,
+        assignment_id: str | None = None,
+        education_level: str | None = None,
+    ) -> Session:
+        _validate_text(subject_slug, "subject_slug", 60)
+        normalized_topic = topic.strip() if isinstance(topic, str) else ""
+        if normalized_topic:
+            _validate_text(normalized_topic, "topic", 160)
+        if title is not None and len(title) > 160:
+            raise ValueError("title must be 160 characters or fewer.")
+        if education_level is not None and len(education_level) > 60:
+            raise ValueError("education_level must be 60 characters or fewer.")
+        if teaching_mode is not None and teaching_mode not in TEACHING_MODES:
+            raise ValueError("teaching_mode is not a supported tutoring mode.")
+
+        payload: dict[str, Any] = {"subject_slug": subject_slug, "topic": normalized_topic}
+        if teaching_mode is not None:
+            payload["teaching_mode"] = teaching_mode
+        if title is not None:
+            payload["title"] = title
+        if assignment_question_id is not None:
+            payload["assignment_question_id"] = assignment_question_id
+        if assignment_id is not None:
+            payload["assignment_id"] = assignment_id
+        if education_level is not None:
+            payload["education_level"] = education_level
+        return self._client._request("POST", "/tutoring/sessions", body=payload)
+
+    def send_message(
+        self,
+        *,
+        session_id: str,
+        content: str,
+        retry: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> TutorResponse:
+        _validate_text(session_id, "session_id")
+        _validate_text(content, "content", 4000)
+        if idempotency_key is not None:
+            _validate_text(idempotency_key, "idempotency_key", 120)
+
+        payload: dict[str, Any] = {"content": content}
+        if retry is not None:
+            payload["retry"] = retry
+        return self._client._request(
+            "POST",
+            f"/tutoring/sessions/{quote(session_id, safe='')}/messages",
+            body=payload,
+            idempotency_key=idempotency_key,
+        )
+
+    def ask(
+        self,
+        *,
+        question: str,
+        session_id: str | None = None,
+        subject_slug: str | None = None,
+        topic: str = "",
+        teaching_mode: TeachingMode | None = None,
+        idempotency_key: str | None = None,
+    ) -> TutorAskResult:
+        _validate_text(question, "question", 4000)
+        if (session_id is None) == (subject_slug is None):
+            raise ValueError("Provide exactly one of session_id or subject_slug.")
+        if idempotency_key is not None:
+            _validate_text(idempotency_key, "idempotency_key", 120)
+
+        if session_id is not None:
+            response = self.send_message(
+                session_id=session_id,
+                content=question,
+                idempotency_key=idempotency_key,
+            )
+            return {"session_id": session_id, "response": response}
+
+        if subject_slug is None:
+            raise ValueError("Provide a subject_slug to start a new tutoring session.")
+        session = self.create_session(
+            subject_slug=subject_slug,
+            topic=topic,
+            teaching_mode=teaching_mode,
+        )
+        try:
+            response = self.send_message(
+                session_id=session["id"],
+                content=question,
+                idempotency_key=idempotency_key,
+            )
+        except MyTutorError as exc:
+            raise TutorAskError(session["id"], exc) from exc
+        return {"session_id": session["id"], "response": response}
+
+
+class MyTutor:
+    """Synchronous client for the server-to-server My Tutor developer API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        _validate_text(api_key, "api_key")
+        if "\r" in api_key or "\n" in api_key:
+            raise ValueError("api_key must not contain newline characters.")
+        if not isinstance(timeout, (int, float)) or isinstance(timeout, bool):
+            raise TypeError("timeout must be a positive finite number of seconds.")
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be a positive finite number of seconds.")
+
+        self._api_key = api_key.strip()
+        self._base_url = _normalize_base_url(base_url)
+        self._timeout = float(timeout)
+        self.subjects = _Subjects(self)
+        self.tutor = _Tutor(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        request = Request(
+            f"{self._base_url}/api/v1{path}",
+            data=data,
+            headers=headers,
+            method=method,
+        )
+        try:
+            with urlopen(request, timeout=self._timeout) as response:
+                return _decode_response(response.status, response.read())
+        except HTTPError as exc:
+            try:
+                return _decode_response(exc.code, exc.read())
+            finally:
+                exc.close()
+        except TimeoutError as exc:
+            raise MyTutorError(
+                f"The My Tutor API request timed out after {self._timeout:g} seconds.",
+                status=None,
+                code="timeout",
+            ) from exc
+        except URLError as exc:
+            raise MyTutorError(
+                "The My Tutor API request could not be completed.",
+                status=None,
+                code="network_error",
+            ) from exc

mytutor/errors.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MyTutorError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None,
+        code: str,
+        details: Any = None,
+        correlation_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.details = details
+        self.correlation_id = correlation_id
+
+
+class TutorAskError(MyTutorError):
+    def __init__(self, session_id: str, cause: MyTutorError) -> None:
+        super().__init__(
+            "The tutoring session was created, but the question could not be completed. "
+            "Retry by sending the question to this session.",
+            status=cause.status,
+            code=cause.code,
+            details=cause.details,
+            correlation_id=cause.correlation_id,
+        )
+        self.session_id = session_id
+        self.cause = cause

mytutor/types.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+TeachingMode = Literal["guided", "explain", "practice", "check_my_work"]
+
+
+class Topic(TypedDict):
+    id: str
+    title: str
+    slug: str
+    curriculum_id: str
+
+
+class Subject(TypedDict):
+    id: str
+    slug: str
+    name: str
+    description: str
+    accent: str
+    topics: list[Topic]
+
+
+class Session(TypedDict):
+    id: str
+    title: str
+    subject_slug: str | None
+    subject_name: str | None
+    teaching_mode: TeachingMode
+    education_level: str
+    status: str
+    topic: str
+    assignment_id: str | None
+    assignment_filename: str
+    created_at: str
+    updated_at: str
+    last_message_at: str | None
+    message_count: int
+    preview: str
+
+
+class TutorMessage(TypedDict):
+    id: str
+    role: str
+    content: str
+    structured: dict[str, Any] | None
+    created_at: str
+
+
+class Whiteboard(TypedDict):
+    schema_version: int
+    title: str
+    subject: str
+    steps: list[dict[str, Any]]
+    annotations: list[dict[str, Any]]
+    updated_at: str | None
+    boards: list[dict[str, Any]]
+    active_board_id: str
+
+
+class TutorResponse(TypedDict):
+    message: TutorMessage
+    user_message: TutorMessage | None
+    steps: list[dict[str, Any]]
+    follow_up: str
+    check_question: str | None
+    topic: str
+    verification_summary: dict[str, int]
+    whiteboard: Whiteboard
+    prompt_version: str
+    model: str
+    credit_action: str
+    credits_charged: int
+    credits_available: int | None
+
+
+class TutorAskResult(TypedDict):
+    session_id: str
+    response: TutorResponse

mytutor_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: mytutor-sdk
+Version: 0.1.0
+Summary: Python client for the My Tutor developer API
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# My Tutor Python SDK
+
+The `mytutor-sdk` distribution provides a typed, synchronous Python client for
+the stable My Tutor developer API v1 endpoints: subjects, tutoring sessions,
+and tutor messages. It has no runtime dependencies.
+
+> **Preview:** This package is not published to PyPI yet. The source and local
+> package are available in this repository; `pip install mytutor-sdk` will work
+> after the first PyPI release. Publishing is intentionally not automated in
+> this repository.
+
+## Requirements
+
+- Python 3.11 or newer
+- A My Tutor developer API key
+- A trusted server environment; never put the secret key in browser or mobile
+  application code
+
+## Install from a local checkout
+
+```sh
+python -m pip install ./packages/sdk-python
+```
+
+After PyPI publication, install with:
+
+```sh
+python -m pip install mytutor-sdk
+```
+
+## Quick start
+
+Set `MYTUTOR_API_KEY` in your server environment. Supply a subject slug to
+start a session; keep the returned `session_id` to continue the conversation.
+
+```python
+import os
+
+from mytutor import MyTutor
+
+client = MyTutor(api_key=os.environ["MYTUTOR_API_KEY"])
+subjects = client.subjects.list()
+result = client.tutor.ask(
+    subject_slug=subjects[0]["slug"],
+    topic="Fractions",
+    question="Explain how to add fractions with different denominators.",
+)
+
+print(result["response"]["message"]["content"])
+
+next_turn = client.tutor.ask(
+    session_id=result["session_id"],
+    question="Can you show another example?",
+)
+```
+
+`tutor.ask` requires exactly one of `session_id` or `subject_slug`. A
+`subject_slug` creates a new tutoring session before sending the question. Use
+`client.tutor.create_session()` and `client.tutor.send_message()` separately
+when you need full control.
+
+## Errors and retries
+
+Catch `MyTutorError` to inspect the HTTP `status`, API `code`, optional
+`details`, and `correlation_id`. Requests are not retried automatically. For a
+retry of the same tutor message, pass the same `idempotency_key`.
+
+If a new-session `ask` creates the session but cannot complete the message, it
+raises `TutorAskError`, which includes `session_id` so the message can be
+retried against that session.
+
+## Configuration
+
+`base_url` defaults to `https://api.mytutor.site`. Override it with your
+deployment's HTTPS API origin when needed. Plain HTTP is permitted only for
+loopback development URLs. `timeout` defaults to 120 seconds and is expressed
+in seconds.

mytutor_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mytutor/__init__.py,sha256=qc29rL-uANq6m4fT9tm1ZYEHKrX_o2VWr44Fc-8BL_0,468
+mytutor/client.py,sha256=vyTS-77HzHH9zgtHLBoMMXut4UXZ4kIgccQ7roqQ_pc,10197
+mytutor/errors.py,sha256=FRV5uiRjHO4lb9NXqBVNdL8gIGYrmJVAB6TQ8d5ndj8,994
+mytutor/types.py,sha256=chxgMhKoSrXqFtYPuhiIByK6QHqi29fyPa_L9vZycXQ,1666
+mytutor_sdk-0.1.0.dist-info/METADATA,sha256=RHiAMdrKrwxgUYhvmvNHbUtk4WJ327isI3W4vYGDres,2669
+mytutor_sdk-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mytutor_sdk-0.1.0.dist-info/top_level.txt,sha256=U_Xqj1M6b8xOjWGcVBi85xImsWPk2fycEEOEevPu09M,8
+mytutor_sdk-0.1.0.dist-info/RECORD,,

mytutor_sdk-0.1.0.dist-info/WHEEL

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

mytutor_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mytutor