## Module 3: Text2SQL Scenario: Branching with an Agent

This module narrows the scope to a classic Text2SQL/database design problem: designing a database for a brand-new Todo app, letting the agent explore multiple approaches in parallel, then choosing one to continue evolving.

You will complete this module in a Jupyter Notebook (the notebook drives the agent to create/manage branches and run SQL on each branch).

### 3.1 Opening the Notebook

1. Click [VS Code](${LAB:HTTPS_REVERSE_PROXY_URL}?next=${LAB:"/vscode/?folder=/root/tidb-lab-branches"|urlencode} "VS Code") to open the IDE.

   > [!TIP]
   > When prompted, click `Yes, I trust the authors`.

2. In the left `EXPLORER`, open:
   - `todo_branch_story.ipynb`
   - `tidb_agent.py` (open it alongside the notebook to understand what tools the agent has)
3. In the notebook, click `Select Kernel` in the top-right, choose `Python Environments...`, and select the recommended `Python 3.11.x` interpreter.
4. Follow the notebook instructions strictly (run cells from top to bottom).

   > [!TIP]
   > It is recommended to copy the contents of `todo_branch_story.ipynb` and `tidb_agent.py` so that you can still access them after completing the lab.

### 3.2 Storyline: Three Parallel Paths, Then Evolve from the Chosen Path

In `todo_branch_story.ipynb`, we explore database design for a brand-new Todo app.

**Data involved**:

- `todos`: todo items (e.g., title, status, due date, created/updated timestamps)
- `users`: users (for ownership/assignment of todos)
- `extensions`: tags, checklist items, etc.

Then you will complete the following storyline:

1. **Step 1: Generate 3 Todo storage approaches in parallel (3 branches)**
   - The agent creates 3 branches: `todo_minimal`, `todo_tags`, `todo_checklists`
   - Each branch represents a different modeling approach; the agent creates tables and inserts sample data on that branch
2. **Step 1 (inspect and choose): Compare the three branches and select a baseline**
   - The notebook shows tables and sample rows for each branch to help you decide
3. **Step 2: Branch again from your chosen baseline and add a user system (2 child branches)**
   - Starting from your selected parent branch, create two child branches:
     - `{base}_owners`: each todo has a single owner
     - `{base}_assignments`: many-to-many between todos and users (collaborative assignment)
   - The agent creates a `users` table, adds relationships (FK/join table), and seeds sample rows
4. **Step 3: Visualize the branch tree**
   - The notebook visualizes branch lineage in the cluster, so you can see where branches were created and which path you continued from

### 3.3 Key Code to Pay Attention To (Materials)

The key materials in this lab are:

- `tidb_agent.py`
  - Wraps TiDB capabilities as Strands Agent tools such as `create_branch`, `create_branch_from_display_name`, and `run_sql_on_branch`
  - Key point: when executing SQL on a branch, you must use the branch's connection info to avoid running DDL/DML on the default branch by mistake
- `todo_branch_story.ipynb`
  - Drives **branch-style schema exploration** via prompts + tool calls, rather than a hardcoded SQL script