9.4 Building Through Conversation

1. The Project: Scientific Data Explorer

Imagine a researcher who just finished a 200-row experiment, opens a browser tab, drops in a CSV file, and instantly sees means, quartiles, and distribution plots for every column, with a single click to export the filtered subset she needs for her next analysis. That is the application we will build from scratch in this section: a scientific data explorer, simple enough to complete in one chapter yet complex enough to exercise every phase of the vibe coding workflow.

The application has four components: a data ingestion layer (parsing and validating CSV uploads), a statistics engine (computing means, standard deviations, correlations, and histograms), a REST API (a set of HTTP endpoints that expose the statistics engine to client applications), and a web frontend (rendering the results in a browser). We build each component through a separate round of the vibe coding loop.

How the Loop Drives Each Component

Without a structured loop, teams routinely discover that AI-generated code looks correct on first reading but silently mishandles edge cases, turning a ten-minute generation step into hours of unguided debugging. A single well-written test catches what a careful code review misses, and a disciplined cycle ensures that every such test exists before the code does.

The vibe coding loop is a structured cycle of four phases: specify, generate, verify, and repair. It is the core engine of AI-assisted development. It transforms an inherently unpredictable process (asking a large language model (LLM) to write code) into a convergent one: each iteration reduces the gap between intent and implementation. You express your intent as executable contracts (tests, schemas, type annotations). The model generates code that attempts to satisfy those contracts, automated verification reveals mismatches, and targeted repair prompts close the remaining gaps. Use this loop instead of unstructured prompting whenever the task involves more than a single function, or whenever correctness matters more than speed of the first draft. Figure 9.4 below illustrates how the four phases connect and where repair feeds back into specification.

This project contributes to the Discovery Workbench, the platform that grows across the book. The data explorer becomes the Workbench's data inspection module, which later chapters extend with exploratory analysis (Chapter 25), anomaly detection (Chapter 30), and experiment provenance tracking (Chapter 47).

2. Phase 1: Write the Contracts First

The vibe coding methodology begins with contracts, not code. We write the test suite, the Pydantic schemas (where Pydantic is a Python library that enforces type constraints on data structures at runtime), and the type stubs before generating a single line of implementation. This is test-driven development (TDD) adapted for AI-assisted generation: the tests serve as both specification and verification.

We start with the Pydantic schemas that define the data contracts between components. In short: The conversation that builds software best is one where failing tests do the talking and the human never touches the implementation.

# schemas.py
from pydantic import BaseModel, Field
from typing import Optional

class DatasetMetadata(BaseModel):
    """Contract for uploaded dataset metadata."""
    filename: str = Field(min_length=1, max_length=255)
    num_rows: int = Field(gt=0)
    num_columns: int = Field(gt=0)
    column_names: list[str] = Field(min_length=1)
    column_types: dict[str, str] = Field(
        description="Mapping from column name to detected type: "
                    "'numeric', 'categorical', or 'datetime'"
    )

class ColumnStatistics(BaseModel):
    """Contract for per-column summary statistics."""
    column_name: str
    count: int = Field(gt=0)
    missing_count: int = Field(ge=0)
    dtype: str

class NumericColumnStatistics(ColumnStatistics):
    """Extended statistics for numeric columns."""
    dtype: str = "numeric"
    mean: float
    std: float = Field(ge=0)
    min_val: float
    max_val: float
    median: float
    q25: float
    q75: float

class CategoricalColumnStatistics(ColumnStatistics):
    """Extended statistics for categorical columns."""
    dtype: str = "categorical"
    unique_count: int = Field(gt=0)
    top_value: str
    top_frequency: int = Field(gt=0)

class DatasetSummary(BaseModel):
    """Contract for full dataset summary."""
    metadata: DatasetMetadata
    columns: list[NumericColumnStatistics | CategoricalColumnStatistics]

With the schemas defined, we write the test suite. Each test encodes a behavioral requirement from our mental specification. We write these tests knowing they will fail; that is the point. The failing tests are the executable specification that guides code generation.

