> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hawkings.education/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutor chat

> Per-activity grounded chat. Threads, messages, streaming.

The tutor sub-API is `client.activities.tutor.*`. See
[Build an AI tutor](/guides/build-an-ai-tutor) for a full walkthrough.

## Start a thread

<CodeGroup>
  ```ts TypeScript theme={null}
  const thread = await hk.activities.tutor.start({
    activity_id: "act_123",
    student_id: "usr_42",
    research_id: "res_...",   // optional
  });
  ```

  ```php PHP theme={null}
  $thread = $hk->activities->tutor->start([
      'activity_id' => 'act_123',
      'student_id' => 'usr_42',
      'research_id' => 'res_...',   // optional
  ]);
  ```
</CodeGroup>

Returns:

```json theme={null}
{
  "id": "thr_01HX9...",
  "object": "tutor_thread",
  "activity_id": "act_123",
  "student_id": "usr_42",
  "created_at": "2026-05-10T12:00:00Z"
}
```

## Send a message

Non-streaming:

<CodeGroup>
  ```ts TypeScript theme={null}
  const reply = await hk.activities.tutor.send(thread.id, {
    message: "Why does time dilate at high speeds?",
  });
  // reply.text, reply.citations
  ```

  ```php PHP theme={null}
  $reply = $hk->activities->tutor->send($thread->id, [
      'message' => 'Why does time dilate at high speeds?',
  ]);
  // $reply->text, $reply->citations
  ```
</CodeGroup>

Streaming:

<CodeGroup>
  ```ts TypeScript theme={null}
  const stream = hk.activities.tutor.sendStream(thread.id, { message });
  for await (const chunk of stream) {
    process.stdout.write(chunk.text_delta);
  }
  ```

  ```php PHP theme={null}
  $stream = $hk->activities->tutor->sendStream($thread->id, ['message' => $message]);
  foreach ($stream as $chunk) {
      echo $chunk->text_delta;
  }
  ```
</CodeGroup>

## Read history

<CodeGroup>
  ```ts TypeScript theme={null}
  const history = await hk.activities.tutor.history("act_123", {
    student_id: "usr_42",
  });
  // history.messages: [{ role, text, citations, created_at }, ...]
  ```

  ```php PHP theme={null}
  $history = $hk->activities->tutor->history('act_123', [
      'student_id' => 'usr_42',
  ]);
  // $history->messages: [{ role, text, citations, created_at }, ...]
  ```
</CodeGroup>

## Message object

```json theme={null}
{
  "id": "msg_01HX9...",
  "thread_id": "thr_01HX9...",
  "role": "assistant" | "user",
  "text": "...",
  "citations": [
    { "lesson_id": "lsn_...", "anchor": "p:14", "snippet": "..." }
  ],
  "created_at": "2026-05-10T12:34:56Z"
}
```