### Frontend Quick Start Guide

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/frontend.md

Steps to clone the repository, install dependencies, configure environment variables, and start the development server.

```bash
git clone <repository>
cd Auto-Analyst-CS/auto-analyst-frontend

npm install

cp .env.example .env.local
# Edit .env.local with your configuration

npm run dev
```

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

### Backend Setup

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/CONTRIBUTING.md

Set up the Python virtual environment, activate it, and install backend dependencies.

```bash
cd auto-analyst-backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```

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

### Frontend Development Setup

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/README.md

Commands to set up the development environment for the frontend, including installing dependencies, copying environment variables, and starting the development server.

```bash
cd auto-analyst-frontend
npm install
cp .env.example .env.local
npm run dev
```

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

### Frontend Setup

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/CONTRIBUTING.md

Install frontend dependencies using npm.

```bash
cd auto-analyst-frontend
npm install
```

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

### Install Dependencies

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/README.md

Navigate to the backend directory, create a virtual environment, activate it, and install all required dependencies using pip.

```bash
cd Auto-Analyst-CS/auto-analyst-backend

python -m venv venv
source venv/bin/activate  # Linux/Mac
virtualenv\Scripts\activate     # Windows

pip install -r requirements.txt
```

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

### Install Dependencies

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/getting_started.md

Clone the repository, set up a virtual environment, and install project dependencies using pip.

```bash
cd Auto-Analyst-CS/auto-analyst-backend

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
virtualenv\Scripts\activate     # Windows

pip install -r requirements.txt
```

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

### Start Frontend Development Server

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Use this command to start the frontend development server. Ensure you are in the 'auto-analyst-frontend' directory.

```bash
cd auto-analyst-frontend
npm run dev
```

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

### Start Both Frontend and Backend Servers

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

If configured in the root package.json, this command starts both the frontend and backend development servers simultaneously.

```bash
# Or run both servers simultaneously
npm run dev:all
```

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

### Start Development Server

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/README.md

Start the FastAPI development server using the default Python module or with uvicorn for more control over host and port.

```bash
# Start the FastAPI server
python -m app

# Or with uvicorn for more control
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

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

### Next.js Production Build and Server Start

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/architecture/overview.md

Commands to build the Next.js application for production and start the production server.

```bash
npm run build     # Next.js production build
```

```bash
npm run start     # Production server
```

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

### Start Development Servers

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Commands to simultaneously run the backend and frontend development servers.

```bash
# Terminal 1 - Backend
cd auto-analyst-backend && uvicorn app:app --reload

# Terminal 2 - Frontend  
cd auto-analyst-frontend && npm run dev
```

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

### Start Full Stack Environment with Docker Compose

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Use this command to start the entire application stack using Docker Compose. This is the recommended way for full-stack development.

```bash
# Use Docker Compose for full environment
docker-compose up -d
```

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

### Start Development Server

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/getting_started.md

Launch the FastAPI development server using the Python app.py script or uvicorn.

```bash
# Development server
python app.py

# Or with uvicorn
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

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

### Start Backend Server with Hot Reload

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Use this command to start the backend development server with hot reload enabled. Ensure you are in the 'auto-analyst-backend' directory.

```bash
cd auto-analyst-backend
python -m app
```

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

### Install and Run Self-hosted Redis

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/development/environment-setup.md

Installs Redis locally using Homebrew for macOS or runs a Redis instance using Docker. This is an alternative to using Upstash for Redis.

```bash
# Install Redis locally
brew install redis  # macOS
# or use Docker
docker run -d -p 6379:6379 redis:alpine
```

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

### Copy Environment Template

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/development/environment-setup.md

Copies the example environment file to a local configuration file. This should be the first step in setting up your local environment.

```bash
cp .env.example .env.local
```

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

### Python Function Example

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/CONTRIBUTING.md

Example of a Python function with type hints and a docstring, adhering to PEP 8 and Black formatting.

```python
from typing import List, Optional

def process_data(data: List[str], limit: Optional[int] = None) -> List[str]:
    """Process the input data with optional limit. 
    
    Args:
        data: List of strings to process
        limit: Optional maximum number of items to process
        
    Returns:
        Processed list of strings
    """
    return data[:limit] if limit else data
```

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

### Direct API Call Example

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/architecture/overview.md

Example of making a direct POST request to the backend API using Axios for chat interactions.

```typescript
// Direct calls to Python FastAPI backend
const response = await axios.post(`${API_URL}/chat`, {
  message: userMessage,
  agent: selectedAgent
});
```

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

### Example: Data Processing and Visualization

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/system/shared_dataframe.md

A complete example demonstrating Agent1 processing data and Agent2 visualizing it using the shared `df_processed` DataFrame. Agent1 filters data and creates a new feature, while Agent2 uses Plotly for interactive visualization.