# test_ingestion.py
import pytest
import tempfile
import os
from schemas import DatasetMetadata

# The function we will ask the AI to generate
from ingestion import ingest_csv

@pytest.fixture
def sample_csv(tmp_path):
    """Create a sample CSV file for testing."""
    content = (
        "id,temperature,pressure,label\n"
        "1,23.5,101.3,control\n"
        "2,24.1,101.5,treatment\n"
        "3,,101.2,control\n"
        "4,22.8,101.4,treatment\n"
    )
    path = tmp_path / "sample.csv"
    path.write_text(content, encoding="utf-8")
    return path

@pytest.fixture
def empty_csv(tmp_path):
    """Create a CSV with headers but no data."""
    path = tmp_path / "empty.csv"
    path.write_text("id,temperature,pressure\n", encoding="utf-8")
    return path

def test_ingest_returns_metadata(sample_csv):
    """Ingestion returns valid DatasetMetadata."""
    metadata, data = ingest_csv(str(sample_csv))
    assert isinstance(metadata, DatasetMetadata)
    assert metadata.num_rows == 4
    assert metadata.num_columns == 4
    assert "temperature" in metadata.column_names

def test_ingest_detects_column_types(sample_csv):
    """Ingestion correctly classifies column types."""
    metadata, data = ingest_csv(str(sample_csv))
    assert metadata.column_types["temperature"] == "numeric"
    assert metadata.column_types["label"] == "categorical"

def test_ingest_preserves_missing_values(sample_csv):
    """Missing values are preserved as NaN, not dropped."""
    metadata, data = ingest_csv(str(sample_csv))
    assert metadata.num_rows == 4  # all rows kept
    # Row 3 has missing temperature
    import math
    temp_values = data["temperature"].tolist()
    assert any(math.isnan(v) for v in temp_values)

def test_ingest_empty_csv_raises(empty_csv):
    """Ingesting a CSV with no data rows raises ValueError."""
    with pytest.raises(ValueError, match="No data rows"):
        ingest_csv(str(empty_csv))

def test_ingest_nonexistent_file():
    """Ingesting a nonexistent file raises FileNotFoundError."""
    with pytest.raises(FileNotFoundError):
        ingest_csv("/nonexistent/path.csv")

# test_statistics.py
import pytest
import numpy as np
import pandas as pd
from schemas import NumericColumnStatistics, CategoricalColumnStatistics

from statistics_engine import compute_column_stats

@pytest.fixture
def numeric_series():
    """A pandas Series of numeric values with one missing."""
    return pd.Series([23.5, 24.1, np.nan, 22.8], name="temperature")

@pytest.fixture
def categorical_series():
    return pd.Series(["control", "treatment", "control", "treatment"],
                     name="label")

def test_numeric_stats_values(numeric_series):
    """Numeric statistics are computed correctly."""
    stats = compute_column_stats(numeric_series)
    assert isinstance(stats, NumericColumnStatistics)
    assert stats.count == 3  # excludes NaN
    assert stats.missing_count == 1
    assert abs(stats.mean - 23.4667) < 0.001

def test_numeric_stats_quartiles(numeric_series):
    """Quartiles are computed correctly."""
    stats = compute_column_stats(numeric_series)
    assert stats.q25 <= stats.median <= stats.q75
    assert stats.min_val <= stats.q25
    assert stats.q75 <= stats.max_val

def test_categorical_stats(categorical_series):
    """Categorical statistics are computed correctly."""
    stats = compute_column_stats(categorical_series)
    assert isinstance(stats, CategoricalColumnStatistics)
    assert stats.unique_count == 2
    assert stats.top_value in ("control", "treatment")
    assert stats.top_frequency == 2

def test_single_value_series():
    """A series with a single value should produce valid stats."""
    s = pd.Series([42.0], name="single")
    stats = compute_column_stats(s)
    assert stats.mean == 42.0
    assert stats.std == 0.0
    assert stats.min_val == stats.max_val == 42.0

3. Phase 2: Generate Through Conversation

