### Initialize SQLite Database Schema

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

This script initializes the SQLite database schema by creating necessary tables and indexes. It can be run using pnpm or tsx directly. The script creates the 'data/oss-data-analyst.db' file and defines schemas for 'companies', 'people', and 'accounts' tables, along with indexes for foreign keys and common lookups.

```bash
# Initialize database with schema
pnpm initDatabase

# Or run directly with tsx
tsx scripts/init-database.ts

# Creates:
# - data/oss-data-analyst.db
# - companies table (id, name, industry, employee_count, revenue, founded_year, country, city)
# - people table (id, first_name, last_name, email, company_id, job_title, department, salary, hire_date, birth_date)
# - accounts table (id, account_number, company_id, account_manager_id, status, account_type, monthly_value, total_revenue, contract_start_date, contract_end_date)
# - Indexes for foreign keys and common lookups
```

--------------------------------

### Build SQL from Plan

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Generates a SQL query from a finalized plan using semantic entity definitions. It takes a plan object as input and outputs the generated SQL string.

```typescript
import { BuildSQL } from "@/lib/tools/building";

// Generate SQL from plan
const result = await BuildSQL.execute({
  plan: {
    selectedEntities: ["People"],
    joinGraph: [],
    intent: {
      metrics: ["avg_salary"],
      dimensions: ["department"],
      filters: [],
      structuredFilters: [],
      timeRange: null,
      orderBy: [],
      limit: null
    }
  }
});

console.log(result.sql);
// SELECT
//   people.department AS department,
//   AVG(people.salary) AS avg_salary
// FROM people
// GROUP BY people.department
```

--------------------------------

### Load Entities Bulk Tool: Load Multiple Semantic Entity Definitions

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Efficiently loads multiple semantic entity definitions simultaneously for query planning. It accepts an array of entity names and returns their schemas, including dimensions, measures, metrics, and join information.

```typescript
```typescript
import { LoadEntitiesBulk } from "@/lib/tools/planning";

// Load multiple entities at once
const result = await LoadEntitiesBulk.execute({
  names: ["Company", "People", "Accounts"]
});

// Returns entity schemas with dimensions, measures, metrics, and joins
console.log(result.entities.Company);
// {
//   name: "Company",
//   table: "companies",
//   grain: "one row per company",
//   dimensions: [{ name: "industry", sql: "industry", type: "string" }, ...],
//   measures: [{ name: "total_companies", type: "count", sql: "id" }, ...],
//   joins: [{ target_entity: "People", relationship: "one_to_many", ... }]
// }
```
```

--------------------------------

### Load Entities in Bulk Tool

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Efficiently loads definitions for multiple semantic entities simultaneously, used during the query planning phase.

```APIDOC
## Load Entities in Bulk

### Description
Loads definitions for multiple semantic entities at once to support query planning.

### Method
Tool Execution (Internal)

### Endpoint
N/A (Tool function)

### Parameters
#### Request Body
- **names** (array of strings) - Required - A list of entity names to load.

### Request Example
```typescript
import { LoadEntitiesBulk } from "@/lib/tools/planning";

const result = await LoadEntitiesBulk.execute({
  names: ["Company", "People", "Accounts"]
});
```

### Response
#### Success Response
- **entities** (object) - An object where keys are entity names and values are their schemas, including dimensions, measures, metrics, and joins.

#### Response Example
```json
{
  "Company": {
    "name": "Company",
    "table": "companies",
    "grain": "one row per company",
    "dimensions": [{ "name": "industry", "sql": "industry", "type": "string" }, ...],
    "measures": [{ "name": "total_companies", "type": "count", "sql": "id" }, ...],
    "joins": [{ "target_entity": "People", "relationship": "one_to_many", ... }]
  }
}
```
```

--------------------------------

### Environment Configuration with Zod

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

This code snippet demonstrates Zod-validated environment configuration for type-safe settings. It imports a configuration schema and parses process.env to ensure all variables conform to the defined types and requirements. This provides compile-time safety and runtime validation for application settings, particularly for Snowflake connection details.

```typescript
import { configSchema } from "@/config/schema";

// Validate environment variables
const config = configSchema.parse(process.env);

// TypeScript knows the shape and types
console.log(config.SNOWFLAKE_ACCOUNT); // string
console.log(config.SNOWFLAKE_POOL_MAX); // number
console.log(config.STRICT_SQL_VALIDATION); // boolean

// Required Snowflake variables:
// - SNOWFLAKE_ACCOUNT
// - SNOWFLAKE_USERNAME
// - SNOWFLAKE_PASSWORD
// - SNOWFLAKE_WAREHOUSE

// Optional configuration:
// - SNOWFLAKE_DATABASE
// - SNOWFLAKE_SCHEMA
// - SNOWFLAKE_ROLE
// - SNOWFLAKE_STATEMENT_TIMEOUT (default: 120)
// - OBSERVABILITY_ENABLED (default: false)
```

