reason-flow/SETUP.md

# Reason Flow Setup Guide

This guide will help you set up the Reason Flow AI engineering reasoning system.

## Prerequisites

- Node.js (v16 or higher)
- PostgreSQL (v12 or higher)
- Git

## Quick Start

### 1. Clone and Install Dependencies

```bash
git clone <repository-url>
cd reason_flow
npm run install-all
```

### 2. Environment Configuration

#### Option A: Interactive Setup (Recommended)
```bash
npm run env:setup
```

#### Option B: Manual Setup
```bash
cp env.example .env
# Edit .env with your configuration
```

### 3. Database Setup

```bash
npm run db:setup
```

### 4. Validate Configuration

```bash
npm run config:validate
```

### 5. Start Development Server

```bash
npm run dev
```

## Detailed Setup

### Environment Variables

The system uses environment variables for configuration. Key variables include:

#### Required Variables
- `GROQ_API_KEY` - Your Groq API key for Kimi K2 model
- `DB_PASSWORD` - PostgreSQL database password
- `JWT_SECRET` - Secret key for JWT tokens

#### Optional Variables
- `OPENAI_API_KEY` - For additional AI capabilities
- `SERP_API_KEY` - For web search functionality
- `REDIS_URL` - For caching (optional)

### Database Configuration

The system supports multiple environments:

- **Development**: `reason_flow_dev`
- **Test**: `reason_flow_test`
- **Production**: `reason_flow_prod`

### API Keys Setup

1. **Groq API Key**: Get from [Groq Console](https://console.groq.com/)
2. **OpenAI API Key**: Get from [OpenAI Platform](https://platform.openai.com/)
3. **SERP API Key**: Get from [SERP API](https://serpapi.com/)

## Available Scripts

### Environment Management
- `npm run env:setup` - Interactive environment setup
- `npm run env:validate` - Validate environment configuration
- `npm run env:show` - Show current configuration

### Database Management
- `npm run db:setup` - Complete database setup
- `npm run db:init` - Initialize database
- `npm run db:reset` - Reset database
- `npm run db:migrate` - Run migrations
- `npm run db:seed` - Run seeders
- `npm run db:status` - Check database status
- `npm run db:info` - Show database information

### Development
- `npm run dev` - Start development server
- `npm run dev-full` - Start both backend and frontend
- `npm run test:groq` - Test Groq API integration

### Configuration
- `npm run config:validate` - Validate all configuration
- `npm run config:show` - Show current configuration

## Environment-Specific Configuration

### Development
- Debug mode enabled
- Verbose logging
- Relaxed rate limiting
- Hot reload enabled

### Production
- Debug mode disabled
- Optimized logging
- Strict rate limiting
- SSL recommended
- Security headers enabled

### Test
- Minimal logging
- Test database
- Mock external services

## Troubleshooting

### Common Issues

1. **Database Connection Failed**
   - Check PostgreSQL is running
   - Verify database credentials
   - Ensure database exists

2. **Groq API Errors**
   - Verify API key is correct
   - Check API quota and limits
   - Test connection: `npm run test:groq`

3. **Configuration Errors**
   - Run: `npm run config:validate`
   - Check required variables are set
   - Verify environment file exists

### Logs

- Application logs: `./logs/app.log`
- Error logs: `./logs/error.log`
- Combined logs: `./logs/combined.log`

### Health Checks

- API Health: `GET /api/health`
- Model Status: `GET /api/models/status`
- Database Status: `npm run db:status`

## Security Considerations

### Production Deployment

1. **Change Default Secrets**
   - Update JWT_SECRET
   - Change admin password
   - Use strong database passwords

2. **Enable SSL**
   - Set DB_SSL=true
   - Use HTTPS in production
   - Configure proper CORS origins

3. **Environment Variables**
   - Never commit .env files
   - Use secure secret management
   - Rotate keys regularly

## Monitoring

### Health Endpoints
- `/api/health` - Basic health check
- `/api/models/status` - Model status
- `/api/feedback/stats` - Feedback statistics

### Logging
- Structured JSON logging
- Log rotation configured
- Error tracking enabled

## Support

For issues and questions:
1. Check the logs for errors
2. Validate configuration
3. Test individual components
4. Review the troubleshooting section

## Next Steps

After setup:
1. Test the API endpoints
2. Upload sample documents
3. Create test conversations
4. Verify model responses
5. Set up monitoring