mytutor-sdk 0.1.0__tar.gz

mytutor_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,77 @@
+# 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/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mytutor-sdk"
+version = "0.1.0"
+description = "Python client for the My Tutor developer API"
+requires-python = ">=3.11"
+readme = "README.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

mytutor_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mytutor_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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/src/mytutor_sdk.egg-info/PKG-INFO

@@ -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/src/mytutor_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/mytutor/__init__.py
+src/mytutor/client.py
+src/mytutor/errors.py
+src/mytutor/types.py
+src/mytutor_sdk.egg-info/PKG-INFO
+src/mytutor_sdk.egg-info/SOURCES.txt
+src/mytutor_sdk.egg-info/dependency_links.txt
+src/mytutor_sdk.egg-info/top_level.txt
+tests/test_client.py

mytutor_sdk-0.1.0/src/mytutor_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mytutor_sdk-0.1.0/src/mytutor_sdk.egg-info/top_level.txt

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

mytutor_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import io
+import json
+import unittest
+from urllib.error import HTTPError
+from unittest.mock import patch
+
+from mytutor import MyTutor, MyTutorError, TutorAskError
+
+
+def tutor_response() -> dict:
+    return {
+        "message": {
+            "id": "message-1",
+            "role": "assistant",
+            "content": "Try a common denominator.",
+            "structured": None,
+            "created_at": "2026-01-01T00:00:00Z",
+        },
+        "user_message": None,
+        "steps": [],
+        "follow_up": "",
+        "check_question": None,
+        "topic": "Fractions",
+        "verification_summary": {},
+        "whiteboard": {
+            "schema_version": 1,
+            "title": "Fractions",
+            "subject": "Mathematics",
+            "steps": [],
+            "annotations": [],
+            "updated_at": None,
+            "boards": [],
+            "active_board_id": "",
+        },
+        "prompt_version": "test",
+        "model": "test",
+        "credit_action": "tutor_message",
+        "credits_charged": 1,
+        "credits_available": 9,
+    }
+
+
+class FakeResponse(io.BytesIO):
+    def __init__(self, payload: dict | list, status: int = 200) -> None:
+        super().__init__(json.dumps(payload).encode())
+        self.status = status
+
+
+class MyTutorClientTests(unittest.TestCase):
+    def test_lists_subjects_with_bearer_authentication(self) -> None:
+        client = MyTutor(api_key="mt_dev_test")
+        with patch("mytutor.client.urlopen", return_value=FakeResponse([])) as open_url:
+            self.assertEqual(client.subjects.list(), [])
+
+        request = open_url.call_args.args[0]
+        self.assertEqual(request.full_url, "https://api.mytutor.site/api/v1/subjects")
+        self.assertEqual(request.get_method(), "GET")
+        self.assertEqual(request.get_header("Authorization"), "Bearer mt_dev_test")
+
+    def test_ask_creates_a_session_and_sends_a_question(self) -> None:
+        client = MyTutor(api_key="mt_dev_test")
+        session = {"id": "session-1"}
+        with patch(
+            "mytutor.client.urlopen",
+            side_effect=[FakeResponse(session, 201), FakeResponse(tutor_response())],
+        ) as open_url:
+            result = client.tutor.ask(
+                subject_slug="mathematics",
+                topic="Fractions",
+                question="How do I add 1/2 and 1/3?",
+                idempotency_key="turn-1",
+            )
+
+        self.assertEqual(result["session_id"], "session-1")
+        self.assertEqual(result["response"]["message"]["content"], "Try a common denominator.")
+        self.assertEqual(open_url.call_count, 2)
+
+        create_request = open_url.call_args_list[0].args[0]
+        self.assertEqual(
+            create_request.full_url,
+            "https://api.mytutor.site/api/v1/tutoring/sessions",
+        )
+        self.assertEqual(
+            json.loads(create_request.data),
+            {"subject_slug": "mathematics", "topic": "Fractions"},
+        )
+
+        message_request = open_url.call_args_list[1].args[0]
+        self.assertEqual(
+            message_request.full_url,
+            "https://api.mytutor.site/api/v1/tutoring/sessions/session-1/messages",
+        )
+        self.assertEqual(message_request.get_header("Idempotency-key"), "turn-1")
+        self.assertEqual(
+            json.loads(message_request.data),
+            {"content": "How do I add 1/2 and 1/3?"},
+        )
+
+    def test_ask_continues_an_existing_session(self) -> None:
+        client = MyTutor(api_key="mt_dev_test")
+        with patch(
+            "mytutor.client.urlopen",
+            return_value=FakeResponse(tutor_response()),
+        ) as open_url:
+            result = client.tutor.ask(
+                session_id="session/with space",
+                question="Why do the denominators need to match?",
+            )
+
+        self.assertEqual(result["session_id"], "session/with space")
+        self.assertEqual(open_url.call_count, 1)
+        request = open_url.call_args.args[0]
+        self.assertTrue(request.full_url.endswith("session%2Fwith%20space/messages"))
+
+    def test_maps_api_errors_to_typed_error(self) -> None:
+        client = MyTutor(api_key="mt_dev_test")
+        error_body = {
+            "error": {
+                "code": "insufficient_credits",
+                "message": "Add credits before continuing.",
+                "details": {"available": 0},
+            },
+            "correlation_id": "request-123",
+        }
+        http_error = HTTPError(
+            "https://api.mytutor.site/api/v1/subjects",
+            402,
+            "Payment required",
+            {},
+            io.BytesIO(json.dumps(error_body).encode()),
+        )
+        with patch("mytutor.client.urlopen", side_effect=http_error):
+            with self.assertRaises(MyTutorError) as raised:
+                client.subjects.list()
+
+        self.assertEqual(raised.exception.status, 402)
+        self.assertEqual(raised.exception.code, "insufficient_credits")
+        self.assertEqual(raised.exception.correlation_id, "request-123")
+        self.assertEqual(raised.exception.details, {"available": 0})
+
+    def test_new_session_error_preserves_session_id(self) -> None:
+        client = MyTutor(api_key="mt_dev_test")
+        provider_error = HTTPError(
+            "https://api.mytutor.site/api/v1/tutoring/sessions/session-1/messages",
+            503,
+            "Unavailable",
+            {},
+            io.BytesIO(
+                json.dumps(
+                    {"error": {"code": "provider_unavailable", "message": "Try again later."}}
+                ).encode()
+            ),
+        )
+        with patch(
+            "mytutor.client.urlopen",
+            side_effect=[FakeResponse({"id": "session-1"}, 201), provider_error],
+        ):
+            with self.assertRaises(TutorAskError) as raised:
+                client.tutor.ask(subject_slug="mathematics", question="Explain fractions.")
+
+        self.assertEqual(raised.exception.session_id, "session-1")
+        self.assertEqual(raised.exception.code, "provider_unavailable")
+        self.assertIsInstance(raised.exception.cause, MyTutorError)
+
+    def test_ask_requires_exactly_one_context(self) -> None:
+        client = MyTutor(api_key="mt_dev_test")
+        with self.assertRaisesRegex(ValueError, "exactly one"):
+            client.tutor.ask(question="Explain fractions.")
+        with self.assertRaisesRegex(ValueError, "exactly one"):
+            client.tutor.ask(
+                question="Explain fractions.",
+                session_id="session-1",
+                subject_slug="mathematics",
+            )
+
+    def test_rejects_non_https_remote_api_origins(self) -> None:
+        with self.assertRaisesRegex(ValueError, "HTTPS API origin"):
+            MyTutor(api_key="mt_dev_test", base_url="http://api.mytutor.site")
+
+
+if __name__ == "__main__":
+    unittest.main()