```python
# Agent1 code
import pandas as pd

# Load and process data
df_processed = df.copy()
df_processed = df_processed[df_processed['price'] > 0]  # Remove invalid prices
df_processed['price_per_sqft'] = df_processed['price'] / df_processed['sqft']
print(f"Created df_processed with {len(df_processed)} rows after processing")
```

```python
# Agent2 code
import plotly.express as px

# Use the processed dataframe
print(f"Using df_processed with {len(df_processed)} rows")
fig = px.scatter(df_processed, x='sqft', y='price', color='price_per_sqft',
                title='Price vs. Square Footage (Colored by Price per SqFt)')
fig.show()
```

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

### Development Environment Architecture

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/architecture/architecture.md

Outlines the components and flow for the local development setup.

```text
Local Development → SQLite Database → File-based Logging → 
Direct Model API Calls → Hot Reloading
```

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

### Provider Hierarchy Example

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/state-management/stores.md

Demonstrates the nested structure of context providers for managing application-wide state and services.

```typescript
// components/ClientLayout.tsx
export default function ClientLayout({ children }: { children: ReactNode }) {
  return (
    <SessionProvider>
      <ThemeProvider>
        <AuthProvider>
          <CreditProvider>
            <DeepAnalysisProvider>
              {children}
            </DeepAnalysisProvider>
          </CreditProvider>
        </AuthProvider>
      </ThemeProvider>
    </SessionProvider>
  )
}
```

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

### Add Missing API Keys to .env File

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/troubleshooting/troubleshooting.md

Example of how to add API keys to the .env file for authentication.

```env
# Add to .env file
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...
ADMIN_API_KEY=your_admin_key_here
```

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

### Create or Retrieve User Response

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/chats.md

Example response after creating or retrieving a user. Includes user ID and creation timestamp.

```json
{
  "user_id": 123,
  "username": "john_doe",
  "email": "john@example.com",
  "created_at": "2023-05-01T12:00:00Z"
}
```

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

### List Agent Templates

Source: https://context7.com/firebird-technologies/auto-analyst/llms.txt

The GET /templates/ endpoint lists all available agent templates. Filtering by variant type is supported.

```bash
curl "http://localhost:8000/templates/?variant_type=individual"
```

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

### Docker Environment Variables

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/development/environment-setup.md

Example of how to pass environment variables to a Docker container. This is typically done during the Docker build or run process.

```dockerfile
# Pass environment variables to container
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
ENV NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
# ... other variables
```

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

### Get Chat Feedback Response

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/feedback.md

Example response from the GET /feedback/chat/{chat_id} endpoint, returning an array of feedback objects for all messages within a given chat. An empty array is returned if no feedback exists.

```json
[
    {
        "feedback_id": 123,
        "message_id": 456,
        "rating": 5,
        "feedback_comment": null,
        "model_name": "gpt-4o-mini",
        "model_provider": "openai",
        "temperature": 0.7,
        "max_tokens": 6000,
        "created_at": "2023-05-01T12:00:00Z",
        "updated_at": "2023-05-01T12:00:00Z"
    }
]
```

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

### Container Architecture Dockerfile

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/architecture/architecture.md

A multi-stage Dockerfile for building optimized container images, including dependency installation, application setup, health checks, and environment configurations.

```dockerfile
# Multi-stage build for optimization
FROM python:3.11-slim as base
# Dependencies and application setup
# Health checks and graceful shutdown
# Environment-specific configurations
```

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

### Initialize Database

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/troubleshooting/troubleshooting.md

Run this command to initialize the database if it's missing tables.

```python
python -c "
from src.db.init_db import init_db
init_db()
print('✅ Database initialized')
"
```

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

### Initialize Database and Default Agents

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/getting_started.md

Run a Python script to initialize the database schema and set up default agents.

```python
from src.db.init_db import init_db
init_db()
print('✅ Database initialized successfully')
```

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

### Initialize Database and Agents

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/README.md

Run a Python script to initialize the database schema and set up default agents.

```python
from src.db.init_db import init_db
init_db()
print('✅ Database and agents initialized successfully')
```

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

### React TypeScript Component Example

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/CONTRIBUTING.md

Example of a React functional component written in TypeScript, including an interface for props and default prop values.

```typescript
interface UserProps {
  name: string;
  email: string;
  role?: 'admin' | 'user';
}

const User: React.FC<UserProps> = ({ name, email, role = 'user' }) => {
  return (
    <div className="user-card">
      <h2>{name}</h2>
      <p>{email}</p>
      <span>{role}</span>
    </div>
  );
};
```

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

### Initialize Default Agents

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/troubleshooting/troubleshooting.md

Run this command to populate the database with default agent templates.