With the contracts in place, we begin the generate phase. The following transcript shows an idealized vibe coding conversation with Claude Code. In practice, your conversation will have more back-and-forth, but the structure is the same.

The first prompt provides the schemas and tests as context, then asks for the implementation:

# Prompt 1 (to Claude Code):
# "Here are my Pydantic schemas (schemas.py) and test suite
# (test_ingestion.py). Implement ingestion.py so that all tests
# in test_ingestion.py pass. Use pandas for CSV parsing.
# The function signature is:
#
#   def ingest_csv(path: str) -> tuple[DatasetMetadata, pd.DataFrame]
#
# Run the tests after implementing."

# --- Claude Code generates: ingestion.py ---

import pandas as pd
import numpy as np
from pathlib import Path
from schemas import DatasetMetadata

def ingest_csv(path: str) -> tuple[DatasetMetadata, pd.DataFrame]:
    """
    Ingest a CSV file and return metadata plus the raw DataFrame.

    Args:
        path: Path to a UTF-8 encoded CSV file with a header row.

    Returns:
        Tuple of (DatasetMetadata, DataFrame).

    Raises:
        FileNotFoundError: If the file does not exist.
        ValueError: If the file has no data rows.
    """
    filepath = Path(path)
    if not filepath.exists():
        raise FileNotFoundError(f"File not found: {path}")

    df = pd.read_csv(path, encoding="utf-8")

    if len(df) == 0:
        raise ValueError("No data rows found in the CSV file")

    # Detect column types
    column_types = {}
    for col in df.columns:
        if pd.api.types.is_numeric_dtype(df[col]):
            column_types[col] = "numeric"
        elif pd.api.types.is_datetime64_any_dtype(df[col]):
            column_types[col] = "datetime"
        else:
            column_types[col] = "categorical"

    metadata = DatasetMetadata(
        filename=filepath.name,
        num_rows=len(df),
        num_columns=len(df.columns),
        column_names=list(df.columns),
        column_types=column_types,
    )

    return metadata, df

Claude Code runs the tests and reports results. In a typical first round, most tests pass but edge cases may need repair.

# Claude Code test output (simulated):
# ==================== test session starts ====================
# test_ingestion.py::test_ingest_returns_metadata          PASSED
# test_ingestion.py::test_ingest_detects_column_types      FAILED
# test_ingestion.py::test_ingest_preserves_missing_values  PASSED
# test_ingestion.py::test_ingest_empty_csv_raises          PASSED
# test_ingestion.py::test_ingest_nonexistent_file          PASSED
# ==================== 1 failed, 4 passed ====================
#
# FAILED test_ingest_detects_column_types:
#   AssertionError: assert 'numeric' == metadata.column_types['id']
#   The 'id' column contains integers, detected as 'numeric',
#   but the test expects 'temperature' to be numeric (which it is)
#   and 'label' to be categorical.
#   Actual column_types: {'id': 'numeric', 'temperature': 'numeric',
#                         'pressure': 'numeric', 'label': 'categorical'}
#   All assertions pass. Re-examining...
#   Actually the test passes. Let me re-run.
#
# On re-run: 5 passed. (The initial failure was a flaky import issue.)

4. Phase 3: Verify with the Full Stack

Passing the unit tests is necessary but not sufficient. We now run the full verification stack from Section 9.3: linting with ruff (a fast Python linter that checks style and common errors), type checking with mypy (a static type checker that verifies type annotations without running the code), and property-based tests. Where example-based unit tests check specific input/output pairs, property-based tests generate hundreds of random inputs and verify that structural invariants (such as "row count is preserved" or "every column has a type") hold across all of them. This makes them particularly effective at catching edge cases that a human would not think to write by hand.

# test_ingestion_properties.py
"""Property-based tests for the ingestion module."""
import tempfile
from pathlib import Path

from hypothesis import given, settings, assume
from hypothesis import strategies as st
import pandas as pd

from ingestion import ingest_csv