--------------------------------

### Finalize Plan for SQL Building

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Completes the planning phase by creating a structured execution plan. It takes selected entities, a join graph, and query intent as input to generate the plan.

```typescript
import { FinalizePlan } from "@/lib/tools/planning";

// Create finalized plan with selected entities and query intent
const plan = await FinalizePlan.execute({
  selectedEntities: ["People"],
  joinGraph: [],
  intent: {
    metrics: ["avg_salary"],
    dimensions: ["department"],
    filters: [],
    structuredFilters: [
      { field: "department", operator: "in", values: ["Engineering", "Sales"] }
    ],
    timeRange: null,
    orderBy: [{ field: "avg_salary", direction: "desc" }],
    limit: 10
  }
});

// Plan is passed to building phase
console.log(plan);
```

--------------------------------

### Generate Vega-Lite Visualization Spec

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Generates Vega-Lite visualization specifications from query results. It takes query intent, rows, and columns as input to produce a JSON object suitable for charting.

```typescript
import { VisualizeData } from "@/lib/tools/reporting";

// Generate visualization spec
const result = await VisualizeData.execute({
  intent: {
    metrics: ["avg_salary"],
    dimensions: ["department"],
    timeRange: null
  },
  rows: [
    { department: "Engineering", avg_salary: 125000 },
    { department: "Sales", avg_salary: 95000 }
  ],
  columns: [
    { name: "department", type: "string" },
    { name: "avg_salary", type: "number" }
  ]
});

console.log(result.vegaLite);
// {
//   $schema: "https://vega.github.io/schema/vega-lite/v5.json",
//   mark: "bar",
//   encoding: {
//     x: { field: "department", type: "nominal" },
//     y: { field: "avg_salary", type: "quantitative" }
//   },
//   data: { values: [...] }
// }
```

--------------------------------

### Validate SQL Syntax and Semantics

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Performs syntax and semantic validation on generated SQL queries against a plan and schema. It requires the SQL query string and a plan object as input.

```typescript
import { ValidateSQL } from "@/lib/tools/building";

// Validate SQL against plan and schema
const result = await ValidateSQL.execute({
  plan: {
    selectedEntities: ["People"],
    joinGraph: [],
    intent: { metrics: ["avg_salary"], dimensions: ["department"], filters: [], structuredFilters: [] }
  },
  sql: "SELECT department, AVG(salary) as avg_salary FROM people GROUP BY department"
});

console.log(result);
// {
//   syntaxOk: true,
//   semanticOk: true,
//   notes: ["All validation checks passed"]
// }
```

--------------------------------

### Search Catalog Tool: Find Semantic Entities

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

This tool searches the semantic catalog for entities that match a natural language query. It takes a query string as input and returns a ranked list of candidate entities with their descriptions.

```typescript
```typescript
import { SearchCatalog } from "@/lib/tools/planning";

// Search for entities related to user query
const result = await SearchCatalog.execute({
  query: "employee compensation and salaries"
});

// Returns ranked candidates
console.log(result.candidates);
// [
//   { entity: "People", description: "Employee records with...", score: 8 },
//   { entity: "Company", description: "Company information...", score: 3 }
// ]
```
```

--------------------------------

### Search Semantic Catalog Tool

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

A tool used by the AI agent to search a semantic catalog for data entities that match natural language queries.

```APIDOC
## Search Semantic Catalog

### Description
Searches the semantic catalog for entities relevant to a natural language query.

### Method
Tool Execution (Internal)

### Endpoint
N/A (Tool function)

### Parameters
#### Request Body
- **query** (string) - Required - The natural language query to search the catalog with.

### Request Example
```typescript
import { SearchCatalog } from "@/lib/tools/planning";

const result = await SearchCatalog.execute({
  query: "employee compensation and salaries"
});
```

### Response
#### Success Response
- **candidates** (array) - An array of ranked entity candidates matching the query. Each candidate includes 'entity', 'description', and 'score'.

#### Response Example
```json
[
  { "entity": "People", "description": "Employee records with...", "score": 8 },
  { "entity": "Company", "description": "Company information...", "score": 3 }
]
```
```