```python
python -m scripts.populate_agent_templates
print('✅ Default agents initialized')
"
```

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

### Build Frontend for Production

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Use this command to build the frontend application for production deployment. Ensure you are in the 'auto-analyst-frontend' directory.

```bash
cd auto-analyst-frontend
npm run build
```

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

### Run Development Server

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/README.md

Commands to start the development server for the Next.js project using different package managers. Open http://localhost:3000 to view the application.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun dev
```

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

### Get Default Dataset

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/session.md

Retrieves the default dataset configured for the application.

```APIDOC
## GET /api/default-dataset

### Description
Gets the default dataset.

### Method
GET

### Endpoint
/api/default-dataset

### Response
#### Success Response (200)
- **headers** (array of strings) - Column headers of the dataset
- **rows** (array of arrays) - Data rows of the dataset
- **name** (string) - Name of the dataset
- **description** (string) - Description of the dataset

### Response Example
```json
{
  "headers": ["column1", "column2", ...],
  "rows": [[val1, val2, ...], ...],
  "name": "Housing Dataset",
  "description": "A comprehensive dataset containing housing information..."
}
```
```

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

### Run API Documentation

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/README.md

Access the interactive API documentation by navigating to the specified local URL in your browser.

```bash
# Interactive documentation
open http://localhost:8000/docs
```

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

### Update PostgreSQL Connection String

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/troubleshooting/troubleshooting.md

Example of updating the DATABASE_URL for PostgreSQL connections.

```env
DATABASE_URL=postgresql://username:password@localhost:5432/auto_analyst
```

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

### Get Enabled Templates

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/features/default-agents.md

Retrieves a list of only the enabled templates for a specific user.

```APIDOC
## GET /templates/user/{user_id}/enabled

### Description
Retrieves a list of all templates that are currently enabled for the specified user.

### Method
GET

### Endpoint
/templates/user/{user_id}/enabled

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The unique identifier of the user.
```

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

### Free Trial Store Implementation

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/state-management/stores.md

Handles the state for a free trial, tracking queries used and the maximum allowed queries. This store is intended for development use only.

```typescript
// lib/store/freeTrialStore.ts
interface FreeTrialStore {
  queriesUsed: number
  maxQueries: number
  hasFreeTrial: () => boolean
  incrementQueries: () => void
  resetTrial: () => void
  getRemainingQueries: () => number
}

export const useFreeTrialStore = create<FreeTrialStore>()(
  persist(
    (set, get) => ({
      queriesUsed: 0,
      maxQueries: 0, // Disabled in production, configurable in development
      
      hasFreeTrial: () => {
        const { queriesUsed, maxQueries } = get()
        return queriesUsed < maxQueries
      },
      
      incrementQueries: () => {
        set((state) => ({
          queriesUsed: Math.min(state.queriesUsed + 1, state.maxQueries)
        }))
      },
      
      resetTrial: () => {
        set({ queriesUsed: 0 })
      },
      
      getRemainingQueries: () => {
        const { queriesUsed, maxQueries } = get()
        return Math.max(0, maxQueries - queriesUsed)
      },
    }),
    {
      name: 'free-trial-storage',
    }
  )
)
```

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

### GET /analytics/tiers/projections

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/analytics.md

Returns projections for cost and usage, broken down by model tiers.

```APIDOC
## GET /analytics/tiers/projections

### Description
Returns tier-based cost and usage projections.

### Method
GET

### Endpoint
/analytics/tiers/projections

### Response
#### Success Response (200)
- **daily_usage** (object) - Daily usage statistics.
- **projections** (object) - Projections for different timeframes.
  - **monthly** (object) - Monthly projections.
  - **quarterly** (object) - Quarterly projections.
  - **yearly** (object) - Yearly projections.
- **tier_definitions** (object) - Definitions of the available tiers.

### Response Example
```json
{
  "daily_usage": {},
  "projections": {
    "monthly": {},
    "quarterly": {},
    "yearly": {}
  },
  "tier_definitions": {}
}
```
```

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

### Initialize Backend Database

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Use this command to initialize the database schema for the backend. Ensure you are in the 'auto-analyst-backend' directory.

```bash
cd auto-analyst-backend
python -m src.db.init_db
```

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

### GET /analytics/costs/today

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/analytics.md

Retrieves the cost, token, and request data for the current day.

```APIDOC
## GET /analytics/costs/today

### Description
Returns today's cost data.

### Method
GET

### Endpoint
/analytics/costs/today

### Response
#### Success Response (200)
- **date** (string) - The current date in YYYY-MM-DD format.
- **cost** (number) - The total cost incurred today.
- **tokens** (integer) - The total number of tokens used today.
- **requests** (integer) - The total number of requests made today.