# Strategy: generate random DataFrames, write them as CSV, ingest them
@st.composite
def random_csv_file(draw):
    """Generate a random CSV file with at least one row."""
    n_rows = draw(st.integers(min_value=1, max_value=50))
    n_cols = draw(st.integers(min_value=1, max_value=10))

    # Generate column names (unique, non-empty)
    col_names = [f"col_{i}" for i in range(n_cols)]

    # For each column, choose numeric or string
    data = {}
    for col in col_names:
        is_numeric = draw(st.booleans())
        if is_numeric:
            values = draw(st.lists(
                st.one_of(
                    st.floats(allow_nan=True, allow_infinity=False,
                              min_value=-1e6, max_value=1e6),
                    st.none(),
                ),
                min_size=n_rows, max_size=n_rows,
            ))
            data[col] = values
        else:
            values = draw(st.lists(
                st.text(min_size=0, max_size=20,
                        alphabet=st.characters(
                            whitelist_categories=("L", "N", "Z"),
                        )),
                min_size=n_rows, max_size=n_rows,
            ))
            data[col] = values

    df = pd.DataFrame(data)

    # Write to temp file
    tmp = tempfile.NamedTemporaryFile(
        mode="w", suffix=".csv", delete=False, encoding="utf-8",
    )
    df.to_csv(tmp, index=False)
    tmp.close()
    return tmp.name, df

@given(csv_data=random_csv_file())
@settings(max_examples=100, deadline=5000)
def test_ingest_preserves_row_count(csv_data):
    """Property: ingestion preserves the number of rows."""
    path, original_df = csv_data
    try:
        metadata, ingested_df = ingest_csv(path)
        assert metadata.num_rows == len(original_df)
        assert len(ingested_df) == len(original_df)
    finally:
        Path(path).unlink(missing_ok=True)

@given(csv_data=random_csv_file())
@settings(max_examples=100, deadline=5000)
def test_ingest_preserves_column_count(csv_data):
    """Property: ingestion preserves the number of columns."""
    path, original_df = csv_data
    try:
        metadata, ingested_df = ingest_csv(path)
        assert metadata.num_columns == len(original_df.columns)
    finally:
        Path(path).unlink(missing_ok=True)

@given(csv_data=random_csv_file())
@settings(max_examples=100, deadline=5000)
def test_ingest_metadata_consistency(csv_data):
    """Property: metadata fields are internally consistent."""
    path, original_df = csv_data
    try:
        metadata, ingested_df = ingest_csv(path)
        # column_names length matches num_columns
        assert len(metadata.column_names) == metadata.num_columns
        # every column in column_types is in column_names
        assert set(metadata.column_types.keys()) == set(metadata.column_names)
        # every type is one of the expected values
        for dtype in metadata.column_types.values():
            assert dtype in ("numeric", "categorical", "datetime")
    finally:
        Path(path).unlink(missing_ok=True)

# Verification stack output:
#
# Layer 1: ruff .................. PASSED (0.3s)
#   No linting issues found.
#
# Layer 2: mypy .................. PASSED (2.1s)
#   No type errors found.
#
# Layer 3: pytest ................ PASSED (8.4s)
#   9 unit tests passed
#   3 property tests passed (300 examples total)
#   0 failures
#
# Summary: 3/3 layers passed in 10.8s
# Specification completeness: 78% (7/9 behavioral categories covered)
# Uncovered: large file handling, concurrent uploads

5. Phase 4: Building the API Layer

With all unit and property tests green, the data layer is solid. The API layer comes next, following the same pattern: schemas first, tests second, generation third, verification fourth.

# test_api.py
"""Tests for the REST API layer."""
import pytest
import io
from app import create_app

@pytest.fixture
def client():
    """Create a test client for the Flask application."""
    app = create_app(testing=True)  # application factory: a function that builds and configures a Flask app instance
    with app.test_client() as client:
        yield client

@pytest.fixture
def sample_csv_bytes():
    """CSV content as bytes for upload testing."""
    content = (
        "temperature,pressure,label\n"
        "23.5,101.3,control\n"
        "24.1,101.5,treatment\n"
        "22.8,101.4,control\n"
    )
    return content.encode("utf-8")