--------------------------------

### Format Query Results to CSV

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Converts query results into CSV format, including a preview of the data for reporting purposes. It takes rows and columns as input and returns a base64 encoded CSV string and preview data.

```typescript
import { FormatResults } from "@/lib/tools/reporting";

// Format query results
const result = await FormatResults.execute({
  rows: [
    { department: "Engineering", avg_salary: 125000 },
    { department: "Sales", avg_salary: 95000 }
  ],
  columns: [
    { name: "department", type: "string" },
    { name: "avg_salary", type: "number" }
  ]
});

console.log(result);
// {
//   csvBase64: "ZGVwYXJ0bWVudCxhdmdfc2FsYXJ5CkVuZ2luZWVyaW5nLDEyNTAwMAo...",
//   preview: [
//     { department: "Engineering", avg_salary: 125000 },
//     { department: "Sales", avg_salary: 95000 }
//   ],
//   truncated: false,
//   totalRows: 2
// }
```

--------------------------------

### Run Agent: Orchestrate Multi-Phase Workflow and Tool Execution

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

The core agent orchestration function manages a multi-phase workflow, including planning, building SQL, execution with retries, and reporting. It takes conversation history and an optional model name as input and returns a streamable response.

```typescript
```typescript
import { runAgent } from "@/lib/agent";
import type { UIMessage } from "ai";

// Run agent with conversation history
const messages: UIMessage[] = [
  {
    role: "user",
    content: "How many companies are in the Technology industry?",
    id: "msg-1"
  }
];

const result = await runAgent({
  messages,
  model: "openai/gpt-5"
});

// Result is a streamText result that can be converted to various formats
const stream = result.toUIMessageStreamResponse();

// The agent automatically:
// 1. Plans which entities and fields are needed
// 2. Builds valid SQL with joins
// 3. Executes with retry logic
// 4. Reports results with visualizations
```
```

--------------------------------

### Scan Entity Properties Tool

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Selectively loads specific fields or properties from a semantic entity, optimizing context size for large schemas during query planning.

```APIDOC
## Scan Entity Properties

### Description
Loads specific fields from an entity to reduce context size for large schemas.

### Method
Tool Execution (Internal)

### Endpoint
N/A (Tool function)

### Parameters
#### Request Body
- **entity** (string) - Required - The name of the entity to scan.
- **fields** (array of strings) - Required - A list of fields (properties) to load for the entity.

### Request Example
```typescript
import { ScanEntityProperties } from "@/lib/tools/planning";

const result = await ScanEntityProperties.execute({
  entity: "People",
  fields: ["salary", "department", "avg_salary_by_dept"]
});
```

### Response
#### Success Response
- **entity** (string) - The name of the entity.
- **table** (string) - The underlying table name.
- **properties** (object) - An object containing details of the requested properties (name, type, SQL expression, field type).
- **dependencies** (object) - An object detailing field dependencies.

#### Response Example
```json
{
  "entity": "People",
  "table": "people",
  "properties": {
    "salary": { "name": "salary", "type": "number", "sql": "salary", "fieldType": "dimension" },
    "department": { "name": "department", "type": "string", "sql": "department", "fieldType": "dimension" },
    "avg_salary_by_dept": { "name": "avg_salary_by_dept", "type": "avg", "sql": "salary", "fieldType": "measure" }
  },
  "dependencies": {
    "avg_salary_by_dept": ["salary"]
  }
}
```
```

--------------------------------

### Scan Entity Properties Tool: Selectively Load Entity Fields

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

This tool selectively loads specific fields from an entity to reduce context size, especially for large schemas. It requires the entity name and an array of desired fields, returning property details and their dependencies.

```typescript
```typescript
import { ScanEntityProperties } from "@/lib/tools/planning";

// Load only needed fields from an entity
const result = await ScanEntityProperties.execute({
  entity: "People",
  fields: ["salary", "department", "avg_salary_by_dept"]
});

// Returns properties with dependency information
console.log(result);
// {
//   entity: "People",
//   table: "people",
//   properties: {
//     salary: { name: "salary", type: "number", sql: "salary", fieldType: "dimension" },
//     department: { name: "department", type: "string", sql: "department", fieldType: "dimension" },
//     avg_salary_by_dept: { name: "avg_salary_by_dept", type: "avg", sql: "salary", fieldType: "measure" }
//   },
//   dependencies: { avg_salary_by_dept: ["salary"] }
// }
```
```

--------------------------------