### Response Example
```json
{
  "date": "2023-05-01",
  "cost": 2.50,
  "tokens": 10000,
  "requests": 100
}
```
```

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

### Run Full Test Suite

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/development/development_workflow.md

Execute the complete test suite for the project.

```bash
pytest tests/
```

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

### Development Environment Configuration (.env.local)

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/development/environment-setup.md

Sets up environment variables for local development, including API URLs, authentication, trial limits, and optional email/Redis configurations.

```bash
# Development configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=development-secret-key-change-in-production
GOOGLE_CLIENT_ID=your-dev-google-client-id
GOOGLE_CLIENT_SECRET=your-dev-google-client-secret
NEXT_PUBLIC_ANALYTICS_ADMIN_PASSWORD=admin123
NEXT_PUBLIC_FREE_TRIAL_LIMIT=20000
NODE_ENV=development

# Email (optional in development)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-dev-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=dev@your-domain.com
SALES_EMAIL=dev@your-domain.com

# Redis (required)
UPSTASH_REDIS_REST_URL=your-redis-url
UPSTASH_REDIS_REST_TOKEN=your-redis-token
```

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

### Get User Preferences

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/features/default-agents.md

Retrieves the current template preferences for a specific user.

```APIDOC
## GET /templates/user/{user_id}

### Description
Retrieves the template preferences for a given user ID.

### Method
GET

### Endpoint
/templates/user/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The unique identifier of the user.
```

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

### Get Model Settings

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/session.md

Fetches the current configuration settings for the AI models.

```APIDOC
## GET /api/model-settings

### Description
Fetches current model settings.

### Method
GET

### Endpoint
/api/model-settings

### Response
#### Success Response (200)
- **provider** (string) - The AI model provider (e.g., "openai")
- **model** (string) - The specific model being used (e.g., "gpt-4o-mini")
- **hasCustomKey** (boolean) - Indicates if a custom API key is configured
- **temperature** (number) - The temperature setting for model generation
- **maxTokens** (integer) - The maximum number of tokens for model responses

### Response Example
```json
{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "hasCustomKey": true,
  "temperature": 1.0,
  "maxTokens": 6000
}
```
```

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

### Instantiate and Use data_maker Agent

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/test_datasets.ipynb

This snippet shows how to instantiate the `data_maker` agent, provide a user query and dataset descriptions, and obtain the generated SQL query. The `dataset_descriptions` are expected to be a string representation of the data context.

```python
data_maker_agent = dspy.Predict(data_maker)

user_query = "show me how much I made from Xperra"

dataset_descriptions = str(response.data_context)

sql = data_maker_agent(user_query=user_query, dataset_descriptions=dataset_descriptions)
```

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

### Get Only Enabled Templates

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/templates.md

Retrieves only the templates that are currently enabled for the specified user.

```APIDOC
## GET /templates/user/{user_id}/enabled

### Description
Retrieves only the templates that are currently enabled for the user.

### Method
GET

### Endpoint
/templates/user/{user_id}/enabled

### Parameters
#### Path Parameters
- **user_id** (integer) - Required - The ID of the user.
```

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

### Test with Sample Data

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/development/development_workflow.md

Run tests using a script with sample data.

```bash
python scripts/test_with_sample_data.py
```

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

### Generate Dataset Description from Preview

Source: https://context7.com/firebird-technologies/auto-analyst/llms.txt

Sends a data sample to an agent to create a structured JSON description of columns, types, and usage notes. Requires headers, rows, and optional description and name for the dataset.

```bash
curl -X POST http://localhost:8000/generate-description-from-preview \
  -H "Content-Type: application/json" \
  -d '{ 
    "headers": ["date", "region", "revenue"], 
    "rows": [ 
      ["2024-01-01", "North", 120000], 
      ["2024-01-01", "South", 85000] 
    ], 
    "description": "Monthly regional sales", 
    "name": "sales_data" 
  }'
# → {"description": " exact_python_name: `sales_data` Dataset: {"exact": "sales_data", "description": "...", "columns": {...}}"}
```

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

### Get Template Categories List

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/templates.md

Retrieves a list of all available template categories.

```APIDOC
## GET /templates/categories/list

### Description
Retrieves a list of all available template categories.

### Method
GET

### Endpoint
/templates/categories/list

### Response
#### Success Response (200)
- **categories** (array of strings) - A list of category names.

### Response Example
```json
{
  "categories": [
    "Data Processing",
    "Machine Learning", 
    "Visualization",
    "Statistics"
  ]
}
```
```

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

### Credit Threshold Usage Examples

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/billing/credit-configuration.md

Demonstrates how to use utility functions to check if a plan appears unlimited based on credit total, determine if a low credit warning should be displayed, and format credit totals for user-friendly display.

```typescript
// Check if plan appears unlimited
const isUnlimited = CreditConfig.isUnlimitedTotal(999999) // true
```

```typescript
// Check if user should be warned
const shouldWarn = CreditConfig.shouldWarnLowCredits(400, 500) // true (80% used)
```

```typescript
// Format credits for display
const display = CreditConfig.formatCreditTotal(999999) // "Unlimited"
```

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

### Get Message Feedback

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/feedback.md

Retrieves the feedback associated with a specific AI-generated message.

```APIDOC
## GET /feedback/message/{message_id}

