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.