def test_upload_returns_metadata(client, sample_csv_bytes):
    """POST /api/upload returns dataset metadata."""
    response = client.post(
        "/api/upload",
        data={"file": (io.BytesIO(sample_csv_bytes), "experiment.csv")},
        content_type="multipart/form-data",
    )
    assert response.status_code == 200
    data = response.get_json()
    assert data["metadata"]["num_rows"] == 3
    assert "temperature" in data["metadata"]["column_names"]

def test_upload_no_file_returns_400(client):
    """POST /api/upload without a file returns 400."""
    response = client.post("/api/upload")
    assert response.status_code == 400

def test_summary_endpoint(client, sample_csv_bytes):
    """GET /api/summary/{dataset_id} returns column statistics."""
    # First upload
    upload = client.post(
        "/api/upload",
        data={"file": (io.BytesIO(sample_csv_bytes), "experiment.csv")},
        content_type="multipart/form-data",
    )
    dataset_id = upload.get_json()["dataset_id"]

    # Then fetch summary
    response = client.get(f"/api/summary/{dataset_id}")
    assert response.status_code == 200
    data = response.get_json()
    assert len(data["columns"]) == 3

def test_summary_unknown_dataset_returns_404(client):
    """GET /api/summary/{unknown_id} returns 404."""
    response = client.get("/api/summary/nonexistent")
    assert response.status_code == 404

def test_health_endpoint(client):
    """GET /api/health returns 200 with status ok."""
    response = client.get("/api/health")
    assert response.status_code == 200
    assert response.get_json()["status"] == "ok"

The specification-grade prompt for the API layer references both the schemas and the test file:

# Prompt 2 (to Claude Code):
# "Implement app.py with a Flask application factory create_app().
# The app should have these endpoints:
#
# POST /api/upload: accept a CSV file upload, ingest it using
#   ingest_csv(), store the result in memory (dict keyed by UUID),
#   return JSON with 'dataset_id' and 'metadata'.
#
# GET /api/summary/: compute column statistics using
#   compute_column_stats() for each column, return JSON matching
#   the DatasetSummary schema.
#
# GET /api/health: return {'status': 'ok'}.
#
# Use the schemas from schemas.py for serialization.
# Use ingestion.py and statistics_engine.py for the business logic.
# All tests in test_api.py must pass."

6. Phase 5: End-to-End Verification with Playwright

Unit and integration tests prove that each endpoint returns the right JSON, but they cannot catch a broken upload button or a missing error div; only a real browser can verify what the user actually sees. Playwright (a browser automation library that drives Chromium, Firefox, and WebKit programmatically) provides that final verification layer.

The final verification layer tests the application as a user would experience it: through a web browser. Playwright automates browser interactions, clicking buttons, uploading files, and reading page content. This is Layer 4 of the verification stack from Section 9.3.

# test_e2e.py
"""End-to-end browser tests using Playwright."""
import pytest
from playwright.sync_api import Page, expect

@pytest.fixture(scope="session")
def app_url():
    """URL of the running application (started externally)."""
    return "http://localhost:5000"

def test_homepage_loads(page: Page, app_url):
    """The homepage loads and displays the application title."""
    page.goto(app_url)
    expect(page.locator("h1")).to_contain_text("Data Explorer")

def test_upload_and_view_summary(page: Page, app_url, tmp_path):
    """Upload a CSV and verify that summary statistics appear."""
    # Create a test CSV
    csv_path = tmp_path / "test_data.csv"
    csv_path.write_text(
        "temperature,pressure\n23.5,101.3\n24.1,101.5\n22.8,101.4\n"
    )

    # Navigate to upload page
    page.goto(app_url)

    # Upload the file
    page.locator('input[type="file"]').set_input_files(str(csv_path))
    page.locator('button:has-text("Upload")').click()

    # Wait for and verify summary statistics
    page.wait_for_selector(".summary-table", timeout=5000)
    expect(page.locator(".summary-table")).to_be_visible()

    # Verify column names appear
    content = page.locator(".summary-table").text_content()
    assert "temperature" in content
    assert "pressure" in content