### Description
Retrieves feedback for a specific message.

### Method
GET

### Endpoint
/feedback/message/{message_id}

### Parameters
#### Path Parameters
- **message_id** (string) - Required - ID of the message to get feedback for

### Response
#### Success Response (200)
- **feedback_id** (integer) - Unique identifier for the feedback entry
- **message_id** (integer) - The ID of the message this feedback is associated with
- **rating** (integer) - The star rating provided (1-5)
- **feedback_comment** (string) - Any additional comment provided by the user (can be null)
- **model_name** (string) - The name of the AI model used
- **model_provider** (string) - The provider of the AI model
- **temperature** (number) - The temperature setting used for the model
- **max_tokens** (integer) - The maximum tokens setting used for the model
- **created_at** (string) - Timestamp when the feedback was created
- **updated_at** (string) - Timestamp when the feedback was last updated

#### Response Example
```json
{
    "feedback_id": 123,
    "message_id": 456,
    "rating": 5,
    "feedback_comment": null,
    "model_name": "gpt-4o-mini",
    "model_provider": "openai",
    "temperature": 0.7,
    "max_tokens": 6000,
    "created_at": "2023-05-01T12:00:00Z",
    "updated_at": "2023-05-01T12:00:00Z"
}
```

### Error Responses
- 404 Not Found: No feedback found for the specified message
- 500 Internal Server Error: Failed to retrieve feedback
```

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

### Agent Configuration Example

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/architecture/architecture.md

Illustrates the structure of the agents_config.json file, specifying default agents, premium templates, and agents to be removed. Customize this file to manage available agents.

```json
{
  "default_agents": [
    {
      "template_name": "preprocessing_agent",
      "description": "Data cleaning and preparation",
      "variant_type": "both",
      "is_premium": false,
      "usage_count": 0,
      "icon_url": "preprocessing.svg"
    }
  ],
  "premium_templates": [...],
  "remove": [...]
```

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

### Get Templates by Specific Category

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/templates.md

Retrieves a list of templates belonging to a specific category.

```APIDOC
## GET /templates/category/{category}

### Description
Retrieves a list of templates belonging to a specific category.

### Method
GET

### Endpoint
/templates/category/{category}

### Parameters
#### Path Parameters
- **category** (string) - Required - The name of the category to filter by.

### Response
#### Success Response (200)
- **template_id** (integer) - Unique identifier for the template.
- **template_name** (string) - The internal name of the template.
- **display_name** (string) - The user-facing name of the template.
- **description** (string) - A brief description of the template's purpose.
- **template_category** (string) - The category the template belongs to.
- **icon_url** (string) - URL to the template's icon.
- **usage_count** (integer) - Number of times the template has been used.

### Response Example
```json
[
  {
    "template_id": 1,
    "template_name": "preprocessing_agent",
    "display_name": "Data Preprocessing Agent",
    "description": "Handles data cleaning and preprocessing",
    "template_category": "Data Processing",
    "icon_url": "/icons/templates/preprocessing_agent.svg",
    "usage_count": 1234
  }
]
```
```

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

### Test Credit Configuration Changes

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/billing/credit-configuration.md

Run these commands to test credit and trial-related functionalities after making changes to the configuration.

```bash
# Test different scenarios
npm run test:credits
npm run test:trial-flows
```

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

### Get Template by ID

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/templates.md

Retrieves detailed information for a specific template using its ID.

```APIDOC
## GET /templates/template/{template_id}

### Description
Retrieves detailed information for a specific template using its ID.

### Method
GET

### Endpoint
/templates/template/{template_id}

### Parameters
#### Path Parameters
- **template_id** (integer) - Required - The unique identifier of the template to retrieve.

### Response
#### Success Response (200)
- **template_id** (integer) - Unique identifier for the template.
- **template_name** (string) - The internal name of the template.
- **display_name** (string) - The user-facing name of the template.
- **description** (string) - A brief description of the template's purpose.
- **prompt_template** (string) - The prompt structure used by the template.
- **template_category** (string) - The category the template belongs to.
- **icon_url** (string) - URL to the template's icon.
- **is_premium_only** (boolean) - Indicates if the template is premium only.
- **is_active** (boolean) - Indicates if the template is currently active.
- **usage_count** (integer) - Number of times the template has been used.
- **created_at** (string) - Timestamp when the template was created.
- **updated_at** (string) - Timestamp when the template was last updated.

### Response Example
```json
{
  "template_id": 1,
  "template_name": "preprocessing_agent",
  "display_name": "Data Preprocessing Agent",
  "description": "Handles data cleaning, missing values, and preprocessing tasks",
  "prompt_template": "You are a data preprocessing specialist...",
  "template_category": "Data Processing",
  "icon_url": "/icons/templates/preprocessing_agent.svg",
  "is_premium_only": false,
  "is_active": true,
  "usage_count": 1234,
  "created_at": "2023-05-01T12:00:00Z",
  "updated_at": "2023-05-01T12:00:00Z"
}
```
```

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

### Populate Agent Templates from Config

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/troubleshooting/troubleshooting.md

Execute this script to load agent templates from configuration files into the database.

```bash
python scripts/populate_agent_templates.py
```

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

### Get All Templates

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/templates.md

Retrieves a list of all available templates. Supports filtering by variant type.

```APIDOC
## GET /templates/

### Description
Retrieves a list of all available templates. Supports filtering by variant type.

### Method
GET

### Endpoint
/templates/

### Query Parameters
- **variant_type** (string) - Optional - Filter by "individual", "planner", or "all" (default: "all")

### Response
#### Success Response (200)
- **template_id** (integer) - Unique identifier for the template.
- **template_name** (string) - The internal name of the template.
- **display_name** (string) - The user-facing name of the template.
- **description** (string) - A brief description of the template's purpose.
- **prompt_template** (string) - The prompt structure used by the template.
- **template_category** (string) - The category the template belongs to.
- **icon_url** (string) - URL to the template's icon.
- **is_premium_only** (boolean) - Indicates if the template is premium only.
- **is_active** (boolean) - Indicates if the template is currently active.
- **usage_count** (integer) - Number of times the template has been used.
- **created_at** (string) - Timestamp when the template was created.
- **updated_at** (string) - Timestamp when the template was last updated.

### Response Example
```json
[
  {
    "template_id": 1,
    "template_name": "preprocessing_agent",
    "display_name": "Data Preprocessing Agent",
    "description": "Handles data cleaning, missing values, and preprocessing tasks",
    "prompt_template": "You are a data preprocessing specialist...",
    "template_category": "Data Processing",
    "icon_url": "/icons/templates/preprocessing_agent.svg",
    "is_premium_only": false,
    "is_active": true,
    "usage_count": 12,
    "created_at": "2023-05-01T12:00:00Z",
    "updated_at": "2023-05-01T12:00:00Z"
  }
]
```
```

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

### Update Chat Response

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/chats.md

Example response after successfully updating a chat. Reflects the modified fields.

```json
{
  "chat_id": 456,
  "title": "Updated Chat Title",
  "created_at": "2023-05-01T12:00:00Z",
  "user_id": 123
}
```

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

### GET /analytics/feedback/summary

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/analytics.md

Returns a summary of feedback statistics, including rating distributions and trends over time.

```APIDOC
## GET /analytics/feedback/summary

### Description
Returns feedback summary statistics including rating distributions and trends.

### Method
GET

### Endpoint
/analytics/feedback/summary

### Query Parameters
- **period** (string) - Optional - Time period (`7d`, `30d`, `90d`, default: `30d`)

### Response
#### Success Response (200)
- **period** (string) - The time period for the data.
- **start_date** (string) - The start date of the data period.
- **end_date** (string) - The end date of the data period.
- **total_feedback** (integer) - Total number of feedback entries received.
- **avg_rating** (number) - The average rating from feedback.
- **chats_with_feedback** (integer) - The number of chats that included feedback.
- **ratings_distribution** (array) - Distribution of ratings (e.g., count for each star rating).
  - **rating** (integer) - The rating value (e.g., 1 to 5).
  - **count** (integer) - The number of times this rating was given.
- **models_data** (array) - Feedback statistics related to specific models.
- **feedback_trend** (array) - Trend data for feedback over the specified period.

### Response Example
```json
{
  "period": "30d",
  "start_date": "2023-04-01",
  "end_date": "2023-05-01",
  "total_feedback": 500,
  "avg_rating": 4.2,
  "chats_with_feedback": 200,
  "ratings_distribution": [
    {"rating": 1, "count": 10},
    {"rating": 2, "count": 20},
    {"rating": 3, "count": 50},
    {"rating": 4, "count": 200},
    {"rating": 5, "count": 220}
  ],
  "models_data": [],
  "feedback_trend": []
}
```
```

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

### Test Container Build

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/development/development_workflow.md

Build the Docker container for the backend service.

```bash
docker build -t auto-analyst-backend .
```

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

### Get Excel Sheet Names

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/session.md

Retrieves a list of all sheet names from an uploaded Excel file.

```APIDOC
## POST /api/excel-sheets

### Description
Gets the list of sheet names from an Excel file.

### Method
POST

### Endpoint
/api/excel-sheets

### Parameters
#### Request Body
- **file** (file) - Required - The Excel file to read sheet names from

### Response
#### Success Response (200)
- **sheets** (array of strings) - A list of sheet names found in the Excel file

### Response Example
```json
{
  "sheets": ["Sheet1", "Sheet2", "Data"]
}
```
```

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

### Configure Environment Variables

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/README.md

Create a .env file to configure database connection, AI model providers, API keys, and other application settings.

```env
# Database Configuration
DATABASE_URL=sqlite:///./chat_database.db

# AI Model Configuration
OPENAI_API_KEY=your-openai-api-key
MODEL_PROVIDER=openai  # openai, anthropic, groq, gemini
MODEL_NAME=gpt-4o-mini
TEMPERATURE=0.7
MAX_TOKENS=6000

# Optional: Additional AI Providers
ANTHROPIC_API_KEY=your-anthropic-key
GROQ_API_KEY=your-groq-key
GEMINI_API_KEY=your-gemini-key

# Security
ADMIN_API_KEY=your-admin-key

# Application Settings
ENVIRONMENT=development
FRONTEND_URL=http://localhost:3000/
```

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

### Get Templates by Category

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/templates.md

Retrieves templates grouped by category. Supports filtering by variant type.

```APIDOC
## GET /templates/categories

### Description
Retrieves templates grouped by category. Supports filtering by variant type.

### Method
GET

### Endpoint
/templates/categories

### Query Parameters
- **variant_type** (string) - Optional - Filter by "individual", "planner", or "all" (default: "individual")

### Response
#### Success Response (200)
- **category** (string) - The name of the category.
- **templates** (array) - A list of templates within this category.
  - **agent_id** (integer) - Unique identifier for the agent/template.
  - **agent_name** (string) - The internal name of the agent/template.
  - **display_name** (string) - The user-facing name of the agent/template.
  - **description** (string) - A brief description of the agent/template.
  - **icon_url** (string) - URL to the agent/template's icon.
  - **usage_count** (integer) - Number of times the agent/template has been used.

### Response Example
```json
[
  {
    "category": "Data Processing", 
    "templates": [
      {
        "agent_id": 1,
        "agent_name": "preprocessing_agent",
        "display_name": "Data Preprocessing Agent",
        "description": "Handles data cleaning and preprocessing",
        "icon_url": "/icons/templates/preprocessing_agent.svg",
        "usage_count": 1234
      }
    ]
  }
]
```
```

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

### Get Latest Code

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/code.md

Retrieves the latest version of code associated with a specific message ID.

```APIDOC
## POST /code/get-latest-code

### Description
Retrieves the latest code from a specific message.

### Method
POST

### Endpoint
/code/get-latest-code

### Parameters
#### Request Body
- **message_id** (integer) - Required - Message ID to retrieve code from

### Request Example
{
  "message_id": 123
}

### Response
#### Success Response (200)
- **code** (string) - The retrieved code

#### Response Example
{
  "code": "print(df.describe())"
}
```

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

### Get Chat Feedback

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/feedback.md

Retrieves all feedback entries for messages within a specific chat conversation.

```APIDOC
## GET /feedback/chat/{chat_id}

### Description
Retrieves all feedback for messages in a specific chat.

### Method
GET

### Endpoint
/feedback/chat/{chat_id}

### Parameters
#### Path Parameters
- **chat_id** (string) - Required - ID of the chat to get feedback for

### Response
#### Success Response (200)
- Returns an array of feedback objects. Each object contains:
  - **feedback_id** (integer) - Unique identifier for the feedback entry
  - **message_id** (integer) - The ID of the message this feedback is associated with
  - **rating** (integer) - The star rating provided (1-5)
  - **feedback_comment** (string) - Any additional comment provided by the user (can be null)
  - **model_name** (string) - The name of the AI model used
  - **model_provider** (string) - The provider of the AI model
  - **temperature** (number) - The temperature setting used for the model
  - **max_tokens** (integer) - The maximum tokens setting used for the model
  - **created_at** (string) - Timestamp when the feedback was created
  - **updated_at** (string) - Timestamp when the feedback was last updated

#### Response Example
```json
[
    {
        "feedback_id": 123,
        "message_id": 456,
        "rating": 5,
        "feedback_comment": null,
        "model_name": "gpt-4o-mini",
        "model_provider": "openai",
        "temperature": 0.7,
        "max_tokens": 6000,
        "created_at": "2023-05-01T12:00:00Z",
        "updated_at": "2023-05-01T12:00:00Z"
    }
]
```

### Note
Returns an empty array if no feedback exists for the chat.

### Error Responses
- 500 Internal Server Error: Failed to retrieve chat feedback
```

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

### Populate Backend Database with Agents

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/README.md

Use this command to fill the database with custom and default agents. Ensure you are in the 'auto-analyst-backend' directory.

```bash
cd auto-analyst-backend
python -m scripts.populate_agent_templates
```

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

### Add Missing Dependencies

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/troubleshooting/troubleshooting.md

Install a missing Python library using pip. This is a common solution for ModuleNotFoundError.

```bash
pip install missing_library
```

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

### Available npm Scripts for Development

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/docs/frontend.md

Common npm scripts for managing the development lifecycle, including starting the server, building for production, linting, and type checking.

```bash
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # ESLint code checking
npm run type-check   # TypeScript validation
```

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

### Create and Initialize Session

Source: https://context7.com/firebird-technologies/auto-analyst/llms.txt

Use `POST /generate-session` to create a new anonymous session, then `POST /initialize-session` to associate it with a user after authentication. The `session_id` from the first call is required for subsequent requests.

```bash
# 1. Create a session
curl -X POST http://localhost:8000/generate-session
# → {"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "message": "Session created successfully"}

SESSION="3fa85f64-5717-4562-b3fc-2c963f66afa6"

# 2. Initialize the session with user identity (after auth)
curl -X POST http://localhost:8000/initialize-session \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "'"$SESSION"'",
    "user_id": 42,
    "user_email": "alice@example.com",
    "user_name": "Alice"
  }'