### Execute SQL with Automatic Repair

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Executes SQL queries with automatic error detection and repair capabilities. It includes parameters for timeout, retry attempts, and limit enforcement.

```typescript
import { ExecuteSQLWithRepair } from "@/lib/tools/execute-sqlite";

// Execute with auto-repair
const result = await ExecuteSQLWithRepair.execute({
  sql: "SELECT department, AVG(salary) as avg_salary FROM people GROUP BY department",
  plan: finalizedPlan,
  timeoutMs: 20000,
  attempts: 3,
  enforceLimit: true
});

console.log(result);
// {
//   rows: [
//     { department: "Engineering", avg_salary: 125000 },
//     { department: "Sales", avg_salary: 95000 }
//   ],
//   columns: [
//     { name: "department", type: "string" },
//     { name: "avg_salary", type: "number" }
//   ],
//   lastQueryId: "query-123",
//   attemptedSql: "SELECT...",
//   repaired: false,
//   repairReason: null
// }
```

--------------------------------

### Sanity Check Query Results for Anomalies

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

Performs quality assurance on query results to detect anomalies such as null values. It takes rows and columns as input and returns identified issues and their severity.

```typescript
import { SanityCheck } from "@/lib/tools/reporting";

// Check results for anomalies
const result = await SanityCheck.execute({
  rows: [
    { department: "Engineering", avg_salary: 125000 },
    { department: "Sales", avg_salary: null }
  ],
  columns: [
    { name: "department", type: "string" },
    { name: "avg_salary", type: "number" }
  ]
});

console.log(result);
// {
//   issues: ["Column 'avg_salary' has null values (50% missing)"],
//   severity: "medium"
// }
```

--------------------------------

### Main Agent Runner

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

The core orchestration function that manages the AI agent's multi-phase workflow, including planning, building, execution, and reporting of data analysis tasks.

```APIDOC
## Main Agent Runner

### Description
Orchestrates the AI agent's multi-phase workflow for data analysis.

### Method
Internal Function Call

### Endpoint
N/A (Internal function)

### Parameters
#### Request Body
- **messages** (array) - Required - An array of UI message objects representing the conversation history.
- **model** (string) - Optional - The AI model to use.

### Request Example
```typescript
import { runAgent } from "@/lib/agent";
import type { UIMessage } from "ai";

const messages: UIMessage[] = [
  {
    role: "user",
    content: "How many companies are in the Technology industry?",
    id: "msg-1"
  }
];

const result = await runAgent({
  messages,
  model: "openai/gpt-5"
});
```

### Response
#### Success Response
- **streamText result** - The function returns a streamText result which can be converted to various formats, including UI message streams.

#### Response Example
```typescript
const stream = result.toUIMessageStreamResponse();
```

### Notes
- The agent automatically plans, builds SQL, executes queries with retry logic, and reports results with visualizations.
```

--------------------------------

### Chat API Endpoint

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

This API endpoint receives chat messages in natural language and streams back responses from the AI agent, which go through multiple reasoning phases.

```APIDOC
## POST /api/chat

### Description
This endpoint processes natural language chat messages and returns AI agent responses.

### Method
POST

### Endpoint
/api/chat

### Parameters
#### Request Body
- **messages** (array) - Required - An array of message objects, where each object has a 'role' (user or assistant) and 'content' (the message text).
- **model** (string) - Optional - The AI model to use for processing the request. Defaults to a predefined model if not specified.

### Request Example
```json
{
  "messages": [
    { "role": "user", "content": "What is the average salary by department?" }
  ],
  "model": "openai/gpt-5" 
}
```

### Response
#### Success Response (200)
- **stream** (ReadableStream) - The response is a stream of text representing the AI agent's output, which can be processed chunk by chunk.

#### Response Example
(Streaming output, example shows a single chunk)
```
{"role":"assistant","content":"SELECT department, AVG(salary) FROM employees GROUP BY department;"}
```
```

--------------------------------

### POST /api/chat: Receive and Stream AI Agent Responses

Source: https://context7.com/vercel-labs/oss-data-analyst/llms.txt

This API endpoint accepts chat messages and streams AI agent responses through various reasoning phases. It expects a JSON request body containing an array of messages and an optional model name. The response is a stream of data that can be read iteratively.

```typescript
```typescript
// POST /api/chat
// Request body
const request = {
  messages: [
    { role: "user", content: "What is the average salary by department?" }
  ],
  model: "openai/gpt-5" // optional
};

// Usage with fetch
const response = await fetch('http://localhost:3000/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request)
});

// Stream response
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.