def test_empty_upload_shows_error(page: Page, app_url):
    """Clicking upload without a file shows an error message."""
    page.goto(app_url)
    page.locator('button:has-text("Upload")').click()
    expect(page.locator(".error-message")).to_be_visible()

7. The Complete Session Retrospective

The full vibe coding session that produced the data explorer spans six rounds. The following table summarizes each round of the loop, its inputs, outputs, and outcome.

session_log = [
    {
        "round": 1,
        "component": "schemas",
        "input": "Pydantic schema definitions",
        "method": "Manual (human-written)",
        "tests_written": 0,
        "tests_passed": "N/A",
        "outcome": "commit",
    },
    {
        "round": 2,
        "component": "ingestion",
        "input": "Schemas + 5 unit tests",
        "method": "Vibe coded (1 iteration)",
        "tests_written": 5,
        "tests_passed": "5/5",
        "outcome": "commit",
    },
    {
        "round": 3,
        "component": "ingestion (properties)",
        "input": "3 property-based tests",
        "method": "Vibe coded (2 iterations, 1 repair)",
        "tests_written": 3,
        "tests_passed": "3/3 (300 examples)",
        "outcome": "commit after repair",
    },
    {
        "round": 4,
        "component": "statistics_engine",
        "input": "Schemas + 4 unit tests",
        "method": "Vibe coded (1 iteration)",
        "tests_written": 4,
        "tests_passed": "4/4",
        "outcome": "commit",
    },
    {
        "round": 5,
        "component": "API (app.py)",
        "input": "Schemas + modules + 5 API tests",
        "method": "Vibe coded (2 iterations, 1 repair)",
        "tests_written": 5,
        "tests_passed": "5/5",
        "outcome": "commit after repair",
    },
    {
        "round": 6,
        "component": "frontend + E2E",
        "input": "API + 3 Playwright tests",
        "method": "Vibe coded (3 iterations, 2 repairs)",
        "tests_written": 3,
        "tests_passed": "3/3",
        "outcome": "commit after repair",
    },
]

total_tests = sum(r["tests_written"] for r in session_log)
total_rounds = len(session_log)
total_iterations = 1 + 1 + 2 + 1 + 2 + 3  # from the method descriptions
print(f"Total tests: {total_tests}")
print(f"Total rounds: {total_rounds}")
print(f"Total iterations: {total_iterations}")
print(f"Average iterations per component: {total_iterations / total_rounds:.1f}")
# Total tests: 20
# Total rounds: 6
# Total iterations: 10
# Average iterations per component: 1.7

The session statistics reveal a pattern: the number of repair iterations correlates with the complexity of the component's interface with external systems. The pure data-processing components (ingestion, statistics) needed 1 to 2 iterations. The API layer (which must handle HTTP semantics, error codes, and JSON serialization) needed 2 iterations. The frontend (which must coordinate HTML, JavaScript, CSS, and server communication) needed 3 iterations. This pattern typically holds across vibe coding projects: the more external interfaces a component has, the more specification gaps tend to emerge, and the more repair iterations it tends to require. Figure 9.4.1 illustrates vibe coding loop iteration pattern across components.

Exercises

1. (Conceptual) The data explorer recipe uses Flask for the API. List three specification gaps that would arise if we switched to FastAPI. Which gaps would be closed automatically by FastAPI's built-in features (Pydantic integration, automatic OpenAPI docs), and which would require new tests?
2. (Coding) Extend the data explorer with a /api/filter endpoint that accepts query parameters for column name, operator (gt, lt, eq), and value, and returns the filtered dataset. Write the test suite first (at least 4 tests covering valid filtering, invalid column, invalid operator, and no results), then use vibe coding to generate the implementation. Record how many iterations you need.
3. (Analysis) Run the full recipe from this section on your own machine. Track the time spent in each phase (specification, generation, verification, repair). What percentage of total time did you spend writing specifications (tests and schemas) versus writing steering prompts? How does this compare to the session statistics in the retrospective?