# → {"status": "success", "session_id": "...", "message": "Session initialized successfully", "user_id": 42}
```

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

### Verify Environment Variables

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-frontend/docs/development/environment-setup.md

Runs the development server to check if environment variables are loaded correctly. Also shows how to check a specific environment variable in the browser console.

```bash
# Verify environment variables are loaded
npm run dev

# Check in browser console
console.log(process.env.NEXT_PUBLIC_API_URL)
```

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

### GET /analytics/code-executions/users

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/analytics.md

Returns code execution statistics grouped by user, showing usage patterns for each user.

```APIDOC
## GET /analytics/code-executions/users

### Description
Returns code execution statistics grouped by user.

### Method
GET

### Endpoint
/analytics/code-executions/users

### Query Parameters
- **period** (string) - Optional - Time period (`7d`, `30d`, `90d`, default: `30d`)
- **limit** (integer) - Optional - Maximum number of users to return (default: `50`).

### Response
#### Success Response (200)
- **period** (string) - The time period for the data.
- **start_date** (string) - The start date of the data period.
- **end_date** (string) - The end date of the data period.
- **users** (array) - An array of objects, where each object contains user-specific code execution statistics.

### Response Example
```json
{
  "period": "30d",
  "start_date": "2023-04-01",
  "end_date": "2023-05-01", 
  "users": []
}
```
```

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

### GET /analytics/code-executions/summary

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/analytics.md

Returns a summary of code execution statistics, including success rates and model performance.

```APIDOC
## GET /analytics/code-executions/summary

