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

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

2. Environment Configuration

Option A: Interactive Setup (Recommended)

npm run env:setup

Option B: Manual Setup

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

3. Database Setup

npm run db:setup

4. Validate Configuration

npm run config:validate

5. Start Development Server

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
2. OpenAI API Key: Get from OpenAI Platform
3. SERP API Key: Get from SERP API

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