> For the complete documentation index, see [llms.txt](https://gdplabs.gitbook.io/glchat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gdplabs.gitbook.io/glchat/developer-documentation/thinking-and-activity-contract.md).

# Thinking and Activity Contract

## Overview

This page defines the contract for Reasoning (Thinking) Events and Activity Events used in GLChat.

We distinguish between two fundamental types of events that provide transparency into how the AI operates: **Thinking Events** (reasoning) and **Activity Events** (actions).

### Thinking Events

Thinking events represent the AI's internal reasoning process - essentially, the "why" behind its decisions and actions. These events provide transparency into the AI's cognitive process as it works through problems.

#### Characteristics

* **Stream-based structure**: Thinking events are grouped into continuous streams that represent a complete reasoning chain. Multiple events share the same unique identifier to show they belong to the same thought process.
* **Sequential flow**: A typical thinking stream follows the pattern: `thinking_start` → one or more `thinking` events → `thinking_end`. All events in this sequence share the same ID.
* **Rich content**: Each thinking event contains the actual reasoning text

#### Event Types

* **thinking\_start**: Marks the beginning of a new reasoning stream.
* **thinking**: Contains the actual reasoning content.
* **thinking\_end**: Marks the completion of a reasoning stream

> ⚠️ Same thinking blocks should have same Id

#### Example

```json
  → thinking_start (id: "a1b2c3d4-...")
  → thinking: "I need to analyze the camera specifications from multiple sources..." (id: "a1b2c3d4-...")
  → thinking: "Comparing against competing models in the same price range..." (id: "a1b2c3d4-...")
  → thinking: "The primary differentiator appears to be the sensor size..." (id: "a1b2c3d4-...")
  → thinking_end (id: "a1b2c3d4-...")
```

> For more detailed structure and contract, go to next page

### Activity Events

Activity events represent discrete external actions or operations that the AI performs. These are the observable "what" - tangible operations like searching the web, opening pages, or extracting data.

#### Characteristics

* **Action-based structure**: Each activity represents a single, complete operation that the AI performs.
* **Stateless behavior**: Unlike thinking events, activities are independent. Each activity receives its own unique ID.
* **Discrete operations**: Activities don't form streams. Each one stands alone as a distinct action that was taken.

#### Example

```json
activity (id: "e5f6g7h8-...", type: "search", message: "Searching for: smartphone reviews")
activity (id: "i9j0k1l2-...", type: "open_page", message: "Opening https://example.com/review")
activity (id: "m3n4o5p6-...", type: "find_in_page", message: "Finding 'price' in page")
activity (id: "q7r8s9t0-...", type: "extract", message: "Performing extract action")
```

> For more detailed structure and contract, go to next page