### Description
Returns code execution statistics including success rates and model performance.

### Method
GET

### Endpoint
/analytics/code-executions/summary

### Query Parameters
- **period** (string) - Optional - Time period (`7d`, `30d`, `90d`, default: `30d`)

### Response
#### Success Response (200)
- **period** (string) - The time period for the data.
- **start_date** (string) - The start date of the data period.
- **end_date** (string) - The end date of the data period.
- **overall_stats** (object) - Overall statistics for code executions.
  - **total_executions** (integer) - Total number of code executions.
  - **successful_executions** (integer) - Number of successful executions.
  - **failed_executions** (integer) - Number of failed executions.
  - **success_rate** (number) - The success rate of code executions.
  - **total_users** (integer) - Total number of unique users executing code.
  - **total_chats** (integer) - Total number of chats involving code execution.
- **model_performance** (array) - Performance metrics for different models used in code execution.
- **failed_agents** (array) - Information about agents that failed during code execution.

### Response Example
```json
{
  "period": "30d",
  "start_date": "2023-04-01",
  "end_date": "2023-05-01",
  "overall_stats": {
    "total_executions": 1000,
    "successful_executions": 950,
    "failed_executions": 50,
    "success_rate": 0.95,
    "total_users": 100,
    "total_chats": 200
  },
  "model_performance": [],
  "failed_agents": []
}
```
```

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

### API Welcome Information

Source: https://github.com/firebird-technologies/auto-analyst/blob/main/auto-analyst-backend/docs/api/routes/session.md

Returns basic welcome information about the API, including a list of available features.

```APIDOC
## GET /

### Description
Returns API welcome information and feature list.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **message** (string) - Welcome message.
- **features** (array) - List of available API features.
```