AHMAD HASSAN
GitHub
ALL PROJECTS
02 / DATA / AGENTIC ANALYTICSSOURCE AVAILABLE

InsightLoop.

A question. A query. A trace you can follow.

A Next.js data agent explores a synthetic retail warehouse in BigQuery. A hand-written loop chooses tools, guards read-only SQL, retries bounded failures and streams its investigation trace to the interface.

01 / THE PROBLEM

A result needs a trail.

A data question may need schema discovery, a query, error recovery or a clarification. InsightLoop exposes that process instead of showing a final answer with no path back to the underlying data.

02 / ARCHITECTURE

How the system moves.

  1. 01

    Ask

    The Next.js chat route accepts a question and opens an NDJSON response stream.

  2. 02

    Plan

    The custom loop sends the current state to a Gemini or Groq adapter with a common tool schema.

  3. 03

    Choose a tool

    The agent can inspect schema, run SQL or ask a clarifying question.

  4. 04

    Constrain BigQuery

    The SQL client permits one read-only SELECT/WITH statement, caps returned rows and cancels timed-out jobs.

  5. 05

    Observe

    Results or errors feed the next bounded step, while the UI shows trace events, SQL and the final answer.

03 / ENGINEERING DECISIONS

Why these boundaries matter.

01

Explicit loop

The application owns the plan, tool, observe and retry cycle rather than hiding it inside a framework.

02

Query boundary

The BigQuery client rejects mutating statements and applies a 15-second timeout with job cancellation.

03

Visible reasoning

Step and completion events drive the trace panel, so the user can inspect the query path.

04 / SOURCE EVIDENCE

What the repository shows.

  • Custom loop bounded to nine tool rounds and three SQL retries
  • Only a single SELECT or WITH query passes the SQL guard
  • Streamed steps and a final answer over NDJSON

Selected files from the public repository, pinned to the revision reviewed for this case study.

EXPLORE THE REPOSITORY

HONEST BOUNDARY

The public source supports the loop, guards and UI trace. This review did not independently run BigQuery, establish answer accuracy or verify production usage and business outcomes.